Créez une application de navigation iOS simple en Swift avec le SDK Navigation de Google Maps Platform

1. Avant de commencer

Cet atelier de programmation vous explique comment créer une application iOS simple qui utilise le SDK Navigation Google Maps Platform pour accéder à une destination préconfigurée.

Voici à quoi ressemblera votre application une fois que vous aurez terminé.

Prérequis

• Connaissances de base en développement d'applications iOS avec Swift.
• Vous devez connaître certains concepts de base du SDK Maps, comme créer une carte centrée sur un lieu spécifique.

Points abordés

• Découvrez comment créer une application iOS Swift simple qui utilise le SDK Navigation pour accéder à une destination.
• Comment intégrer le SDK Navigation à partir du dépôt Cocoapods distant.
• Découvrez comment gérer les autorisations d'accès à la position et le contrat utilisateur avec les conditions d'utilisation du SDK Navigation.
• Comment initialiser le SDK.
• Découvrez comment définir une destination et lancer la navigation.

Prérequis

• La dernière version stable de Xcode.
• Un compte Google et un projet pour lesquels la facturation est activée.
• Un appareil iOS ou un appareil émulé exécuté dans le simulateur Xcode. Quelle que soit la méthode choisie, elle doit répondre aux exigences minimales du SDK Navigation.

2. Configuration

Si vous ne disposez pas encore d'un compte Google Cloud Platform et d'un projet pour lequel la facturation est activée, configurez votre projet Google Cloud en suivant les instructions de la page Premiers pas avec Google Maps Platform.

Sélectionner un projet Google Cloud dans la console

Dans la console Cloud, cliquez sur le menu déroulant des projets, puis sélectionnez celui que vous souhaitez utiliser pour cet atelier de programmation.

Remarque : L'utilisation du SDK Navigation n'est pas couverte par le crédit mensuel récurrent de 200 $de Google Maps Platform, mais les 1 000 premières destinations par mois ne sont pas facturées.

Activer le SDK Navigation dans votre projet

Activez les API et les SDK Google Maps Platform requis pour cet atelier de programmation depuis Google Cloud Marketplace.

Dans la console Google Cloud, accédez à API et services > Bibliothèque, puis recherchez "Navigation SDK".

Un résultat de recherche devrait s'afficher.

Cliquez sur SDK Navigation pour ouvrir la page d'informations sur le produit. Cliquez sur Activer pour activer le SDK dans votre projet.

Répétez cette procédure pour le SDK Google Maps pour iOS.

Créer une clé API

Générez une clé API sur la page Identifiants de Cloud Console. Toutes les requêtes envoyées à Google Maps Platform nécessitent une clé API. Sur la page "Identifiants" de la console. Cliquez sur "+ Créer des identifiants" en haut de la page, puis sélectionnez "Clé API" parmi les options.

Pour une utilisation en production, il est recommandé de définir une restriction d'application pour votre clé API, mais cela est facultatif pour cet atelier de programmation.

3. Obtenir les fichiers de l'exemple de projet

Cette section explique comment configurer un projet d'application Xcode vide de base en clonant les fichiers du dépôt GitHub pour cet atelier de programmation. Le dépôt GitHub contient les versions avant et après du code de l'atelier de programmation. L'atelier de programmation commencera par un modèle de projet vide et se terminera par l'état final. Si vous êtes bloqué, vous pouvez utiliser le projet terminé dans le dépôt comme référence.

Cloner le dépôt ou télécharger le code

Accédez au répertoire dans lequel vous souhaitez stocker l'atelier de programmation.

Clonez ensuite le dépôt ou téléchargez le code :

git clone https://github.com/googlemaps-samples/codelab-navigation-101-ios-swift

Si git n'est pas installé, cliquez sur ce bouton pour obtenir le code :

Obtenir le code

Pour vous permettre de commencer rapidement, le dépôt contient du code de démarrage dans le dossier Starter qui vous aidera à suivre cet atelier de programmation. Un projet Solution terminé est également disponible si vous souhaitez passer directement à la suite ou vérifier votre progression à tout moment. Pour utiliser le projet de solution, vous devez suivre les instructions d'installation à l'aide de CocoaPods ci-dessous, puis exécuter la commande "pod update" à partir du dossier solution/Navigation SDK Codelab.

Une fois le dépôt cloné en local, utilisez Xcode pour ouvrir le dossier Starter en tant que projet existant. Vérifiez que le projet est compilé et exécuté.

Remarque : Le projet de cet atelier de programmation est écrit en Swift avec UIKit.

Connecter un appareil ou configurer le simulateur Xcode

4. Ajouter le SDK Navigation à votre application

