Créer une application de navigation Android simple avec le SDK Navigation Google Maps Platform

Créer une application de navigation Android simple avec le SDK Navigation Google Maps Platform

À propos de cet atelier de programmation

Dernière mise à jour : oct. 10, 2024

Rédigé par Ed Boiling

1. Avant de commencer

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

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

Prérequis

• Vous disposez de connaissances de base en développement d'applications Android en Kotlin.
• Connaître les concepts de base du SDK Google Maps, tels que les cartes, les lieux et les coordonnées

Points abordés

• Créer une application Android simple qui utilise le SDK Navigation pour accéder à une destination
• Intégrer le SDK Navigation à partir du dépôt Maven de Google à distance
• Gérer les autorisations d'accéder à la position et le contrat utilisateur avec les conditions d'utilisation du SDK Navigation
• Initialiser le SDK
• Définir une destination et démarrer le guidage de la navigation

Prérequis

• La dernière version stable d'Android Studio installée Cet atelier de programmation a été créé à l'aide d'Android Studio Jellyfish. Si vous utilisez une autre version, l'apparence et la mise en page de l'interface et des composants peuvent varier.
• Un compte Google et un projet avec la facturation activée.
• Un appareil Android en mode développeur avec le débogage USB activé ou un émulateur Android. Quel que soit votre choix, il doit respecter les conditions minimales requises pour le SDK Navigation.

Remarque: L'utilisation du SDK Navigation n'est pas couverte par le crédit mensuel récurrent de 200 $de Google Maps Platform. Toutefois, les 1 000 premières destinations par mois n'engendreront aucuns frais. Pour en savoir plus, consultez la page Utilisation et facturation.

2. Configuration

Si vous ne possédez pas encore de 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" https://developers.google.com/maps/gmp-get-started.

Sélectionnez votre projet Google Cloud dans la console.

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

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.

Accéder aux API Services > dans la console Google Cloud, puis recherchez "Navigation SDK".

Un résultat de recherche devrait s'afficher.

Cliquez sur le résultat du SDK Navigation pour ouvrir la page d'informations sur le produit. Cliquez sur le bouton "Activer" pour activer le SDK dans votre projet.

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

Remarque: Le SDK Navigation inclut une version du SDK Google Maps pour Android. Vous n'avez donc pas besoin de le configurer séparément. Ajouter le SDK Android Google Maps en tant que dépendance distincte entraînera des erreurs de compilation.

Créer une clé API

Générez une clé API sur la page Identifiants de Cloud Console. Vous pouvez suivre la procédure décrite à l'étape 3 de la section du guide de démarrage rapide sur la page Premiers pas avec Google Maps Platform. Toutes les requêtes envoyées à Google Maps Platform nécessitent une clé API.

3. Obtenir les fichiers d'exemple de projet

Cette section explique comment configurer un projet Android Studio vide de base en clonant des fichiers à partir du dépôt GitHub de cet atelier de programmation. Le dépôt GitHub contient les versions avant et après le code de l'atelier de programmation. L'atelier de programmation démarrera avec un modèle de projet vide, puis se terminera à l'état "Terminé". Si vous rencontrez des difficultés, vous pouvez utiliser le projet terminé comme référence dans le dépôt.

Clonez ce dépôt GitHub pour obtenir le code de cet atelier de programmation.

git clone https://github.com/googlemaps-samples/codelab-navigation-101-android-kotlin.git

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

Obtenir le code

Pour vous permettre de commencer rapidement cet atelier de programmation, le dépôt contient un code de démarrage dans le dossier Starter. Le projet de démarrage fournit une UI d'application de base et une configuration de compilation, mais le SDK Navigation n'y est pas ajouté. Il existe également un projet Solution terminé au cas où vous voudriez avancer ou vérifier votre progression à tout moment.

Ouvrir le dépôt cloné dans Android Studio

Une fois le dépôt cloné en local, utilisez Android Studio pour ouvrir le dossier Starter en tant que projet existant.

1. Dans la boîte de dialogue "Bienvenue dans Android Studio", cliquez sur le bouton "Ouvrir".
2. Accédez au dossier dans lequel vous avez enregistré le dépôt cloné, puis sélectionnez le dossier Starter dans le dossier racine codelab-navigation-101-android-kotlin.
3. Vérifiez que le projet est compilé et exécuté.

