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 Create a trip verwenden, um Google Maps oder Waze zu starten und die Rückgabe an Ihre 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. Dazu 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 der Schaltfläche.
Start-URL erstellen
Um eine Navigationssitzung zu starten, erstellen Sie eine Start-URL für Navigation Connect. 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 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 Ihr Ziel so formatieren, dass es den folgenden Regeln entspricht:
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.
Fügen Sie Parameter für Fahrt-Tokens und Navigation hinzu.
Um die Start-URL zu vervollständigen, müssen Sie das authentifizierte Fahrt-Token einfügen, das Sie über die Anfrage Fahrt erstellen erhalten haben. Sie müssen auch die Navigationsparameter angeben, mit denen Google Maps oder Waze angewiesen werden, 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: Mit diesem Parameter wird die aktive Navigation erzwungen.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- und 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: Mit diesem Parameter wird die aktive Navigation erzwungen.external_trip_token: Dieser Parameter enthält Ihr authentifiziertes Fahrt-Token.
In den folgenden Beispielen wird gezeigt, wie die Start-URL für Waze mit verschiedenen Zielformaten formatiert wird:
-
Breiten- und 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 können.
Wenn Sie Ihre Anwendungs-ID angeben, können Sie die folgenden Funktionen nutzen:
- Datenfreigabe autorisieren:Hier wird geprü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 für die Rückkehr aktivieren:Google Maps oder Waze können eine gebrandete Schaltfläche für die Rückkehr 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 den Start-Intent hinzu, der 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ück zu Ihrer App leiten
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 Zielort 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 den Start-Intent 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 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, 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)
}
}