Para iniciar la sesión de navegación, tu app debe construir de forma dinámica una URL de inicio que abra 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 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 tu ID de 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 les permites iniciar Google Maps o Waze con un botón, asegúrate de que se atribuya correctamente y de etiquetarlo de forma clara para evitar confusiones. 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 de Google Maps o un vínculo directo de Waze estándar.
Para iniciar Google Maps o Waze en el dispositivo del conductor, usa el mecanismo específico de la plataforma:
- Android: Pasa la cadena de la URL en un
Intent. - iOS: Usa la cadena de URL como un vínculo universal (o vínculo directo).
Formatea el destino
Para asegurarte de que Google Maps o Waze puedan calcular una ruta correctamente, cumple con las siguientes reglas cuando des formato a 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 independientes.
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=navigateaction_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
-
ID de lugar:
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
Proporciona tu ID de 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 verificado. Esto identifica tu app como la fuente del viaje para que Google Maps o Waze puedan vincular el viaje activo con 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.
Si proporcionas tu ID de aplicación, se habilitarán las siguientes funciones:
- Autoriza el uso compartido de datos: Verifica que tu app esté autorizada para recibir datos de viajes activos.
- Habilitar el consentimiento del conductor: Completa 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 la hora de llegada estimada.
- 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 de tu paquete al
intent de inicio (que contiene la cadena de la 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 Atrás con la marca (Waze) para que el conductor pueda volver a tu app sin problemas en cualquier momento durante el viaje o cuando llegue al destino.
Android
Debes crear un PendingIntent que apunte de vuelta a la actividad de tu app. Adjunta este PendingIntent como un elemento adicional 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 que tu app pase a 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 indica 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 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)
En el siguiente código de Kotlin, se 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)
En el siguiente código de Swift, se 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)
}
}