Remarque: Le projet de cet atelier de programmation est écrit en Kotlin.

Ajouter un appareil virtuel ou connecter un appareil physique

Pour connecter un appareil Android à votre ordinateur, suivez les instructions d'Android Studio pour exécuter des applications sur un appareil. Vous pouvez également configurer un appareil virtuel à l'aide d'AVD (Android Virtual Device) Manager. Lorsque vous choisissez un émulateur, assurez-vous de sélectionner une image qui inclut les API Google.

Dans Android Studio, cliquez sur l'option de menu "Run" (Exécuter) ou sur l'icône du bouton de lecture. Choisissez un appareil lorsque vous y êtes invité.

4. Ajouter le SDK Navigation à votre application

Ajouter la bibliothèque du SDK Navigation et votre clé API à votre projet

Remarque : le projet du dépôt utilise le DSL Kotlin pour les fichiers de compilation, tandis que les applications de démonstration du SDK Nav utilisent le DSL Groovy. La syntaxe a été migrée, mais vous remarquerez peut-être de légères différences dans la façon dont Kotlin spécifie les éléments. Consultez le guide de migration pour comprendre les différences.

Pour ajouter la bibliothèque du SDK Navigation à votre application, vous devez modifier votre build.gradle.kts au niveau de l'application afin d'extraire le SDK Navigation à partir du dépôt Maven de Google et de configurer un numéro de version.

Créez une variable dans votre configuration de compilation pour stocker le numéro de version du SDK Navigation.

Configurez une variable dans votre build.gradle.kts au niveau de l'application pour qu'elle contienne la valeur de la version du SDK Navigation utilisée dans votre application. Vous pourrez ainsi passer facilement à la dernière version à l'avenir.

Consultez les notes de version du SDK Navigation pour connaître le numéro de version le plus récent.

val navSdkVersion by extra("6.0.0")

Vous pouvez également modifier les valeurs de cette variable et d'autres à l'aide de la boîte de dialogue qui se trouve sous Fichier > Structure du projet > Variables:

Ajouter une dépendance à la configuration de compilation

Ajoutez maintenant la dépendance d'API suivante au bloc de dépendances dans votre fichier build.gradle.kts. au niveau de l'application. La version utilisée sera la valeur de ${navSdkVersion} que vous venez de définir dans votre fichier build.gradle.kts au niveau de l'application :

dependencies {

   // Include the Google Navigation SDK.
   api("com.google.android.libraries.navigation:navigation:${navSdkVersion}")

...

Ajouter votre clé API

Utiliser le plug-in Secrets Gradle pour gérer la clé API

Nous vous recommandons d'utiliser le plug-in Secrets Gradle pour gérer de manière sécurisée la clé API dans votre application. Le plug-in a été ajouté au modèle initial du projet en tant que dépendance dans votre fichier build.gradle.kts de premier niveau.

// Top-level build file where you can add configuration options common to all sub-projects/modules.
plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
    //... other plugin definitions here
}

Ouvrez le fichier secrets.properties dans votre répertoire de premier niveau, puis remplacez YOUR_API_KEY par votre clé API. Stockez votre clé dans ce fichier, car secrets.properties n'est pas vérifié dans un système de contrôle des versions.

MAPS_API_KEY=YOUR_API_KEY

Pour en savoir plus sur ce sujet, consultez Ajouter la clé API à votre application dans la documentation du SDK Navigation.

Vérifier le contenu de local.defaults.properties

Le projet vide contient également un fichier local.defaults.properties dans votre répertoire de premier niveau (même dossier que le fichier secrets.properties). Ouvrez-le et examinez le code suivant.

MAPS_API_KEY=DEFAULT_API_KEY

Cela permet de fournir une valeur de sauvegarde pour la propriété MAPS_API_KEY au cas où secrets.properties ne serait pas ajouté au projet, afin d'éviter que les compilations n'échouent. Il n'est pas nécessaire de modifier ce fichier. Si la définition secrets.properties de MAPS_API_KEY est introuvable, la valeur par défaut arrête l'exécution de l'application au moment de l'exécution, ce qui génère une erreur de clé API.

Vérifier que le fichier manifeste Android utilise la clé API que vous avez spécifiée

Ouvrez app/src/main/AndroidManifest.xml. Vous remarquerez que la propriété MAPS_API_KEY permet de définir la clé API de l'application:

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

