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 dans Swift.
• Connaissances de base du SDK Google Maps, comme la création d'une carte centrée sur un lieu spécifique.

Points abordés

• Créer une application iOS Swift simple qui utilise le SDK Navigation pour accéder à une destination.
• Intégrer le SDK Navigation à partir du dépôt Cocoapods distant.
• Gérer les autorisations d'accès à la position et l'accord de l'utilisateur avec les conditions d'utilisation du SDK Navigation.
• Initialiser le SDK.
• Définir une destination et démarrer les instructions de 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. Quel que soit votre choix, il 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 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 le Google Cloud Marketplace.

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

Vous devriez voir un résultat de recherche.

Cliquez sur SDK Navigation pour ouvrir la page Détails du 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" dans 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 des fichiers à partir 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 finalisé 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 aider à démarrer rapidement, le dépôt contient du code de démarrage dans le dossier Starter pour vous aider à suivre cet atelier de programmation. Il existe également un projet Solution finalisé si vous souhaitez passer à l'étape suivante 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 que vous avez cloné le dépôt localement, 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 dans 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 plus de détails, consultez le guide de démarrage de CocoaPods.

sudo gem install cocoapods

Créez un fichier nommé Podfile dans le dossier de votre projet, dans le dossier starter/Navigation SDK Codelab (dans XCode, Fichier > Nouveau > Fichier > Autre > Vide, enregistrez-le sous "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

Enregistrez Podfile.

Ouvrez un terminal et accédez à l'emplacement où vous avez enregistré votre 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 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 précise et des instructions détaillées. Votre application devra donc demander à l'utilisateur d'accorder 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 vos applications 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 le refus d'autorisation ou l'indisponibilité de la position.

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

Demander l'autorisation d'accéder à la position précise

Vous pouvez ajouter de nouvelles valeurs en plaçant le pointeur de la souris sur la ligne "Information Property List" jusqu'à ce qu'une icône "+" s'affiche. Cliquez sur le "+" pour afficher une boîte de dialogue contenant 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
Privacy - Location Always And When In Use Usage Description	"This app requires your device location in order to provide turn-by-turn navigation"
Privacy - Location When In Use Usage Description	"This app requires your device location in order to provide turn-by-turn navigation"
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é, le fichier 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 à l'utilisateur et la mettra à disposition de votre application 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 les notifications, qui seront nécessaires pour afficher les instructions 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.")
          }
        }

Compilez 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

À cette étape, vous allez ajouter une carte et la configurer pour afficher 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

Compilez et exécutez votre application. Vous devriez voir une carte centrée sur le sud-ouest de Londres.

Conseil : Pour obtenir une latitude et une longitude différentes à utiliser comme point de départ, faites un clic droit sur n'importe quel lieu dans Google Maps dans un navigateur ou appuyez longuement 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 produit 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 l'utilisateur final s'affichent. Si elles ne sont pas acceptées, 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 explique 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 la 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 démarrer les instructions

Cette section vous explique comment définir une destination et démarrer les instructions de navigation.

Créer une fonction pour la logique de navigation

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

Remarque : L'attribut @objc est requis 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éer un Waypoint pour la destination

Créez ensuite un tableau de destinations avec un seul point de repère.

Conseil : Utilisez un ID de lieu pour le point de repère. L'utilisation d'ID de lieu permet au SDK Navigation de déterminer le meilleur itinéraire 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")!)
}

Appeler setDestinations()et gérer la réponse

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

Si le GMSRouteStatus est "OK", démarrez les instructions en définissant isGuidanceActive=true sur l'objet navigator de mapView. Sinon, affichez une instruction indiquant 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 états 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 constaterez peut-être que vous obtenez plus fréquemment des erreurs d'autorisation d'accès à la position, de clé API ou de "no route found" (aucun itinéraire trouvé) 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 affiche 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 démarrer les instructions de navigation

Enfin, ajoutez un bouton à l'interface utilisateur et connectez-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)
}

Compilez et exécutez votre application.

Remarque : L'exécution du code dans

startNav()

appellera la

setDestinations()

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

Conseil : Définissez un nouveau point de départ par défaut pour le simulateur XCode en sélectionnant Features > Location > Custom Location (Fonctionnalités > Position > 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 pour l'utilisateur final, 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 développer davantage votre application, consultez les articles suivants pour vous inspirer.

• É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. Astuce : Les applications de démonstration du SDK Navigation comportent un exemple d'implémentation. Exécutez pod try GoogleNavigation dans le dossier de votre projet pour afficher le code.