Abra o Google Maps ou o Waze.

Para iniciar a sessão de navegação, seu app precisa criar dinamicamente um URL de inicialização para abrir o Google Maps ou o Waze. Este guia descreve como usar o token de viagem autenticado de Criar uma viagem para iniciar o Google Maps ou o Waze e configurar a experiência de retorno ao seu app.

Como iniciar o Google Maps ou o Waze

Para iniciar o Google Maps ou o Waze, você precisa fornecer uma maneira de permitir que os motoristas iniciem uma sessão de navegação no seu app, criar o URL de inicialização com os parâmetros necessários e fornecer o ID do aplicativo para atribuir a sessão.

Permitir que os motoristas iniciem a navegação no seu app

Você precisa fornecer uma maneira para os motoristas iniciarem a navegação no seu app. Se você permitir que os motoristas iniciem o Google Maps ou o Waze usando um botão, garanta a atribuição adequada e evite confusão rotulando-o claramente. Por exemplo, coloque o texto "Google Maps" ou "Waze" no botão ou perto dele.

Criar o URL de inicialização

Para iniciar uma sessão de navegação, crie um URL de inicialização do Navigation Connect. Esse URL é uma string que contém o destino, o token de viagem e os parâmetros de navegação necessários. Ele funciona de maneira semelhante a um URL padrão do Google Maps ou a um link direto do Waze.

Para iniciar o Google Maps ou o Waze no dispositivo do motorista, use o mecanismo específico da plataforma:

  • Android:transmita a string de URL em uma Intent.
  • iOS:use a string de URL como um link universal (ou link direto).

Formatar o destino

Para garantir que o Google Maps ou o Waze possa calcular um trajeto com sucesso, siga estas regras ao formatar o destino:

  • Especifique exatamente um destino acessível. Você pode transmitir o destino como uma string de endereço, coordenadas de latitude/longitude ou um ID de lugar.

  • Não use vários pontos de referência. Se você transmitir vários pontos de referência diretamente no URL, o Google Maps ou o Waze vai mostrar um erro. Em vez disso, crie viagens separadas.

Adicionar o token de viagem e os parâmetros de navegação

Para concluir o URL de inicialização, inclua o token de viagem autenticado que você recebeu da solicitação Criar uma viagem. Você também precisa incluir os parâmetros de navegação que informam ao Google Maps ou ao Waze para iniciar a navegação ativa.

Google Maps

Para o Google Maps, inclua os seguintes parâmetros no URL de inicialização:

  • dir_action=navigate: esse parâmetro força a navegação ativa.
  • action_token: esse parâmetro fornece o token de viagem autenticado.

Os exemplos a seguir mostram como formatar o URL de inicialização do Google Maps usando diferentes formatos de destino:

  • Coordenadas de latitude/longitude: 
    https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
  • String de endereço: 
    https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
  • ID de lugar: 
    https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN

Waze

Para o Waze, inclua os seguintes parâmetros no URL de inicialização:

  • navigate=yes: esse parâmetro força a navegação ativa.
  • external_trip_token: esse parâmetro fornece o token de viagem autenticado.

Os exemplos a seguir mostram como formatar o URL de inicialização do Waze usando diferentes formatos de destino:

  • Coordenadas de latitude/longitude: 
    https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
  • String de endereço: 
    https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
  • ID de lugar: 
    https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

Fornecer o ID do aplicativo (somente Android)

Para atribuir uma sessão de navegação ao seu app no Android, forneça o ID do aplicativo verificado. Isso identifica seu app como a origem da viagem para que o Google Maps ou o Waze possa vincular a jornada ativa à sua plataforma.

Fornecer o ID do aplicativo ativa os seguintes recursos:

  • Autorizar o compartilhamento de dados pessoais:verifica se seu app está autorizado a receber dados de viagens ativas.
  • Ativar o consentimento do motorista:preenche a tela de permissão com o nome da empresa e a Política de Privacidade, garantindo que o motorista saiba quem está recebendo a localização em tempo real e a previsão de chegada.
  • Ativar o botão de retorno:permite que o Google Maps ou o Waze crie um botão de retorno com marca para que os motoristas possam voltar ao seu app.

Para transmitir o ID do aplicativo ao Google Maps ou ao Waze no Android, adicione o nome do pacote à intent de inicialização (que contém a string do URL de inicialização) usando Intent.EXTRA_REFERRER_NAME.

O exemplo a seguir mostra como adicionar o nome do pacote à intent:

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

Como permitir que os motoristas retornem ao seu app

App Google Maps com uma barra inferior que tem o botão "Voltar", o nome do app e o ícone de compartilhamento de dados pessoais, à esquerda. App Waze com botão "Voltar" personalizado à direita.

O Navigation Connect mostra uma barra inferior (Google Maps) ou um botão "Voltar" com marca (Waze) para que o motorista possa voltar ao seu app a qualquer momento durante a viagem ou quando chegar ao destino.

Android

Você precisa criar uma PendingIntent que aponte de volta para a atividade do seu app. Anexe este PendingIntent como um extra à intent de inicialização usando a chave exata "pendingIntent". Quando o usuário toca no botão de retorno, o Google Maps ou o Waze executa essa intent para trazer seu app para o primeiro plano. 

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

iOS (somente Waze)

Não é necessário adicionar nada ao URL de inicialização para ativar o botão de retorno. O Waze usa automaticamente o link universal que você registrou ao verificar seu app.

Amostras de código

Os exemplos de código a seguir mostram como iniciar o Google Maps ou o Waze no seu app usando o Navigation Connect e ativar o botão "Voltar ao app".

Google Maps (Android)

O código Kotlin a seguir mostra uma função de exemplo que inicia uma sessão do Navigation Connect com os parâmetros necessários. 

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)

O código Kotlin a seguir mostra uma função de exemplo que inicia uma sessão do Navigation Connect com os parâmetros necessários. 

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)

O código Swift a seguir mostra uma função de exemplo que inicia uma sessão do Navigation Connect com os parâmetros necessários. 

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