Ouvrez le fichier build.gradle.kts au niveau de l'application et recherchez la propriété secrets.

Le paramètre propertiesFileName du plug-in doit être défini sur secrets.properties, et defaultPropertiesFileName doit indiquer local.defaults.properties.

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

Enregistrez tous les fichiers et synchronisez votre projet avec Gradle.

5. Configurer les autorisations de l'application et ajouter une interface utilisateur de base

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

Le SDK Navigation dépend des signaux GPS pour fonctionner. Votre application devra donc demander à l'utilisateur d'autoriser l'accès aux données de localisation précises. Ajoutez l'autorisation d'accéder à la position exacte en tant qu'enfant de l'élément <manifest> dans le fichier AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" >
   <uses-permission 
      android:name="android.permission.ACCESS_FINE_LOCATION"
   />
</manifest>

Pour en savoir plus sur les autorisations d'accéder à la position Android, consultez la section Demander l'autorisation d'accéder à la position de la documentation destinée aux développeurs Android.

Pour exécuter votre application sur un appareil Android 14, demandez l'autorisation d'accéder à la position du service de premier plan en ajoutant la balise uses-permission suivante au même endroit que l'autorisation d'accéder à la position exacte :

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />

Ajouter une activité de lancement avec une interface utilisateur de base

Lorsque votre application s'exécute, elle a besoin d'un code qui s'exécute au démarrage pour vérifier si l'utilisateur a accordé l'autorisation d'accéder à sa position, et gérer chaque scénario possible, en demandant l'autorisation si elle n'a pas encore été accordée. Pour ce faire, ajoutez une interface utilisateur de base à votre application. Cet atelier de programmation utilise l'UI créée lorsque vous créez une activité Views vide dans Android Studio. Vous allez l'adapter pour vérifier l'autorisation d'accéder à la position avant d'ajouter du code à l'activité pour l'interface utilisateur de navigation.

Ouvrez le fichier MainActivity.kt dans l'éditeur de code et inspectez le code, qui affiche une UI de base.

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

Votre application doit déclencher la demande d'accès à la position exacte avant l'initialisation du SDK Navigation.

Pour vous assurer que cette vérification est effectuée au démarrage de votre application, ajoutez du code à votre classe MainActivity, dans la méthode onCreate() remplacée de votre activité.

Le code suivant vérifie si l'utilisateur a accordé une autorisation d'accéder à la position précise. Sinon, il demande l'autorisation. Ajoutez ce code dans votre méthode onCreate().

    val permissions =
      if (VERSION.SDK_INT >= VERSION_CODES.TIRAMISU) {
        arrayOf(permission.ACCESS_FINE_LOCATION, permission.POST_NOTIFICATIONS)
      } else {
        arrayOf(permission.ACCESS_FINE_LOCATION)
      }

    if (permissions.any { !checkPermissionGranted(it) }) {

      if (permissions.any { shouldShowRequestPermissionRationale(it) }) {
        // Display a dialogue explaining the required permissions.
      }

      val permissionsLauncher =
        registerForActivityResult(
          RequestMultiplePermissions(),
          { permissionResults ->
            if (permissionResults.getOrDefault(permission.ACCESS_FINE_LOCATION, false)) {
              onLocationPermissionGranted()
            } else {
              finish()
            }
          },
        )

      permissionsLauncher.launch(permissions)
    } else {
      android.os.Handler(Looper.getMainLooper()).postDelayed({ onLocationPermissionGranted() }, SPLASH_SCREEN_DELAY_MILLIS)
    }
  }

  private fun checkPermissionGranted(permissionToCheck: String): Boolean =
    ContextCompat.checkSelfPermission(this, permissionToCheck) == PackageManager.PERMISSION_GRANTED

Ajoutez une fonction à votre classe MainActivity, appelée onLocationPermissionGranted, qui gérera le résultat lorsque l'utilisateur autorisera le partage de sa position. Dans les étapes suivantes, nous allons ajouter du code pour lancer une nouvelle activité de navigation.

private fun onLocationPermissionGranted() {
   //code to initialize Navigation SDK will go here
}

Compilez votre projet. Si vous rencontrez des erreurs de compilation, recherchez-les et corrigez-les.

Exécutez votre projet sur un nouvel appareil virtuel. La boîte de dialogue de demande d'autorisation doit s'afficher lors de l'installation et du démarrage de l'application.