Il existe trois façons d'intégrer le SDK Navigation à un projet Xcode. Cet atelier de programmation utilise CocoaPods. Pour savoir comment intégrer le SDK à l'aide de Swift Package Manager ou l'installer manuellement en le téléchargeant, consultez Créer le projet Xcode et installer le SDK Navigation dans la documentation du SDK Navigation.

Installer à l'aide de CocoaPods

Si vous ne possédez pas encore l'outil CocoaPods, installez-le sur macOS en exécutant la commande ci-dessous à partir du terminal. Pour en savoir plus, consultez le guide de démarrage de CocoaPods.

sudo gem install cocoapods

Créez un fichier nommé "Podfile" dans le dossier de votre projet, à l'intérieur du dossier de l'atelier de programmation starter/Navigation SDK (dans Xcode, Fichier > Nouveau > Fichier > Autre > Vide, enregistrez-le sous le nom "Podfile").

Ajoutez le contenu suivant à votre Podfile :

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '15.0'

target 'Navigation SDK Codelab' do
  pod 'GoogleNavigation', '9.1.1'
end

Économisez Podfile.

Ouvrez un terminal et accédez au répertoire dans lequel vous avez enregistré votre fichier Podfile (il doit s'agir du dossier "starter/Navigation SDK Codelab" dans le dépôt de l'atelier de programmation).

cd "<path-to-starter-project-folder>/Navigation SDK Codelab"

Exécutez la commande pod install. Cela installe les API spécifiées dans le Podfile, ainsi que toutes les éventuelles dépendances.

pod install

Fermez Xcode, puis ouvrez le fichier .xcworkspace de votre projet pour lancer Xcode. À partir de ce moment, vous devez utiliser le fichier .xcworkspace pour ouvrir le projet.

Vérifiez qu'un répertoire "Pods" a été ajouté à la structure du projet et qu'il contient les pods "GoogleMaps" et "GoogleNavigation".

Ajouter votre clé API

Ajoutez votre clé API à votre fichier AppDelegate.swift comme suit :

1. Ajoutez les instructions d'importation suivantes :

import GoogleMaps
import GoogleNavigation

2. Ajoutez les éléments suivants à votre méthode application(_:didFinishLaunchingWithOptions:) :

GMSServices.provideAPIKey("YOUR_API_KEY")

Remplacez "YOUR_API_KEY" par la clé API que vous avez créée à l'étape précédente.

Compilez votre projet et corrigez les erreurs.

5. Configurer les autorisations de l'application

Le SDK Navigation dépend des signaux GPS pour fournir une position sur la route et des instructions détaillées. Votre application devra donc demander à l'utilisateur d'autoriser l'accès aux données de localisation précises.

Pour ce faire, vous allez ajouter des propriétés au fichier Info.plist de votre application dans Xcode, ajouter du code à votre application pour demander l'autorisation à l'utilisateur au moment de l'exécution et gérer les erreurs telles que l'autorisation non accordée ou la position indisponible.

Ouvrez Info.plist dans Xcode. L'aperçu devrait ressembler à ceci.

Demander l'autorisation d'accéder à la position exacte

Pour ajouter des valeurs, pointez sur la ligne "Liste des propriétés d'informations" jusqu'à ce que l'icône + s'affiche. Cliquez sur le signe "+" pour afficher une boîte de dialogue avec des noms de propriétés suggérés. Notez que vous pouvez également ajouter des propriétés manuellement.

Ajoutez les propriétés et valeurs suivantes à Info.plist :

Propriété	Valeur
Confidentialité : description de l'utilisation de la localisation "Toujours" et "Lorsque l'appli est en cours d'utilisation"	"Cette application nécessite la position de votre appareil pour fournir une navigation détaillée."
Confidentialité - Description de l'utilisation de la position "Lorsque l'appli est en cours d'utilisation"	"Cette application nécessite la position de votre appareil pour fournir une navigation détaillée."
allowsBackgroundLocationUpdates	OUI

Demander l'autorisation d'accéder à la position en arrière-plan

Ajoutez les propriétés et valeurs suivantes à Info.plist :

UIBackgroundModes > Ajouter une ligne > Item 0: App registers for location updates (sélectionnez cette valeur dans la liste déroulante des suggestions)

Une fois que vous avez terminé, Info.plist doit se présenter comme suit.

Demander l'accès à la position au moment de l'exécution

Ajoutez les instructions d'importation suivantes à ViewController.swift :

import GoogleNavigation

Ajoutez la déclaration suivante à votre classe ViewController :

var locationManager: CLLocationManager!

Ajoutez un remplacement de méthode pour loadView() et appelez locationManager.requestAlwaysAuthorization() :

