Pour démarrer la session de navigation, votre application doit créer de manière dynamique 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 votre ID d'application pour attribuer la session.
Permettez aux conducteurs de 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, veillez à l'attribuer correctement et à é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 ou un lien profond Waze standard.
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).
Formater la destination
Pour vous assurer que Google Maps ou Waze peuvent 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 la forme d'une chaîne d'adresse, de coordonnées de latitude/longitude ou d'un ID de lieu.
N'utilisez pas plusieurs points de cheminement. Si vous transmettez plusieurs points de cheminement 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 lancer 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 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 de 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 votre 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, indiquez l'ID de votre application validée. Il identifie 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.
En fournissant votre ID d'application, vous pouvez bénéficier des fonctionnalités suivantes :
- Autoriser le partage de données : vérifie que votre application est autorisée à recevoir des données sur les trajets actifs.
- Activer le consentement du conducteur : l'écran de consentement est renseigné 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é 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 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}")
Comment permettre aux conducteurs de revenir à votre application
Navigation Connect affiche une barre inférieure (Google Maps) ou un bouton de retour de marque (Waze) pour que le conducteur puisse revenir facilement à votre application à tout moment pendant le trajet ou lorsqu'il arrive à destination.
Android
Vous devez créer un PendingIntent qui renvoie à l'activité de votre 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 afficher 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 "Revenir à 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)
}
}