Damit die Navigationssitzung gestartet werden kann, muss Ihre App dynamisch eine Start-URL erstellen, um Google Maps oder Waze zu öffnen. In diesem Leitfaden 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 eine Möglichkeit bieten, mit der Fahrer eine Navigationssitzung über Ihre App starten können. Außerdem müssen Sie die Start-URL mit den erforderlichen Parametern erstellen und Ihre Anwendungs-ID angeben, 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 Quellenangabe und vermeiden Sie Verwirrung, indem Sie die Schaltfläche deutlich kennzeichnen. Platzieren Sie den Text „Google Maps“ oder „Waze“ beispielsweise auf oder in der Nähe des Buttons.
Start-URL erstellen
Um eine Navigationssitzung zu starten, erstellen Sie eine Launch-URL für Navigation Connect. Diese URL ist ein String, der das Ziel, das Trip-Token und die erforderlichen Navigationsparameter enthält. Sie funktioniert ähnlich wie eine Standard-Google Maps-URL oder ein Waze-Deeplink.
Verwenden Sie den plattformspezifischen 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 können, müssen Sie die folgenden Regeln für die Formatierung Ihres Ziels 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.
Parameter für Fahrt-Tokens und Navigation hinzufügen
Um die Start-URL zu vervollständigen, müssen Sie das authentifizierte Fahrt-Token einfügen, das Sie über die Anfrage Create a trip erhalten haben. Sie müssen auch die Navigationsparameter angeben, die Google Maps oder Waze anweisen, die aktive Navigation zu starten.
Google Maps
Fügen Sie für Google Maps die folgenden Parameter in Ihre Start-URL ein:
dir_action=navigate: Dieser Parameter erzwingt die aktive Navigation.action_token: Dieser Parameter enthält Ihr authentifiziertes Fahrt-Token.
In den folgenden Beispielen wird gezeigt, 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 Ihre Start-URL ein:
navigate=yes: Dieser Parameter erzwingt die aktive Navigation.external_trip_token: Mit diesem Parameter wird Ihr authentifiziertes Fahrt-Token angegeben.
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 Fahrt mit Navigation Connect starten möchten, müssen Sie Ihrer App unter Android eine Navigationssitzung zuweisen. Geben Sie dazu 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 können. Eine fehlende oder ungültige Anwendungs-ID führt dazu, dass die Authentifizierung des Fahrt-Tokens fehlschlägt.
Wenn Sie Ihre Anwendungs-ID angeben, können Sie folgende Funktionen nutzen:
- Datenfreigabe autorisieren:Prüft, ob Ihre App berechtigt ist, Daten zu aktiven Fahrten zu empfangen.
- Fahrereinwilligung aktivieren:Auf dem Einwilligungsbildschirm werden Ihr Unternehmensname und Ihre Datenschutzerklärung angezeigt, damit der Fahrer weiß, wer seinen Echtzeitstandort und seine voraussichtliche Ankunftszeit erhält.
- Schaltfläche „Zurück“ aktivieren:Google Maps oder Waze können eine gebrandete Schaltfläche „Zurück“ 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.
Im folgenden Beispiel wird gezeigt, wie Sie den Paketnamen dem Intent hinzufügen:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
Fahrer zur Rückkehr zu Ihrer App bewegen
Navigation Connect zeigt eine untere Leiste (Google Maps) oder eine markenspezifische 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 eine PendingIntent erstellen, die auf die Aktivität Ihrer App verweist. Hängen Sie diesen PendingIntent als Extra an die Startabsicht an. Verwenden Sie dazu den genauen Schlüssel "pendingIntent". Wenn der Nutzer auf die Schaltfläche „Zurück“ tippt, wird dieser Intent von Google Maps oder Waze ausgeführt, um Ihre App in den Vordergrund zu holen.
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 Universal 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 den Button „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, mit der eine Navigation Connect-Sitzung mit den erforderlichen Parametern gestartet wird.
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)
}
}