override func loadView() {
        locationManager = CLLocationManager()
        locationManager.requestAlwaysAuthorization()

Votre application demandera désormais la position de l'utilisateur et la mettra à sa disposition s'il accorde l'autorisation .

Demander l'autorisation d'afficher les notifications

Ajoutez le code suivant à loadView() pour demander à l'utilisateur l'autorisation d'afficher des notifications, ce qui sera nécessaire pour afficher les instructions de manœuvre de navigation.

UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
        granted, error in
        // Handle denied authorization to display notifications.
          if !granted || error != nil {
              print("User rejected request to display notifications.")
          }
        }

Créez et exécutez l'application, puis vérifiez que vous êtes invité à partager votre position et à activer les notifications.

6. Ajouter une interface utilisateur de navigation

Dans cette étape, vous allez ajouter une carte et la configurer pour qu'elle affiche un lieu. Vous afficherez ensuite une boîte de dialogue contenant les conditions d'utilisation du SDK Navigation.

Ajouter une vue de carte à votre application

Ajoutez cette ligne pour déclarer une variable GMSMapView dans votre ViewController.

var mapView: GMSMapView!

Ajoutez le code suivant à loadView() dans votre Viewcontroller.swift pour initialiser la carte.

let camera = GMSCameraPosition.camera(withLatitude: 51.483174, longitude: -0.177369, zoom: 14)
let options = GMSMapViewOptions()
options.camera = camera
options.frame = .zero
        
mapView = GMSMapView(options: options)
view = mapView

Après avoir compilé et exécuté votre application, vous devriez voir une carte centrée sur le sud-ouest de Londres.

Conseil : Pour obtenir d'autres coordonnées de latitude et de longitude à utiliser comme point de départ, effectuez un clic droit sur n'importe quel lieu dans Google Maps sur un navigateur, ou appuyez de manière prolongée sur la carte dans l'application mobile Google Maps, puis copiez ou notez les coordonnées.

Afficher la boîte de dialogue des conditions d'utilisation du SDK Navigation

Ajoutez le code suivant à ViewController.swift dans la même méthode loadView() que le code précédent. Les conditions d'utilisation du SDK Navigation pour les utilisateurs finaux s'affichent. Si vous ne l'acceptez pas, la navigation ne sera pas activée.

// Show the terms and conditions.
let companyName = "Navigation SDK Codelab"
GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(withCompanyName: companyName) { termsAccepted in
  if termsAccepted {
    // Enable navigation if the user accepts the terms.
    self.mapView.isNavigationEnabled = true
    // Request authorization for alert notifications which deliver guidance instructions
    // in the background.
  } else {
    // Handle the case when the user rejects the terms and conditions.
  }
}

Compilez et exécutez l'application pour afficher la boîte de dialogue.

7. Ajouter des écouteurs pour les événements de navigation clés

Cette étape vous montre comment configurer des écouteurs pour les événements clés, tels que l'arrivée à destination ou le changement d'itinéraire du conducteur.

Pour écouter ces événements, votre contrôleur de vue doit adopter le protocole GMSNavigatorListener.

Ajoutez ce protocole à la définition de classe dans ViewController.swift.