6. Ajouter une interface utilisateur de navigation

Vous pouvez ajouter une UI de navigation de deux manières : SupportNavigationFragment ou NavigationView.

Pour plus de simplicité, l'atelier de programmation utilise un NavigationView.

Modifier la mise en page

Modifiez res/layout/activity_main.xml pour ajouter une mise en page à un NavigationView.

1. Ouvrez le fichier et passez à la vue Code.
2. Remplacez l'intégralité du contenu du fichier par une nouvelle mise en page d'un NavigationView dans un RelativeLayout, comme dans l'exemple ci-dessous. Comme vous n'allez ajouter qu'une vue de navigation à l'application, une mise en page simple suffit.
3. Attribuez à votre NavigationView l'ID "@+id/navigation_view".

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="match_parent">
 <com.google.android.libraries.navigation.NavigationView
     android:id="@+id/navigation_view"
     android:layout_width="wrap_content"
     android:layout_height="wrap_content"
      />
</RelativeLayout>

Configurer l'activité de navigation

Dans Android Studio, ouvrez le fichier MainActivity.kt dans l'éditeur.

Ajoutez du code de configuration de base pour vous assurer que l'expérience de navigation fonctionne correctement dans votre application. Dans le fichier MainActivity.kt, apportez les modifications suivantes :

1. Déclarez une variable dans votre classe MainActivity pour faire référence à votre NavigationView :

private lateinit var navView: NavigationView

2. Ajoutez du code à la méthode onCreate() pour obtenir une référence à votre NavigationView:

navView = findViewById(R.id.navigation_view)
navView.onCreate(savedInstanceState)

3. Ajoutez du code à la méthode onCreate() pour vous assurer que l'écran reste allumé pendant les instructions de navigation :

// Ensure the screen stays on during nav.
window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)

4. Modifiez le code qui appelle ViewCompat.setOnApplyWindowInsetsListener pour référencer l'ID de votre NavigationView.

ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.navigation_view)) { v, insets ->
  val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
  v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
  insets
}

5. Ajoutez une méthode showToast() à la classe pour afficher des commentaires à l'utilisateur:

private fun showToast(errorMessage: String) {
   Toast.makeText(this@MainActivity, errorMessage, Toast.LENGTH_LONG).show()
}

7. Initialiser le SDK Navigation

Maintenant que vous avez terminé la configuration de l'activité Navigation de base, vous pouvez initialiser le SDK Navigation. Pour ce faire, ajoutez le code suivant à votre fichier MainActivity.kt:

/** Starts the Navigation API, capturing a reference when ready. */
@SuppressLint("MissingPermission")
private fun initializeNavigationApi() {
   NavigationApi.getNavigator(
       this,
       object : NavigatorListener {
           override fun onNavigatorReady(navigator: Navigator) {
               // store a reference to the Navigator object
               mNavigator = navigator
               // code to start guidance will go here
           }

           override fun onError(@NavigationApi.ErrorCode errorCode: Int) {
               when (errorCode) {
                   NavigationApi.ErrorCode.NOT_AUTHORIZED -> {
                       // Note: If this message is displayed, you may need to check that
                       // your API_KEY is specified correctly in AndroidManifest.xml
                       // and is been enabled to access the Navigation API
                       showToast(
                           "Error loading Navigation API: Your API key is " +
                                   "invalid or not authorized to use Navigation."
                       )
                   }
                   NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED -> {
                       showToast(
                           "Error loading Navigation API: User did not " +
                                   "accept the Navigation Terms of Use."
                       )
                   }
                   else -> showToast("Error loading Navigation API: $errorCode")
               }
           }
       },
   )

}

Ce code crée une méthode appelée initializeNavigationApi(). Cette méthode obtient une référence à un objet Navigator en appelant NavigationApi.getNavigator() et implémente un NavigatorListener pour gérer le rappel.

Notez que lorsque l'API Navigation est initialisée, la méthode NavigationListener.onNavigatorReady est appelée, avec un objet Navigator transmis en tant que paramètre. Le code ci-dessus met à jour la variable mNavigator que vous avez déclarée précédemment avec l'objet Navigator initialisé qui est transmis à cette méthode.

Remarque: L'annotation @SuppressLint empêche Android Studio d'afficher un avertissement concernant les autorisations manquantes lors de l'appel de méthodes d'API qui nécessitent l'autorisation d'accéder à la position de l'utilisateur.

