Um die Navigationssitzung zu starten, muss Ihre App dynamisch eine Start-URL erstellen, um Google Maps oder Waze zu öffnen. In dieser Anleitung wird beschrieben, wie Sie das authentifizierte Fahrt-Token aus „Fahrt erstellen“ verwenden, um Google Maps oder Waze zu starten und die Rückkehr zu Ihrer App zu konfigurieren.
Google Maps oder Waze starten
Wenn Sie Google Maps oder Waze starten möchten, müssen Sie Fahrern die Möglichkeit geben, eine Navigationssitzung über Ihre App zu starten, die Start-URL mit den erforderlichen Parametern zu erstellen und Ihre Anwendungs-ID anzugeben, um die Sitzung zuzuordnen.
Fahrern ermöglichen, die Navigation über Ihre App zu starten
Sie sollten Fahrern die Möglichkeit geben, die Navigation über Ihre App zu starten. Wenn Sie Fahrern ermöglichen, Google Maps oder Waze über eine Schaltfläche zu starten, sorgen Sie für eine korrekte Zuordnung und vermeiden Sie Verwirrung, indem Sie die Schaltfläche deutlich kennzeichnen. Platzieren Sie beispielsweise den Text „Google Maps“ oder „Waze“ auf oder in der Nähe der Schaltfläche.
Start-URL erstellen
Erstellen Sie eine Navigation Connect-Start-URL, um eine Navigationssitzung zu starten. Diese URL ist ein String, der das Ziel, das Fahrt-Token und die erforderlichen Navigationsparameter enthält. Sie funktioniert ähnlich wie eine Standard-Google Maps-URL oder ein Waze-Deeplink.
Verwenden Sie den plattformspezischen Mechanismus, um Google Maps oder Waze auf dem Gerät des Fahrers zu starten:
- Android:Übergeben Sie den URL-String in einem
Intent. - iOS:Verwenden Sie den URL-String als universellen Link (oder Deeplink).
Ziel formatieren
Damit Google Maps oder Waze eine Route berechnen kann, müssen Sie beim Formatieren des Ziels die folgenden Regeln einhalten:
Geben Sie genau ein erreichbares Ziel an. Sie können das Ziel als Adressstring, Breiten-/Längengradkoordinaten oder Orts-ID übergeben.
Verwenden Sie nicht mehrere Wegpunkte. Wenn Sie mehrere Wegpunkte direkt in der URL übergeben, wird in Google Maps oder Waze ein Fehler angezeigt. Erstellen Sie stattdessen separate Fahrten.
Fahrt-Token und Navigationsparameter hinzufügen
Um die Start-URL zu vervollständigen, müssen Sie das authentifizierte Fahrt-Token einfügen, das Sie in der Anfrage „Fahrt erstellen“ erhalten haben. Außerdem müssen Sie die Navigationsparameter einfügen, die Google Maps oder Waze anweisen, die aktive Navigation zu starten.
Google Maps
Fügen Sie für Google Maps die folgenden Parameter in die Start-URL ein:
dir_action=navigate: Dieser Parameter erzwingt die aktive Navigation.action_token: Dieser Parameter enthält Ihr authentifiziertes Fahrt-Token.
Die folgenden Beispiele zeigen, wie Sie die Start-URL für Google Maps mit verschiedenen Zielformaten formatieren:
-
Breiten-/Längengradkoordinaten:
https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
-
Adressstring:
https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
-
Orts-ID:
https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN
Waze
Fügen Sie für Waze die folgenden Parameter in die Start-URL ein:
navigate=yes: Dieser Parameter erzwingt aktive Navigation.external_trip_token: Dieser Parameter enthält Ihr authentifiziertes Fahrt-Token.
Die folgenden Beispiele zeigen, wie Sie die Start-URL für Waze mit verschiedenen Zielformaten formatieren:
-
Breiten-/Längengradkoordinaten:
https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
-
Adressstring:
https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
-
Orts-ID:
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
Anwendungs-ID angeben (nur Android)
Wenn Sie eine Navigationssitzung Ihrer App unter Android zuordnen möchten, geben Sie Ihre bestätigte Anwendungs-ID an. Dadurch wird Ihre App als Quelle der Fahrt identifiziert, sodass Google Maps oder Waze die aktive Fahrt mit Ihrer Plattform verknüpfen kann.
Wenn Sie Ihre Anwendungs-ID angeben, werden die folgenden Funktionen aktiviert:
- Datenfreigabe autorisieren:Prüft, ob Ihre App berechtigt ist, Daten zu aktiven Fahrten zu empfangen.
- Einwilligung des Fahrers aktivieren:Füllt den Zustimmungsbildschirm mit Ihrem Unternehmensnamen und Ihrer Datenschutzerklärung aus, damit der Fahrer weiß, wer seinen Echtzeitstandort und die voraussichtliche Ankunftszeit erhält.
- Schaltfläche „Zurück“ aktivieren:Ermöglicht Google Maps oder Waze, eine gebrandete Schaltfläche „Zurück“ zu erstellen, damit Fahrer zu Ihrer App zurückkehren können.
Wenn Sie die Anwendungs-ID unter Android an Google Maps oder Waze übergeben möchten, fügen Sie Ihrem Paketnamen mit Intent.EXTRA_REFERRER_NAME dem Start-Intent hinzu (das den Start-URL-String enthält).
Das folgende Beispiel zeigt, wie Sie den Paketnamen dem Intent hinzufügen:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
Fahrern ermöglichen, zu Ihrer App zurückzukehren
Navigation Connect zeigt eine untere Leiste (Google Maps) oder eine gebrandete Schaltfläche „Zurück“ (Waze) an, damit der Fahrer jederzeit während der Fahrt oder bei der Ankunft am Ziel nahtlos zu Ihrer App zurückkehren kann.
Android
Sie müssen ein PendingIntent erstellen, das auf die
Aktivität Ihrer App verweist. Hängen Sie dieses PendingIntent als Extra an das Start
Intent an und verwenden Sie dabei genau den Schlüssel "pendingIntent". Wenn der Nutzer auf die
Schaltfläche „Zurück“ tippt, führt Google Maps oder Waze dieses Intent aus, um Ihre App in den
Vordergrund zu bringen.
intent.putExtra("pendingIntent", getPendingIntent())iOS (nur Waze)
Sie müssen der Start-URL nichts hinzufügen, um die Schaltfläche „Zurück“ zu aktivieren. Waze verwendet automatisch den universellen Link, den Sie bei der Bestätigung Ihrer App registriert haben.
Codebeispiele
Die folgenden Codebeispiele zeigen, wie Sie Google Maps oder Waze über Ihre App mit Navigation Connect starten und die Schaltfläche „Zurück zur App“ aktivieren.
Google Maps (Android)
Der folgende Kotlin-Code zeigt eine Beispielfunktion, die eine Navigation Connect-Sitzung mit den erforderlichen Parametern startet.
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)
Der folgende Kotlin-Code zeigt eine Beispielfunktion, die eine Navigation Connect-Sitzung mit den erforderlichen Parametern startet.
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)
Der folgende Swift-Code zeigt eine Beispielfunktion, die eine Navigation Connect-Sitzung mit den erforderlichen Parametern startet.
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)
}
}