Google Maps oder Waze starten

Um die Navigation zu starten, muss Ihre App dynamisch eine Start-URL erstellen, um Google Maps oder Waze zu öffnen. In diesem Leitfaden wird beschrieben, wie Sie das authentifizierte Fahrttoken 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. Außerdem müssen Sie die Start-URL mit den erforderlichen Parametern erstellen und Ihre Anwendungs-ID angeben, um die Sitzung zuzuordnen.

Fahrer können die Navigation über Ihre App starten

Sie sollten Fahrern die Möglichkeit bieten, die Navigation über Ihre App zu starten. Wenn Sie Fahrern die Möglichkeit geben, Google Maps oder Waze über eine Schaltfläche zu starten, achten Sie auf eine korrekte Zuordnung und vermeiden Sie Verwirrung, indem Sie die Schaltfläche klar kennzeichnen. Platzieren Sie beispielsweise den Text „Google Maps“ oder „Waze“ auf oder in der Nähe der Schaltfläche.

Start-URL erstellen

Wenn Sie eine Navigationssitzung starten möchten, 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 standardmäßige 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 kann, müssen Sie beim Formatieren des Ziels die folgenden Regeln beachten:

  • 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.

Fahrttoken und Navigationsparameter hinzufügen

Um die Start-URL zu vervollständigen, müssen Sie das authentifizierte Fahrttoken angeben, das Sie über die Anfrage Fahrt erstellen erhalten haben. Außerdem müssen Sie die Navigationsparameter angeben, die Google Maps oder Waze mitteilen, dass die aktive Navigation gestartet werden soll.

Google Maps

Fügen Sie für Google Maps die folgenden Parameter in die Start-URL ein:

  • dir_action=navigate: Mit diesem Parameter wird die aktive Navigation erzwungen.
  • action_token: Dieser Parameter liefert Ihr authentifiziertes Fahrttoken.

In den folgenden Beispielen wird gezeigt, wie die Start-URL für Google Maps mit verschiedenen Zielformaten formatiert wird:

  • Breiten- und Längengrad:
    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: Mit diesem Parameter wird das authentifizierte Fahrttoken angegeben.

Die folgenden Beispiele zeigen, wie die Start-URL für Waze mit verschiedenen Zielformaten formatiert wird:

  • Breiten- und Längengrad:
    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 kann. Eine fehlende oder ungültige Anwendungs-ID führt zu einer fehlgeschlagenen Authentifizierung des Fahrt-Tokens.

Wenn Sie Ihre Anwendungs-ID angeben, werden die folgenden Funktionen aktiviert:

  • Datenweitergabe autorisieren: Es wird geprüft, ob Ihre App berechtigt ist, Daten zu aktiven Fahrten zu empfangen.
  • Einwilligung des Fahrers aktivieren: Auf dem Zustimmungsbildschirm werden Ihr Unternehmensname und Ihre Datenschutzerklärung angezeigt. So weiß der Fahrer, wer seinen Echtzeitstandort und seine voraussichtliche Ankunftszeit erhält.
  • Schaltfläche „Zurück“ aktivieren: Google Maps oder Waze können eine Schaltfläche „Zurück“ mit Ihrem Branding erstellen, damit Fahrer zu Ihrer App zurückwechseln können.

Wenn Sie die Anwendungs-ID unter Android an Google Maps oder Waze übergeben möchten, fügen Sie dem Start-Intent (der den Start-URL-String enthält) mit Intent.EXTRA_REFERRER_NAME Ihren Paketnamen hinzu.

Im folgenden Beispiel wird gezeigt, wie der Paketname dem Intent hinzugefügt wird:

intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")

Fahrern die Rückkehr zu Ihrer App ermöglichen

Google Maps App mit einer Leiste am unteren Rand, die links den Zurück-Button, den App-Namen und das Symbol für die Datenweitergabe enthält. Waze App mit gebrandetem Button „Zurück“ auf der rechten Seite

Navigation Connect zeigt eine untere Leiste (Google Maps) oder eine gebrandete Zurück-Schaltfläche (Waze) an, damit der Fahrer jederzeit während der Fahrt oder bei der Ankunft am Ziel nahtlos zu Ihrer App zurückwechseln kann.

Android

Du musst einen PendingIntent erstellen, der auf die Aktivität deiner App verweist. Hänge diesen PendingIntent als Extra an den Start-Intent an und verwende dabei genau den Schlüssel "pendingIntent". Wenn der Nutzer auf die Schaltfläche „Zurück“ tippt, führt Google Maps oder Waze diesen 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

In den folgenden Codebeispielen wird gezeigt, wie Sie Google Maps oder Waze über Navigation Connect aus Ihrer App 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)
        }
       }