Enfin, ajoutez un appel à votre méthode initializeNavigationApi à partir de la méthode onLocationPermissionGranted.

private fun onLocationPermissionGranted() {
   initializeNavigationApi()
}

8. Ajouter des écouteurs pour les principaux événements de navigation

Lorsque vos utilisateurs suivent les instructions, le SDK Navigation déclenche des événements qui peuvent informer l'application des principaux changements d'état en cours de route, par exemple lorsque l'utilisateur change d'itinéraire ou arrive à sa destination. Dans le fichier MainActivity.kt, ajoutez des écouteurs pour gérer ces événements:

1. Dans la classe MainActivity, déclarez deux variables pour faire référence à des objets Écouteur d'événements:

private var arrivalListener: Navigator.ArrivalListener? = null
private var routeChangedListener: Navigator.RouteChangedListener? = null

2. Ajoutez une méthode registerNavigationListeners() pour configurer les écouteurs lorsque le navigateur est initialisé. Cette méthode appelle Navigator.clearDestinations() pour réinitialiser NavigationView lorsque l'événement "Arrivée" est déclenché :

/**
* Registers a number of example event listeners that show an on screen message when certain
* navigation events occur (e.g. the driver's route changes or the destination is reached).
*/
private fun registerNavigationListeners() {
   withNavigatorAsync {
       arrivalListener =
           Navigator.ArrivalListener { // Show an onscreen message
               showToast("User has arrived at the destination!")
               mNavigator?.clearDestinations()
           }
       mNavigator?.addArrivalListener(arrivalListener)

       routeChangedListener =
           Navigator.RouteChangedListener { // Show an onscreen message when the route changes
               showToast("onRouteChanged: the driver's route changed")
           }
       mNavigator?.addRouteChangedListener(routeChangedListener)
   }
}

3. Ajoutez un appel à registerNavigationListeners() à partir du code de rappel onNavigatorReady dans la méthode initializeNavigationApi:

override fun onNavigatorReady(navigator: Navigator) {
   // store a reference to the Navigator object
   mNavigator = navigator

   //listen for events en route
   registerNavigationListeners()


}

4. Configurez l'interface utilisateur. Vous pouvez contrôler différents aspects de l'interface utilisateur de navigation lorsque les instructions sont en cours d'exécution. La position de la caméra est une personnalisation importante. Ajoutez un appel à la méthode setTaskRemovedBehaviour de l'objet navigator renvoyé dans onNavigatorReady comme suit. Cela mettra fin au guidage et aux notifications si l'utilisateur balaie l'application:

// Disables the guidance notifications and shuts down the app and background service
// when the user dismisses/swipes away the app from Android's recent tasks.
navigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)

5. Ajoutez un appel à GoogleMap.followMyLocation pour spécifier un CameraPerspective. L'accès à GoogleMap s'effectue via la méthode NavigatorView.getMapAsync() comme suit :

navView.getMapAsync {
   googleMap  ->
   googleMap.followMyLocation(GoogleMap.CameraPerspective.TILTED)
}

6. Pour vous assurer que la navigation fonctionne correctement tout au long du cycle de vie de l'application, implémentez les méthodes suivantes dans votre classe MainActivity:

override fun onSaveInstanceState(savedInstanceState: Bundle) {
   super.onSaveInstanceState(savedInstanceState)

   navView.onSaveInstanceState(savedInstanceState)
}

override fun onTrimMemory(level: Int) {
   super.onTrimMemory(level)
   navView.onTrimMemory(level)
}

override fun onStart() {
   super.onStart()
   navView.onStart()
}

override fun onResume() {
   super.onResume()
   navView.onResume()
}

override fun onPause() {
   navView.onPause()
   super.onPause()
}

override fun onConfigurationChanged(configuration: Configuration) {
   super.onConfigurationChanged(configuration)
   navView.onConfigurationChanged(configuration)
}

override fun onStop() {
   navView.onStop()
   super.onStop()
}

override fun onDestroy() {
   navView.onDestroy()
   withNavigatorAsync {
       // Unregister event listeners to avoid memory leaks.
       if (arrivalListener != null) {
           navigator.removeArrivalListener(arrivalListener)
       }
       if (routeChangedListener != null) {
           navigator.removeRouteChangedListener(routeChangedListener)
       }

       navigator.simulator?.unsetUserLocation()
       navigator.cleanup()
   }
   super.onDestroy()
}

