Uruchamianie Map Google lub Waze

Aby rozpocząć sesję nawigacji, aplikacja musi dynamicznie utworzyć adres URL uruchamiania, który otworzy Mapy Google lub Waze. Z tego przewodnika dowiesz się, jak używać uwierzytelnionego tokena podróży z usługi Create a trip do uruchamiania Map Google lub Waze oraz jak skonfigurować powrót do aplikacji.

Jak uruchomić Mapy Google lub Waze

Aby uruchomić Mapy Google lub Waze, musisz umożliwić kierowcom rozpoczęcie sesji nawigacji z poziomu aplikacji, utworzyć adres URL uruchamiania z wymaganymi parametrami i podać identyfikator aplikacji, aby przypisać sesję.

Umożliwienie kierowcom rozpoczęcia nawigacji z poziomu aplikacji

Musisz umożliwić kierowcom rozpoczęcie nawigacji z poziomu aplikacji. Jeśli pozwolisz kierowcom na uruchamianie Map Google lub Waze za pomocą przycisku, zadbaj o prawidłowe przypisanie i unikaj nieporozumień, wyraźnie oznaczając przycisk. Na przykład umieść tekst „Mapy Google” lub „Waze” na przycisku lub w jego pobliżu.

Tworzenie adresu URL uruchamiania

Aby rozpocząć sesję nawigacji, utwórz adres URL uruchamiania Navigation Connect. Ten adres URL to ciąg znaków zawierający miejsce docelowe, token podróży i wymagane parametry nawigacji. Działa podobnie jak standardowy adres URL Map Google lub precyzyjny link Waze.

Aby uruchomić Mapy Google lub Waze na urządzeniu kierowcy, użyj mechanizmu specyficznego dla platformy:

  • Android: przekaż ciąg znaków adresu URL w Intent.
  • iOS: użyj ciągu znaków adresu URL jako linku uniwersalnego (lub precyzyjnego linku).

Formatowanie miejsca docelowego

Aby Mapy Google lub Waze mogły prawidłowo obliczyć trasę, podczas formatowania miejsca docelowego przestrzegaj tych zasad:

  • Określ dokładnie 1 osiągalne miejsce docelowe. Miejsce docelowe możesz przekazać jako ciąg znaków adresu, współrzędne geograficzne lub identyfikator miejsca.

  • Nie używaj wielu punktów pośrednich. Jeśli przekażesz wiele punktów pośrednich bezpośrednio w adresie URL, Mapy Google lub Waze wyświetlą błąd. Zamiast tego utwórz osobne podróże.

Dodawanie tokena podróży i parametrów nawigacji

Aby uzupełnić adres URL uruchamiania, musisz dodać uwierzytelniony token podróży, który został otrzymany w odpowiedzi na żądanie Create a trip. Musisz też dodać parametry nawigacji, które informują Mapy Google lub Waze o rozpoczęciu aktywnej nawigacji.

Mapy Google

W przypadku Map Google w adresie URL uruchamiania uwzględnij te parametry:

  • dir_action=navigate: Ten parametr wymusza aktywną nawigację.
  • action_token: ten parametr zawiera uwierzytelniony token podróży.

Poniższe przykłady pokazują, jak sformatować adres URL uruchamiania w Mapach Google przy użyciu różnych formatów miejsca docelowego:

  • Współrzędne geograficzne: 
    https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
  • Ciąg znaków adresu: 
    https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
  • Identyfikator miejsca: 
    https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN

Waze

W przypadku Waze w adresie URL uruchamiania uwzględnij te parametry:

  • navigate=yes: ten parametr wymusza aktywną nawigację.
  • external_trip_token: ten parametr zawiera uwierzytelniony token podróży.

Poniższe przykłady pokazują, jak sformatować adres URL uruchamiania w Waze przy użyciu różnych formatów miejsca docelowego:

  • Współrzędne geograficzne: 
    https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
  • Ciąg znaków adresu: 
    https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
  • Identyfikator miejsca: 
    https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

Podawanie identyfikatora aplikacji (tylko na Androidzie)

Aby przypisać sesję nawigacji do aplikacji na Androidzie, podaj zweryfikowany identyfikator aplikacji. Identyfikuje on aplikację jako źródło podróży, dzięki czemu Mapy Google lub Waze mogą połączyć aktywną podróż z Twoją platformą.

.

Podanie identyfikatora aplikacji umożliwia korzystanie z tych funkcji:

  • Autoryzacja udostępniania danych: sprawdza, czy aplikacja jest uprawniona do otrzymywania danych o podróży.
  • Włączanie zgody kierowcy: wypełnia ekran zgody nazwą firmy i polityką prywatności, dzięki czemu kierowca wie, kto otrzymuje jego lokalizację w czasie rzeczywistym i szacowany czas dotarcia.
  • Włączanie przycisku powrotu: umożliwia Mapom Google lub Waze utworzenie przycisku powrotu z Twoją marką, aby kierowcy mogli wrócić do Twojej aplikacji.

Aby przekazać identyfikator aplikacji do Map Google lub Waze na Androidzie, dodaj nazwę pakietu do intencji uruchamiania (która zawiera ciąg znaków adresu URL uruchamiania) za pomocą Intent.EXTRA_REFERRER_NAME.

Ten przykład pokazuje, jak dodać nazwę pakietu do intencji:

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

Umożliwianie kierowcom powrotu do aplikacji

Aplikacja Mapy Google z paskiem dolnym, na którym po lewej stronie znajdują się przycisk Wstecz, nazwa aplikacji i ikona udostępniania danych. Aplikacja Waze z przyciskiem Wstecz z logo po prawej stronie.

Navigation Connect wyświetla pasek dolny (Mapy Google) lub przycisk Wstecz z Twoją marką (Waze), dzięki czemu kierowca może w dowolnym momencie podróży lub po dotarciu do miejsca docelowego bezproblemowo wrócić do Twojej aplikacji.

Android

Musisz utworzyć PendingIntent, który będzie wskazywać aktywność aplikacji. Dołącz ten PendingIntent jako dodatkowy element do intencji uruchamiania, używając dokładnego klucza "pendingIntent". Gdy użytkownik kliknie przycisk powrotu, Mapy Google lub Waze wykonają tę intencję, aby przenieść Twoją aplikację na pierwszy plan. 

intent.putExtra("pendingIntent", getPendingIntent())

iOS (tylko Waze)

Aby włączyć przycisk powrotu, nie musisz nic dodawać do adresu URL uruchamiania. Waze automatycznie używa linku uniwersalnego, który został zarejestrowany podczas weryfikacji aplikacji.

Przykładowe fragmenty kodu

Te przykładowe fragmenty kodu pokazują, jak uruchomić Mapy Google lub Waze z poziomu aplikacji za pomocą Navigation Connect i włączyć przycisk „Wróć do aplikacji”.

Mapy Google (Android)

Ten kod w języku Kotlin pokazuje przykładową funkcję, która uruchamia sesję Navigation Connect z wymaganymi parametrami. 

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)

Ten kod w języku Kotlin pokazuje przykładową funkcję, która uruchamia sesję Navigation Connect z wymaganymi parametrami. 

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)

Ten kod w języku Swift pokazuje przykładową funkcję, która uruchamia sesję Navigation Connect z wymaganymi parametrami. 

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)
        }
       }