Lancer Google Maps ou Waze

Pour démarrer la session de navigation, votre application doit créer dynamiquement une URL de lancement pour ouvrir Google Maps ou Waze. Ce guide explique comment utiliser le jeton de trajet authentifié de Créer un trajet pour lancer Google Maps ou Waze et configurer l'expérience de retour vers votre application.

Lancer Google Maps ou Waze

Pour lancer Google Maps ou Waze, vous devez permettre aux conducteurs de démarrer une session de navigation depuis votre application, créer l'URL de lancement avec les paramètres requis et fournir l'ID de votre application pour attribuer la session.

Autoriser les conducteurs à lancer la navigation depuis votre application

Vous devez permettre aux conducteurs de lancer la navigation depuis votre application. Si vous leur permettez de lancer Google Maps ou Waze à l'aide d'un bouton, assurez-vous de l'attribuer correctement et d'éviter toute confusion en l'étiquetant clairement. Par exemple, placez le texte "Google Maps" ou "Waze" sur le bouton ou à proximité.

Créer l'URL de lancement

Pour démarrer une session de navigation, créez une URL de lancement Navigation Connect. Cette URL est une chaîne contenant la destination, le jeton de trajet et les paramètres de navigation requis. Il fonctionne de la même manière qu'une URL Google Maps standard ou un lien profond Waze.

Important : Navigation Connect n'est compatible qu'avec la conduite. Ne configurez pas les modes de déplacement autres que la conduite (comme la marche, le vélo ou les transports en commun) dans vos URL de lancement. Si le conducteur navigue dans un mode autre que la conduite, Navigation Connect ne renverra pas de mises à jour de télémétrie ni d'informations sur le trafic.

Pour lancer Google Maps ou Waze sur l'appareil du conducteur, utilisez le mécanisme spécifique à la plate-forme :

• Android : transmettez la chaîne d'URL dans un Intent.
• iOS : utilisez la chaîne d'URL comme lien universel (ou lien profond).

Mettre en forme la destination

Pour que Google Maps ou Waze puissent calculer un itinéraire, respectez les règles suivantes lorsque vous mettez en forme votre destination :

• Spécifiez une seule destination accessible. Vous pouvez transmettre la destination sous forme de chaîne d'adresse, de coordonnées de latitude/longitude ou d'ID de lieu.

• N'utilisez pas plusieurs points de repère. Si vous transmettez plusieurs points de repère directement dans l'URL, Google Maps ou Waze affiche une erreur. Créez plutôt des trajets distincts.

Remarque : Ne transmettez pas d'origine de départ personnalisée dans l'URL de lancement. Google Maps ou Waze utilisent automatiquement la position actuelle du conducteur au début de la session. Pour éviter les erreurs "Origine introuvable", demandez à vos chauffeurs d'activer le suivi précis de la position.

Ajouter un jeton de trajet et des paramètres de navigation

Pour compléter l'URL de lancement, vous devez inclure le jeton de voyage authentifié que vous avez reçu de la requête Create a trip. Vous devez également inclure les paramètres de navigation qui indiquent à Google Maps ou Waze de démarrer la navigation active.

Google Maps

Pour Google Maps, incluez les paramètres suivants dans votre URL de lancement :

• dir_action=navigate : ce paramètre force la navigation active.
• action_token : ce paramètre fournit votre jeton de trajet authentifié.

Les exemples suivants montrent comment mettre en forme l'URL de lancement de Google Maps en utilisant différents formats de destination :

• Coordonnées de latitude/longitude :

  https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN

• Chaîne d'adresse :

  https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN

• ID du lieu :

  https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN

Waze

Pour Waze, incluez les paramètres suivants dans votre URL de lancement :

• navigate=yes : ce paramètre force la navigation active.
• external_trip_token : ce paramètre fournit votre jeton de trajet authentifié.

Les exemples suivants montrent comment mettre en forme l'URL de lancement pour Waze à l'aide de différents formats de destination :

• Coordonnées de latitude/longitude :

  https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN

• Chaîne d'adresse :

  https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN

  Remarque : Waze accède au premier résultat de recherche pour les chaînes d'adresses.
• ID du lieu :

  https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

Fournir l'ID d'application (Android uniquement)

Pour démarrer un trajet avec Navigation Connect, vous devez attribuer une session de navigation à votre application sur Android. Pour ce faire, fournissez l'ID de votre application validée. Cela permet d'identifier votre application comme source du trajet afin que Google Maps ou Waze puissent associer le trajet actif à votre plate-forme. Si l'ID d'application est manquant ou non valide, l'authentification du jeton de trajet échoue.

Remarque : Pour iOS, vous devez avoir fourni l'ID de l'application dans le message CreateTripRequest. Pour en savoir plus, consultez Créer un voyage.

Fournir l'ID d'application permet d'activer les fonctionnalités suivantes :

• Autoriser le partage de données : vérifie que votre application est autorisée à recevoir les données de trajet en cours.
• Activer le consentement du conducteur : l'écran de consentement affiche le nom de votre entreprise et vos règles de confidentialité. Le conducteur sait ainsi qui reçoit sa position en temps réel et son heure d'arrivée prévue.
• Activer le bouton "Retour" : permet à Google Maps ou Waze de créer un bouton "Retour" personnalisé pour que les conducteurs puissent revenir à votre application.

Pour transmettre l'ID d'application à Google Maps ou Waze sur Android, ajoutez le nom de votre package à l'intent de lancement (qui contient la chaîne de l'URL de lancement) à l'aide de Intent.EXTRA_REFERRER_NAME.