9. Définir une destination

Vous êtes maintenant prêt à définir une destination et à lancer le guidage de la navigation. Dans le fichier MainActivity.kt, apportez les modifications suivantes :

1. Ajoutez une méthode navigateToPlace() qui définit la destination de navigation et accepte un paramètre placeId.

/**
* Requests directions from the user's current location to a specific place (provided by the
* Place ID).
*/
private fun navigateToPlace(placeId: String) {

}

2. Dans votre méthode navigateToPlace(), utilisez la méthode Waypoint.builder() pour créer un Waypoint à partir de l'ID de lieu transmis à la méthode. Gérez les UnsupportedPlaceIdException que cela peut générer lorsque l'ID de lieu ne correspond pas à une adresse précise:

val waypoint: Waypoint? =
// Set a destination by using a Place ID (the recommended method)
try {
   Waypoint.builder().setPlaceIdString(placeId).build()
} catch (e: Waypoint.UnsupportedPlaceIdException) {
   showToast("Place ID was unsupported.")
   return
}

3. Ajoutez le code suivant à votre méthode navigateToPlace() pour définir une destination à l'aide du point de cheminement:

val pendingRoute = mNavigator?.setDestination(waypoint)

// Set an action to perform when a route is determined to the destination
pendingRoute?.setOnResultListener { code ->
   when (code) {
       RouteStatus.OK -> {
           // Code to start guidance will go here
       }

       RouteStatus.ROUTE_CANCELED -> showToast("Route guidance canceled.")
       RouteStatus.NO_ROUTE_FOUND,
       RouteStatus.NETWORK_ERROR ->
           // TODO: Add logic to handle when a route could not be determined
           showToast("Error starting guidance: $code")

       else -> showToast("Error starting guidance: $code")
   }
}

L'objet Navigator comporte une méthode setDestinations() qui peut accepter divers paramètres. L'option la plus simple consiste à fournir un Waypoint. Le mode de transport par défaut est DRIVING, adapté aux voitures à quatre roues. La méthode setDestinations() renvoie un objet ListenableResultFuture contenant un objet RouteStatus. RouteStatus indique si un itinéraire a été trouvé vers la destination et vous permet de gérer différents états d'erreur si ce n'est pas le cas.

4. Apportez des modifications de configuration supplémentaires pour améliorer l'expérience utilisateur de la navigation:

// Hide the toolbar to maximize the navigation UI
supportActionBar?.hide()

// Enable voice audio guidance (through the device speaker)
mNavigator?.setAudioGuidance(Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE)


// Simulate vehicle progress along the route (for demo/debug builds)
if (BuildConfig.DEBUG) {
   mNavigator?.simulator?.simulateLocationsAlongExistingRoute(
       SimulationOptions().speedMultiplier(5f)
   )
}

Ces modifications incluent les améliorations suivantes :

• Masquage de la barre d'actions pour maximiser l'espace de l'interface utilisateur de navigation.
• Activer les instructions audio pour lire les alertes et les instructions de navigation
• Configurer le simulateur pour le débogage en spécifiant un multiplicateur de vitesse

5. Recherchez un ID de lieu qui servira de destination. Dans l'idéal, il ne doit pas être trop éloigné de l'emplacement de l'utilisateur. Utilisez l'outil de recherche d'ID de lieu Google Maps Platform ou obtenez un ID de lieu à partir d'un appel de l'API Places.

Si vous simulez la navigation, vous pouvez définir la position de l'utilisateur dans le code ou la récupérer à partir de votre appareil connecté. L'atelier de programmation suppose que vous simulez un lieu à Londres, au Royaume-Uni.

6. Ajoutez un objet compagnon à votre classe MainActivity pour stocker un point de départ et un ID de lieu. L'atelier de programmation utilisera un point de départ à Londres et l'ID de lieu de Trafalgar Square :

companion object{
   const val TRAFALGAR_SQUARE ="ChIJH-tBOc4EdkgRJ8aJ8P1CUxo" //London, UK
   val startLocation = LatLng(51.345678, -0.1234456)
}

Conseil: Pour obtenir une latitude et une longitude différentes à utiliser comme point de départ, effectuez un clic droit sur un lieu dans Google Maps dans un navigateur ou appuyez de manière prolongée sur la carte dans l'application mobile Google Maps.

