Inicia Google Maps o Waze

Para iniciar la sesión de navegación, tu app debe crear de forma dinámica una URL de inicio para abrir Google Maps o Waze. En esta guía, se describe cómo usar el token de viaje autenticado de Crea un viaje para iniciar Google Maps o Waze y configurar la experiencia de regreso a tu app.

Cómo iniciar Google Maps o Waze

Para iniciar Google Maps o Waze, debes proporcionar una forma para que los conductores inicien una sesión de navegación desde tu app, crear la URL de inicio con los parámetros obligatorios y proporcionar el ID de tu aplicación para atribuir la sesión.

Permite que los conductores inicien la navegación desde tu app

Debes proporcionar una forma para que los conductores inicien la navegación desde tu app. Si permites que los conductores inicien Google Maps o Waze con un botón, asegúrate de que la atribución sea correcta y evita la confusión etiquetándolo claramente. Por ejemplo, coloca el texto "Google Maps" o "Waze" en el botón o cerca de él.

Crea la URL de inicio

Para iniciar una sesión de navegación, crea una URL de inicio de Navigation Connect. Esta URL es una cadena que contiene el destino, el token de viaje y los parámetros de navegación obligatorios. Funciona de manera similar a una URL estándar de Google Maps o un vínculo directo de Waze.

Para iniciar Google Maps o Waze en el dispositivo del conductor, usa el mecanismo específico de la plataforma:

• Android: Pasa la cadena de URL en un Intent.
• iOS: Usa la cadena de URL como un vínculo universal (o vínculo directo).

Da formato al destino

Para asegurarte de que Google Maps o Waze puedan calcular una ruta correctamente, sigue las siguientes reglas cuando des formato a tu destino:

• Especifica exactamente un destino alcanzable. Puedes pasar el destino como una cadena de dirección, coordenadas de latitud y longitud, o un ID de lugar.

• No uses varios puntos de ruta. Si pasas varios puntos de ruta directamente en la URL, Google Maps o Waze mostrarán un error. En su lugar, crea viajes separados.

Nota: No pases un origen de inicio personalizado en la URL de inicio. Google Maps o Waze usan automáticamente la ubicación actual del conductor cuando se inicia la sesión. Para evitar errores de "Origen no encontrado", exige a tus conductores que habiliten el seguimiento de ubicación precisa.

Agrega el token de viaje y los parámetros de navegación

Para completar la URL de inicio, debes incluir el token de viaje autenticado que recibiste de la solicitud Crea un viaje. También debes incluir los parámetros de navegación que le indican a Google Maps o Waze que inicien la navegación activa.

Google Maps

En el caso de Google Maps, incluye los siguientes parámetros en tu URL de inicio:

• dir_action=navigate: Este parámetro fuerza la navegación activa.
• action_token: Este parámetro proporciona tu token de viaje autenticado.

En los siguientes ejemplos, se muestra cómo dar formato a la URL de inicio de Google Maps con diferentes formatos de destino:

• Coordenadas de latitud y longitud:

  https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN

• Cadena de dirección:

  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

En el caso de Waze, incluye los siguientes parámetros en tu URL de inicio:

• navigate=yes: Este parámetro fuerza la navegación activa.
• external_trip_token: Este parámetro proporciona tu token de viaje autenticado.

En los siguientes ejemplos, se muestra cómo dar formato a la URL de inicio de Waze con diferentes formatos de destino:

• Coordenadas de latitud y longitud:

  https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN

• Cadena de dirección:

  https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN

  Nota: Waze navega al primer resultado de la búsqueda de cadenas de dirección.
• ID de lugar:

  https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

Proporciona el ID de tu aplicación (solo para Android)

Para atribuir una sesión de navegación a tu app en Android, proporciona tu ID de aplicación verificada. Esto identifica tu app como la fuente del viaje para que Google Maps o Waze puedan vincular el viaje activo a tu plataforma.

Nota: En el caso de iOS, deberías haber proporcionado el ID de aplicación en el CreateTripRequest mensaje. Consulta Crea un viaje para obtener más detalles.

Proporcionar el ID de tu aplicación habilita las siguientes funciones:

• Autorizar el uso compartido de datos: Verifica que tu app esté autorizada para recibir datos de viajes activos.
• Habilitar el consentimiento del conductor: Propaga la pantalla de consentimiento con el nombre de tu empresa y la política de privacidad, lo que garantiza que el conductor sepa quién recibe su ubicación en tiempo real y su ETA.
• Habilitar el botón de regreso: Permite que Google Maps o Waze creen un botón de regreso con la marca para que los conductores puedan volver a tu app.

Para pasar el ID de aplicación a Google Maps o Waze en Android, agrega el nombre del paquete al intent de inicio (que contiene la cadena de URL de inicio) con Intent.EXTRA_REFERRER_NAME.

En el siguiente ejemplo, se muestra cómo agregar el nombre del paquete al intent:

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

Cómo permitir que los conductores regresen a tu app

Navigation Connect muestra una barra inferior (Google Maps) o un botón de regreso con la marca (Waze) para que el conductor pueda volver a tu app en cualquier momento durante el viaje o cuando llegue al destino.

Android

Debes crear un PendingIntent que vuelva a la actividad de tu app. Conecta este PendingIntent como un extra al intent de inicio con la clave exacta "pendingIntent". Cuando el usuario presiona el botón de regreso, Google Maps o Waze ejecutan este intent para llevar tu app al primer plano.

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

iOS (solo Waze)

No es necesario que agregues nada a la URL de inicio para habilitar el botón de regreso. Waze usa automáticamente el vínculo universal que registraste cuando verificaste tu app.

Muestras de código

En las siguientes muestras de código, se muestra cómo iniciar Google Maps o Waze desde tu app con Navigation Connect y habilitar el botón "Volver a la app".

Google Maps (Android)

En el siguiente código de Kotlin, se muestra una función de muestra que inicia una sesión de Navigation Connect con los parámetros obligatorios.

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)

En el siguiente código de Kotlin, se muestra una función de muestra que inicia una sesión de Navigation Connect con los parámetros obligatorios.

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)

En el siguiente código de Swift, se muestra una función de muestra que inicia una sesión de Navigation Connect con los parámetros obligatorios.

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