Inicia Google Maps o Waze

Para iniciar la sesión de navegación, tu app debe crear de forma dinámica una URL de lanzamiento para abrir Google Maps o Waze. En esta guía, se describe cómo usar el token de viaje autenticado de Create a trip 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 de permitir que los conductores inicien una sesión de navegación desde tu app, crear la URL de inicio con los parámetros requeridos 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 confusiones etiquetándolo claramente. Por ejemplo, coloca el texto "Google Maps" o "Waze" en el botón o cerca de él.

Cómo construir la URL de lanzamiento

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 del viaje y los parámetros de navegación obligatorios. Funciona de manera similar a una URL de Google Maps o un vínculo directo de Waze estándar.

Importante: Navigation Connect solo admite la conducción. No configures modos de viaje que no sean de conducción (como a pie, en bicicleta o en transporte público) en tus URLs de lanzamiento. Si el conductor navega en un modo que no es de conducción, Navigation Connect no devolverá actualizaciones de telemetría ni información del tráfico.

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

Cómo darle formato al destino

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

• Especifica exactamente un destino accesible. 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 referencia. Si pasas varios puntos de referencia 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 lanzamiento. 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 preciso.

Agrega parámetros de navegación y tokens de viaje

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

Google Maps

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

• 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 la URL de lanzamiento:

• 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 direcciones.
• 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 iniciar un viaje con Navigation Connect, debes atribuir una sesión de navegación a tu app en Android. Para ello, 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. Si falta el ID de aplicación o no es válido, se producirá un error en la autenticación del token de viaje.

Nota: En iOS, debes haber proporcionado el ID de aplicación en el mensaje de CreateTripRequest. Consulta Cómo crear un viaje para obtener más información.

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

• Autoriza el uso compartido de datos: Verifica que tu app esté autorizada para recibir datos de viajes activos.
• Habilita el consentimiento del conductor: La pantalla de consentimiento se completa 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.
• Habilita 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 la aplicación a Google Maps o Waze en Android, agrega el nombre del paquete a la intención 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 atrás con la marca (Waze) para que el conductor pueda volver sin problemas a tu app en cualquier momento durante el viaje o cuando llegue al destino.

Android

Debes crear un PendingIntent que apunte a la actividad de tu app. Adjunta este PendingIntent como un extra al intent de inicio con la clave exacta "pendingIntent". Cuando el usuario presiona el botón de volver, 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 lanzamiento 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)

El siguiente código en Kotlin muestra una función de ejemplo que inicia una sesión de Navigation Connect con los parámetros requeridos.

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)

El siguiente código en Kotlin muestra una función de ejemplo que inicia una sesión de Navigation Connect con los parámetros requeridos.

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)

El siguiente código en Swift muestra una función de ejemplo que inicia una sesión de Navigation Connect con los parámetros requeridos.

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