L'exemple suivant montre comment ajouter le nom du package à l'intention :

intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")

Comment permettre aux conducteurs de revenir à votre application

Navigation Connect affiche une barre inférieure (Google Maps) ou un bouton Retour personnalisé (Waze) pour que le conducteur puisse revenir facilement à votre application à tout moment pendant le trajet ou à son arrivée à destination.

Android

Vous devez créer un PendingIntent qui pointe vers l'activité de votre application. Associez ce PendingIntent en tant qu'extra à l'intent de lancement en utilisant la clé exacte "pendingIntent". Lorsque l'utilisateur appuie sur le bouton de retour, Google Maps ou Waze exécute cet intent pour ramener votre application au premier plan.

intent.putExtra("pendingIntent", getPendingIntent())

iOS (Waze uniquement)

Vous n'avez rien à ajouter à l'URL de lancement pour activer le bouton "Retour". Waze utilise automatiquement le lien universel que vous avez enregistré lorsque vous avez validé votre application.

Exemples de code

Les exemples de code suivants montrent comment lancer Google Maps ou Waze depuis votre application à l'aide de Navigation Connect et comment activer le bouton "Retour à l'appli".

Google Maps (Android)

Le code Kotlin suivant montre un exemple de fonction qui lance une session Navigation Connect avec les paramètres requis.

private val destinationAddress = "1600 Amphitheatre Parkway, Mountain View, CA 94043"

        private fun launchNavConnect() {
           val jwtToken = "TRIP_TOKEN"

           try {
               // URL Encode the destination
               val encodedDestination = URLEncoder.encode(destinationAddress, "UTF-8")
               val navConnectUrl = "https://www.google.com/maps/dir/?api=1" +
                       "&destination=$encodedDestination" +
                       "&dir_action=navigate" +
                       "&action_token=$jwtToken"

               val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navConnectUrl))
               // Explicitly set GMM package to ensure it opens in Google Maps
               intent.setPackage("com.google.android.apps.maps")
               // Add your application ID to the intent
               intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
               // set up the NavConnect back button
               intent.putExtra("pendingIntent", getPendingIntent())
               startActivity(intent)

           } catch (e: Exception) {
               // handle errors
           }
        }

        private fun getPendingIntent(): PendingIntent? {
          val returnIntent = Intent(application, MainActivity::class.java) // replace with your activity to launch
          returnIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
          val flags = PendingIntent.FLAG_IMMUTABLE
          if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            return PendingIntent.getActivity(application, 0, returnIntent, flags)
          }

          val options =
            ActivityOptions.makeBasic()
              .setPendingIntentCreatorBackgroundActivityStartMode(
                ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
              )

          return PendingIntent.getActivity(application, 0, returnIntent, flags, options.toBundle())
        }

Waze (Android)

Le code Kotlin suivant montre un exemple de fonction qui lance une session Navigation Connect avec les paramètres requis.

private val destinationAddress = "1600 Amphitheatre Parkway, Mountain View, CA 94043"

         private fun launchNavConnect() {
            val tripToken = "TRIP_TOKEN"

            try {
                // URL Encode the destination
                val encodedDestination = URLEncoder.encode(destinationAddress, "UTF-8")
                val navConnectUrl = "https://waze.com/ul?" +
                        "&q=$encodedDestination" +
                        "&navigate=yes" +
                        "&external_trip_token=$tripToken"

                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navConnectUrl))
                // Explicitly set package name to ensure it opens in Waze
                intent.setPackage("com.waze")
                // Add your application ID to the intent
                val referrerName = "android-app://${application.packageName}"
                intent.putExtra(Intent.EXTRA_REFERRER_NAME, referrerName)

                // set up the NavConnect back button
                intent.putExtra("pendingIntent", getPendingIntent())
                startActivity(intent)

            } catch (e: Exception) {
                // handle errors
            }
         }

         private fun getPendingIntent(): PendingIntent? {
           val returnIntent = Intent(application, MainActivity::class.java) // replace with your activity to launch
           returnIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
           val flags = PendingIntent.FLAG_IMMUTABLE
           if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
             return PendingIntent.getActivity(application, 0, returnIntent, flags)
           }

           val options =
             ActivityOptions.makeBasic()
               .setPendingIntentCreatorBackgroundActivityStartMode(
                 ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
               )

           return PendingIntent.getActivity(application, 0, returnIntent, flags, options.toBundle())
         }

Waze (iOS)

Le code Swift suivant montre un exemple de fonction qui lance une session Navigation Connect avec les paramètres requis.

openWazeUrl(queryItems: [URLQueryItem(name: "q", value: "1600 Amphitheatre Parkway")])

        private func openWazeUrl(queryItems: [URLQueryItem]) {
          var components = URLComponents()
          components.scheme = "https"
          components.host = "waze.com"
          components.path = "/ul"

          // Create a mutable copy of the queryItems.
          var mutableQueryItems = queryItems

          // Add Trip Token
          guard let tokenText = tokenField.text, !tokenText.isEmpty else {
            return
          }
          let token = URLQueryItem(name: "external_trip_token", value: tokenText)

          mutableQueryItems.append(token)

          // Add compulsory params
          mutableQueryItems.append(URLQueryItem(name: "navigate", value: "yes"))

          // Construct and Launch URL
          components.queryItems = mutableQueryItems

          guard let url = components.url else {
            return
          }

          UIApplication.shared.open(url, options: [:], completionHandler: nil)
        }
       }