7. Ajoutez un appel à votre méthode navigateToPlace() à partir du rappel onNavigatorReady dans la méthode initializeNavigationApi, puis ajoutez une branche de logique qui s'exécutera en mode débogage, qui définit l'emplacement de l'utilisateur:

// Disables the guidance notifications and shuts down the app and background service
// when the user dismisses/swipes away the app from Android's recent tasks.
navigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)

mNavigator = navigator

if (BuildConfig.DEBUG) {
   mNavigator?.simulator?.setUserLocation(MainActivity.startLocation)
}
//listen for events en route
registerNavigationListeners()

navView.getMapAsync {
   googleMap  ->
   googleMap.followMyLocation(GoogleMap.CameraPerspective.TILTED)
}

//navigate to a destination
navigateToPlace(MainActivity.TRAFALGAR_SQUARE)

10. Créer et exécuter votre code

La première fois que vous exécutez l'application, vous devez lui accorder des autorisations d'accéder à la position et accepter les conditions d'utilisation du SDK Navigation.

Remarque : L'exécution de l'application appelle la méthode setDestinations(), 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.

Définir l'emplacement

Par défaut, l'emplacement de l'appareil émulé peut être défini sur le campus Google de Mountain View en Californie, sauf si vous avez défini un emplacement dans le code ou dans la boîte de dialogue des propriétés de l'émulateur.

Si tel est le cas, il est possible que l'application ne trouve pas d'itinéraire vers l'identifiant de lieu que vous avez configuré (par défaut, Opéra de Sydney, Sydney, Australie). Dans ce cas, votre méthode showToast() affiche le message "Aucun itinéraire trouvé".

Coder en dur le lieu de départ

Pour définir un emplacement différent dans le code, ajoutez la ligne suivante dans votre méthode navigateToPlace() dans MainActivity.kt, avant l'appel de mNavigator.startGuidance() :

mNavigator?.simulator?.setUserLocation(startLocation)

Démarrer l'émulateur à l'emplacement par défaut de votre choix

Pour définir une autre position dans l'émulateur d'appareil, lancez l'émulateur s'il n'est pas déjà en cours d'exécution, puis cliquez sur le menu à trois points avec l'info-bulle "Commandes avancées". La boîte de dialogue qui s'ouvre contient une option de menu pour "Position".

Par exemple, si vous utilisez l'ID de lieu de l'Opéra de Sydney comme destination, choisissez un lieu situé à Sydney, en Australie. Par exemple, recherchez "Plage de Bondi", sélectionnez une suggestion, puis cliquez sur "Enregistrer l'emplacement" en bas à droite de la boîte de dialogue. Vous pouvez également cliquer sur "Enregistrer le point" pour ajouter le lieu à une liste enregistrée en vue d'une utilisation ultérieure.

Si vous définissez un ID de lieu différent comme destination, choisissez un lieu à proximité pour que l'itinéraire simulé soit réaliste et pas trop long pour faciliter le débogage.

Redémarrez l'application. Elle devrait maintenant vous emmener à destination.

11. Félicitations !

Vous avez terminé cet atelier de programmation. Bravo ! Vous êtes arrivé à destination. Bon codage :-)

12. Aller plus loin

Si vous souhaitez aller plus loin dans le développement de votre application, consultez les sujets suivants pour vous inspirer.

• Écouter les autres événements de navigation Ajoutez du code pour afficher un message si le conducteur modifie son itinéraire ou à son arrivée.
• Personnalisez l'interface de navigation.
• Si vous souhaitez relever un défi plus important, essayez d'ajouter une commande Place Picker de l'API Places pour permettre à l'utilisateur de définir la destination. Astuce: Les applications de démonstration du SDK Navigation sur GitHub proposent un exemple d'implémentation.
• Évitez les problèmes potentiels d'appel des objets Navigator et GoogleMap de manière asynchrone en adoptant l'approche utilisée dans les applications de démonstration du SDK Navigation sur GitHub. Dans les scénarios d'application plus complexes, l'initialisation de ces objets peut ne pas être terminée lors de l'exécution de votre code. Conseil: Vous pouvez ajouter la classe InitializedNavScope à la fin de votre fichier MainActivity.kt pour une implémentation très rapide.