class ViewController: UIViewController,
                      GMSNavigatorListener {

Ajoutez maintenant une ligne de code pour configurer l'écouteur dans loadView():.

// Add a listener for GMSNavigator.
mapView.navigator?.add(self)

Enfin, ajoutez deux méthodes à votre classe pour gérer les événements déclenchés.

// Listener to handle arrival events.
func navigator(_ navigator: GMSNavigator, didArriveAt waypoint: GMSNavigationWaypoint) {
  print("You have arrived at: \(waypoint.title)")
}

// Listener for route change events.
func navigatorDidChangeRoute(_ navigator: GMSNavigator) {
  print("The route has changed.")
}

8. Définir une destination et lancer le guidage

Cette section vous explique comment définir une destination et démarrer le guidage.

Créez une fonction pour la logique de navigation.

Commencez par ajouter une fonction appelée startNav() à votre ViewController. Il contiendra la logique permettant de définir une destination et de lancer la navigation.

Remarque : L'attribut @objc est nécessaire pour rendre la méthode disponible pour le code Objective-C et éviter de déclencher une erreur de compilation après avoir ajouté du code qui appelle le SDK Navigation.

// Create a route and start guidance.
@objc func startNav() {
}

Créez un Waypoint pour la destination.

Ensuite, créez un tableau de destinations avec un seul point de cheminement.

Conseil : Utilisez un ID de lieu pour le point de repère. L'utilisation d'un ID de lieu permet au SDK Navigation de choisir le meilleur emplacement pour la destination. Pour trouver des ID de lieu, vous pouvez utiliser l'application Place ID Finder ou l'API Places Google Maps Platform pour rechercher des lieux.

// Create a route and start guidance.
@objc func startNav() {
  var destinations = [GMSNavigationWaypoint]()
  destinations.append(
    GMSNavigationWaypoint.init(
      placeID: "ChIJH-tBOc4EdkgRJ8aJ8P1CUxo",
      title: "Trafalgar Square")!)
}

Appelez setDestinations()et gérez la réponse.

Appelez ensuite setDestinations et gérez le GMSRouteStatus renvoyé.

Si GMSRouteStatus est défini sur "OK", lancez le guidage en définissant isGuidanceActive=true sur l'objet navigator de mapView. Sinon, affichez une instruction pour indiquer qu'une erreur s'est produite.

Si la valeur GMSRouteStatus renvoyée est "OK", commencez à simuler la conduite sur l'itinéraire en appelant mapView.locationSimulator.simulateLocationsAlongExistingRoute().

// Create a route and start guidance.
@objc func startNav() {
  var destinations = [GMSNavigationWaypoint]()
    destinations.append(
      GMSNavigationWaypoint.init(
        placeID: "ChIJH-tBOc4EdkgRJ8aJ8P1CUxo",
          title: "Trafalgar Square")!)
      
  mapView.navigator?.setDestinations(
    destinations
  ) { routeStatus in
    guard routeStatus == .OK else {
      print("Handle route statuses that are not OK.")
      return
    }
    //If routeStatus is OK, start guidance.
    self.mapView.navigator?.isGuidanceActive = true
    //start simulating driving along the route. self.mapView.locationSimulator?.simulateLocationsAlongExistingRoute()
    self.mapView.cameraMode = .following
  }
}

Gérer les codes d'erreur courants

Il est utile de gérer les erreurs GMSRouteStatus de manière plus explicite, en particulier lors du débogage des problèmes initiaux de votre nouvelle application. Par exemple, vous pouvez constater que vous obtenez plus fréquemment des erreurs d'autorisation de localisation, de clé API ou de "route introuvable" au début en raison de votre configuration de débogage. Il peut donc être utile de gérer ces états d'erreur.

Ajoutez du code qui gère ces cas spécifiques et imprime une instruction dans la console.

mapView.navigator?.setDestinations(
  destinations
) { routeStatus in
    guard routeStatus == .OK else {
      print("Handle route statuses that are not OK.")
      switch routeStatus {
       case .locationUnavailable:
        print("Location unavailable.") //check permissions
      case .noRouteFound:
        print("No route found.") //check start location and destination
      case .waypointError:
        print("Waypoint error") //check Place ID
      default:
        print("Not sure what happened")
      }
    return
  }

Ajouter un bouton pour lancer les instructions de navigation

Enfin, ajoutez un bouton à l'UI et associez-le à la méthode startNav. Créez une méthode appelée makeButton() avec le code suivant. Appelez votre fonction makeButton() à partir de loadView().

// Add a button to the view.
func makeButton() {
  // A button to start navigation.
  let navButton = UIButton(frame: CGRect(x: 5, y: 150, width: 200, height: 35))
  navButton.backgroundColor = .blue
  navButton.alpha = 0.5
  navButton.setTitle("Start navigation", for: .normal)
  navButton.addTarget(self, action: #selector(startNav), for: .touchUpInside)
  self.mapView.addSubview(navButton)
}

Créez et exécutez votre application.

Remarque : l'exécution du code dans

startNav()

appellera le

setDestinations()

, qui entraîne des frais après les 1 000 premières destinations utilisées. Pour en savoir plus, consultez Utilisation et facturation.

Conseil : Définissez un nouveau lieu de départ par défaut pour le simulateur Xcode en sélectionnant "Features" (Fonctionnalités) > "Location" (Position) > "Custom Location" (Position personnalisée) dans le menu du simulateur, ou ajoutez du code pour simuler la position avec le SDK Navigation en appelant la méthode mapview.locationSimulator?.simulateLocationAt() dans votre fonction startNav().

9. Félicitations !

Bravo, vous êtes arrivé à destination !

Vous avez créé une application simple qui fournit des instructions de navigation détaillées vers une destination à l'aide du SDK Navigation Google Maps Platform.

Vous avez configuré les autorisations de l'application et la boîte de dialogue des conditions d'utilisation du SDK Navigation, et vous avez spécifié une destination à l'aide d'un ID de lieu. Vous avez géré différents états de réussite et d'erreur dans votre application.

10. Aller plus loin

Si vous souhaitez aller plus loin dans le développement d'applications, consultez les rubriques suivantes pour trouver l'inspiration.

• Écoutez d'autres événements de navigation. Ajoutez du code pour afficher un message si le temps ou la distance restants dépassent un seuil.
• Personnalisez l'interface de navigation.
• Si vous souhaitez relever un défi plus important, essayez d'ajouter un sélecteur de lieu de l'API Places pour permettre à l'utilisateur de définir la destination. Remarque : Les applications de démonstration du SDK Navigation contiennent un exemple d'implémentation. Exécutez pod try GoogleNavigation dans le dossier de votre projet pour afficher le code.