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é à partir de la section Créer un trajet pour lancer Google Maps ou Waze, et configurer l'expérience de retour à 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.
Permettre aux conducteurs de démarrer la navigation depuis votre application
Vous devez permettre aux conducteurs de démarrer la navigation depuis votre application. Si vous leur permettez de lancer Google Maps ou Waze à l'aide d'un bouton, assurez-vous que l'attribution est correcte et évitez 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. Elle fonctionne de la même manière qu'une URL Google Maps standard ou un lien profond Waze.
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 vous assurer que Google Maps ou Waze peut calculer un itinéraire, respectez les règles suivantes lorsque vous mettez en forme votre destination :
Spécifiez exactement une 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.
Ajouter un jeton de trajet et des paramètres de navigation
Pour compléter l'URL de lancement, vous devez inclure le jeton de trajet authentifié que vous avez reçu de la requête Créer un trajet. 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 pour Google Maps à l'aide de 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 de 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
-
ID de 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 attribuer une session de navigation à votre application sur Android, fournissez votre ID d'application validé. Cela identifie votre application comme source du trajet afin que Google Maps ou Waze puisse relier le trajet actif à votre plate-forme.
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 des données de trajet actives.
- Activer le consentement du conducteur : remplit l'écran de consentement avec le nom de votre entreprise et vos règles de confidentialité, ce qui permet au conducteur de savoir qui reçoit sa position en temps réel et son heure d'arrivée prévue.
- Activer le bouton de retour : permet à Google Maps ou Waze de créer un bouton de retour personnalisé afin 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 d'URL de lancement) à l'aide de Intent.EXTRA_REFERRER_NAME.
L'exemple suivant montre comment ajouter le nom du package à l'intent :
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
Permettre aux conducteurs de revenir à votre application
Navigation Connect affiche une barre inférieure (Google Maps) ou un bouton Retour personnalisé (Waze) afin 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 votre
activité d'application. Associez ce PendingIntent en tant qu'extra à l'intent de lancement à l'aide de la clé exacte "pendingIntent". Lorsque l'utilisateur appuie sur le
bouton de retour, Google Maps ou Waze exécute cet intent pour mettre 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 de 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 activer le bouton "Retour à l'application".
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)
}
}