Cuando recuperas los datos de tu viaje, tu backend recibe cargas útiles de JSON que detallan el progreso del viaje del conductor. Analiza estas cargas útiles para supervisar el viaje, actualizar tus sistemas de despacho y determinar los estados actuales del viaje para determinar el siguiente paso para el conductor a medida que avanza o cuando finaliza un viaje.
Lee la carga útil de datos
Google Maps o Waze envían las cargas útiles de datos del viaje a los servidores de Navigation Connect cuando el conductor comienza a navegar, periódicamente a lo largo de la ruta (cada 60 segundos de forma predeterminada) y cuando llega al destino. Cada mensaje JSON contiene datos de viaje relevantes, incluidas las coordenadas del conductor ajustadas a la ruta, la distancia recorrida y la hora estimada de llegada (ETA).
En el siguiente ejemplo de código, se muestra una carga útil de datos de viaje para cuando un conductor comienza a navegar para un viaje desde King's Cross hasta Central St. Giles.
{
"name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
"state": "ENROUTE",
"execution": {
"origin": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
}
},
"destination": {
"point": {
"latitude": 51.515598,
"longitude": -0.1277623
}
},
"location": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
},
"sourceTime": "2025-05-30T12:37:26Z",
"serverTime": "2025-05-30T12:37:26.221069Z"
},
"traveledDuration": "0s",
"remainingDuration": "990s",
"traveledDistanceMeters": 0,
"remainingDistanceMeters": 2879,
"stopAddedInRoute": false
}
}
Supervisa los estados de viaje activos
Para confirmar un inicio exitoso y supervisar el progreso, evalúa el campo de estado en cada carga útil.
| Estado | Descripción |
|---|---|
NEW |
Se creó el viaje, pero el conductor aún no comenzó a navegar. |
ENROUTE |
El conductor está navegando activamente hacia el destino. Usa este estado para confirmar que el viaje se autenticó y se inició correctamente. |
Controla las paradas agregadas
Los conductores pueden agregar paradas a su ruta durante la navegación. Si lo hacen, Navigation Connect establece el campo execution.stopAddedInRoute en true en la carga útil de datos JSON. La API de Navigation Connect continúa haciendo un seguimiento del conductor hacia el destino original. Las métricas, como la hora estimada de llegada (ETA), la distancia y la duración, aumentan para incluir las paradas agregadas.
El comportamiento para agregar paradas depende de la app de navegación y coincide con su funcionalidad estándar:
- Google Maps: Los conductores pueden agregar varias paradas a su ruta.
- Waze: Los conductores solo pueden agregar una parada. Si un conductor intenta agregar otra parada, Waze le solicita que inicie una nueva sesión de navegación en lugar de agregar la parada a la ruta actual.
No es necesario que ajustes las entradas de backend para admitir esta función.
Soluciona problemas de autenticación y de inicio
Si no recibes un estado ENROUTE, es probable que se haya producido un error de autenticación. Las causas comunes incluyen parámetros de API mal escritos o un token de viaje vencido. Verifica la hora de vencimiento del token en tu respuesta inicial CreateTrip.
Si el estado no cambia de NEW a ENROUTE, es posible que el dispositivo del conductor impida la autenticación. Navigation Connect no envía mensajes de error para estos casos. Verifica la siguiente información:
- El conductor tiene instalada la versión 5.15.5 o posterior de Waze, o la versión 26.14 o posterior de Google Maps.
- El conductor no usa Android Auto ni Apple CarPlay.
- El conductor tiene una conexión a Internet activa.
Controla los datos de la ruta restante (solo en Waze)
Si habilitaste el informe de la ruta restante durante la creación del viaje, tu backend recibe la polilínea de la ruta activa y las condiciones del tráfico en tiempo real desde la ubicación actual del conductor hasta su destino final.
Puedes ingerir y procesar estos datos para potenciar varias funciones en tus aplicaciones, incluidos los siguientes ejemplos:
- Potencia los mapas de seguimiento en vivo: Renderiza la polilínea de la ruta restante en un mapa web o para dispositivos móviles orientado al cliente para proporcionar visibilidad del viaje del conductor.
- Mejora la precisión de la ETA: Combina la polilínea ajustada a la ruta y las velocidades de los intervalos de tráfico para mejorar la logística interna o las predicciones de llegada de las entregas.
- Analiza el cumplimiento de la ruta: Compara la geometría de la ruta restante con las rutas de despacho esperadas para evaluar la adherencia del conductor.
Navigation Connect muestra los detalles de la ruta restante en el campo execution.remainingRoute, ya sea que envíes una solicitud GetTrip o recibas actualizaciones basadas en eventos con Google Cloud Pub/Sub. Sin embargo, la forma en que la carga útil da formato y estructura estos datos depende del método de recuperación que uses.
Método GetTrip
Cuando llamas al método GetTrip, el formato de respuesta de la polilínea depende del parámetro routePolylineFormat que especificaste en tu solicitud. Para obtener más
información, consulta Personaliza los formatos de polilíneas.
Para todos los formatos de polilíneas, Navigation Connect muestra el tráfico como una lista separada de objetos SpeedReadingInterval en el campo execution.remainingRoute.trafficInformation. Estos objetos asignan categorías de tráfico a los índices de polilíneas con los siguientes valores:
startPolylinePointIndex: Es el índice inicial del intervalo de tráfico en la polilínea.endPolylinePointIndex: Es el índice final del intervalo de tráfico.speed: Es la categoría de tráfico para este segmento:NORMAL,SLOWoTRAFFIC_JAM.
Actualizaciones de Google Cloud Pub/Sub
Cuando recuperas datos de viajes con Pub/Sub,
las actualizaciones siempre muestran datos de la ruta restante en un GeoJSON unificado
FeatureCollection en el campo execution.remainingRoute.
Este formato combina directamente la geometría de la polilínea con las velocidades del tráfico, lo que elimina la necesidad de asignar índices de forma manual.
Consulta un ejemplo de carga útil de Pub/Sub
En la siguiente muestra de código, se muestra la estructura GeoJSON que se muestra en el campo execution.remainingRoute dentro del objeto updatedTrip de un mensaje de Pub/Sub:
{ "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.3934, 37.7955], [-122.4010, 37.7980] ] }, "properties": { "speed": "SLOW" } }, { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.4010, 37.7980], [-122.4058, 37.8025], [-122.4187, 37.8021] ] }, "properties": { "speed": "NORMAL" } } ] }
Optimiza el tamaño de la carga útil
Debido a que los arrays de coordenadas son grandes, incluir datos de la ruta restante en tus mensajes de Pub/Sub puede aumentar significativamente el tamaño de la carga útil (hasta 13 o 14 KB por mensaje). Si recibes actualizaciones de alta frecuencia, este volumen puede aumentar la carga de procesamiento de backend y los costos de uso.
Para optimizar tu transmisión, usa el parámetro pubsubFieldMask en tu objeto TripConfig durante la creación del viaje para excluir campos pesados. Para
obtener más información, consulta Configuraciones opcionales.
Controla los estados finales del viaje
Cuando un conductor llega al destino o deja de navegar, la carga útil muestra uno de los siguientes estados finales. Usa estos estados para activar los siguientes pasos adecuados en tu app.
| Estado | Descripción | Acción recomendada |
|---|---|---|
ARRIVED |
El conductor llegó al destino. | Verifica el valor de remainingDistanceMeters. Si el conductor estacionó
cerca, pero no en las coordenadas exactas, considera proporcionar instrucciones para llegar a pie
en tu app. |
SUSPENDED |
El conductor salió manualmente de la navegación paso a paso antes de llegar
al destino. Como Google Maps o Waze no muestran automáticamente a los conductores en tu app cuando salen de una sesión antes de tiempo, el conductor debe presionar manualmente el botón de volver. |
Para ayudar a los conductores a completar su viaje, compara
execution.location con el destino. Si queda distancia
proporciona un botón o un vínculo para reanudar el viaje o cambiar al modo de caminata. |
FAILED |
Un error técnico interrumpió la conexión. Esto ocurre si la app no puede calcular una ruta o aparece una advertencia de seguridad. Es posible que el conductor siga navegando, pero no recibirás actualizaciones. | Vuelve al seguimiento manual del estado en tu app. |
CLIENT_ERROR |
Este estado aparece por uno de los siguientes motivos:
|
Vuelve al seguimiento manual del estado en tu app. |