Per avviare la sessione di navigazione, l'app deve creare dinamicamente un URL di avvio per aprire Google Maps o Waze. Questa guida descrive come utilizzare il token di corsa autenticato di Crea una corsa per avviare Google Maps o Waze e configurare l'esperienza di ritorno alla tua app.
Come avviare Google Maps o Waze
Per avviare Google Maps o Waze, devi fornire un modo per consentire ai conducenti di avviare una sessione di navigazione dalla tua app, creare l'URL di lancio con i parametri richiesti e fornire l'ID applicazione per attribuire la sessione.
Consenti ai conducenti di avviare la navigazione dalla tua app
Devi fornire ai conducenti un modo per avviare la navigazione dalla tua app. Se consenti ai conducenti di avviare Google Maps o Waze utilizzando un pulsante, assicurati di attribuire correttamente l'app ed evita confusione etichettandola chiaramente. Ad esempio, inserisci il testo "Google Maps" o "Waze" sopra o accanto al pulsante.
Crea l'URL di lancio
Per avviare una sessione di navigazione, crea un URL di lancio di Navigation Connect. Questo URL è una stringa contenente la destinazione, il token della corsa e i parametri di navigazione richiesti. Funziona in modo simile a un URL di Google Maps standard o a un deep link di Waze.
Per avviare Google Maps o Waze sul dispositivo del conducente, utilizza il meccanismo specifico della piattaforma:
- Android: passa la stringa dell'URL in un
Intent. - iOS: utilizza la stringa dell'URL come link universale (o deep link).
Formatta la destinazione
Per assicurarti che Google Maps o Waze possano calcolare correttamente un percorso, rispetta le seguenti regole durante la formattazione della destinazione:
Specifica esattamente una destinazione raggiungibile. Puoi passare la destinazione come stringa di indirizzo, coordinate di latitudine/longitudine o ID luogo.
Non utilizzare più tappe. Se passi più tappe direttamente nell'URL, Google Maps o Waze visualizza un errore. Crea invece corse separate.
Aggiungi il token della corsa e i parametri di navigazione
Per completare l'URL di lancio, devi includere il token della corsa autenticato che hai ricevuto dalla richiesta Crea una corsa. Devi anche includere i parametri di navigazione che indicano a Google Maps o Waze di avviare la navigazione attiva.
Google Maps
Per Google Maps, includi i seguenti parametri nell'URL di avvio:
dir_action=navigate: questo parametro forza la navigazione attiva.action_token: questo parametro fornisce il token di corsa autenticato.
I seguenti esempi mostrano come formattare l'URL di avvio di Google Maps utilizzando diversi formati di destinazione:
-
Coordinate di latitudine/longitudine:
https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
-
Stringa dell'indirizzo:
https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
-
ID luogo:
https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN
Waze
Per Waze, includi i seguenti parametri nell'URL di avvio:
navigate=yes: questo parametro forza la navigazione attiva.external_trip_token: questo parametro fornisce il token di corsa autenticato.
I seguenti esempi mostrano come formattare l'URL di avvio per Waze utilizzando diversi formati di destinazione:
-
Coordinate di latitudine/longitudine:
https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
-
Stringa dell'indirizzo:
https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
-
ID luogo:
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
Fornisci l'ID applicazione (solo Android)
Per iniziare un percorso con Navigation Connect, devi attribuire una sessione di navigazione alla tua app su Android. Per farlo, fornisci l'ID applicazione verificato. Questo identifica la tua app come origine della corsa, in modo che Google Maps o Waze possano ricollegare il percorso attivo alla tua piattaforma. Un ID applicazione mancante o non valido comporta un errore di autenticazione del token di percorso.
Se fornisci l'ID applicazione, vengono attivate le seguenti funzionalità:
- Autorizza la condivisione dei dati: verifica che la tua app sia autorizzata a ricevere i dati sul percorso attivo.
- Attiva il consenso del conducente: compila la schermata per il consenso con il nome della tua attività e le norme sulla privacy, assicurandoti che il conducente sappia chi riceve la sua posizione in tempo reale e l'orario di arrivo stimato.
- Attiva il pulsante di ritorno: consente a Google Maps o Waze di creare un pulsante di ritorno con il brand in modo che i conducenti possano tornare alla tua app.
Per passare l'ID applicazione a Google Maps o Waze su Android, aggiungi il nome del pacchetto all'intent di lancio (che contiene la stringa dell'URL di lancio) utilizzando Intent.EXTRA_REFERRER_NAME.
L'esempio seguente mostra come aggiungere il nome del pacchetto all'intent:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
Come consentire ai conducenti di tornare alla tua app
Navigation Connect mostra una barra in basso (Google Maps) o un pulsante Indietro con il brand (Waze) in modo che il conducente possa tornare facilmente alla tua app in qualsiasi momento durante il viaggio o quando arriva a destinazione.
Android
Devi creare un PendingIntent che rimandi all'attività della tua app. Collega questo PendingIntent come extra all'intent di lancio utilizzando la chiave esatta "pendingIntent". Quando l'utente tocca il pulsante Indietro, Google Maps o Waze esegue questo intent per portare la tua app in primo piano.
intent.putExtra("pendingIntent", getPendingIntent())iOS (solo Waze)
Non è necessario aggiungere nulla all'URL di avvio per attivare il pulsante Indietro. Waze utilizza automaticamente il link universale che hai registrato quando hai verificato la tua app.
Esempi di codice
I seguenti esempi di codice mostrano come avviare Google Maps o Waze dalla tua app utilizzando Navigation Connect e attivare il pulsante "Torna all'app".
Google Maps (Android)
Il seguente codice Kotlin mostra una funzione di esempio che avvia una sessione di Navigation Connect con i parametri richiesti.
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)
Il seguente codice Kotlin mostra una funzione di esempio che avvia una sessione di Navigation Connect con i parametri richiesti.
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)
Il seguente codice Swift mostra una funzione di esempio che avvia una sessione di Navigation Connect con i parametri richiesti.
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)
}
}