Quando recuperi i dati sul percorso, il backend riceve payload JSON che descrivono in dettaglio l'avanzamento del viaggio del conducente. Analizza questi payload per monitorare la corsa, aggiornare i sistemi di assegnazione e interpretare gli stati attuali della corsa per determinare il passaggio successivo per il conducente man mano che procede o al termine di una corsa.
Leggi il payload
Google Maps o Waze inviano i payload dei dati sul percorso ai server di Navigation Connect quando il conducente inizia la navigazione, periodicamente lungo il percorso (ogni 60 secondi per impostazione predefinita) e quando il conducente arriva a destinazione. Ogni messaggio JSON contiene i dati sul percorso pertinenti, incluse le coordinate del conducente allineate alla strada, la distanza percorsa e l'orario di arrivo stimato (ETA).
Il seguente esempio di codice mostra un payload di dati sul percorso per quando un autista inizia la navigazione per un viaggio da King's Cross a 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
}
}
Monitorare gli stati dei viaggi attivi
Per confermare l'avvio e monitorare l'avanzamento, valuta il campo di stato in ogni payload.
| Stato | Descrizione |
|---|---|
NEW |
Il viaggio è stato creato, ma il conducente non ha ancora iniziato la navigazione. |
ENROUTE |
L'autista sta navigando attivamente verso la destinazione. Utilizza questo stato per confermare che il viaggio è stato autenticato e avviato correttamente. |
Gestire le tappe aggiunte
I conducenti possono aggiungere fermate al percorso durante la navigazione. In questo caso,
Navigation Connect imposta il campo execution.stopAddedInRoute su true nel
payload dei dati JSON. L'API Navigation Connect
continua a monitorare l'autista verso la destinazione originale. Metriche come
l'orario di arrivo stimato (ATE), la distanza e la durata aumentano
per includere le tappe aggiuntive.
Il comportamento per l'aggiunta di fermate dipende dall'app di navigazione e corrisponde alla sua funzionalità standard:
- Google Maps:i conducenti possono aggiungere più fermate al loro itinerario.
- Waze:gli autisti possono aggiungere una sola fermata. Se un conducente tenta di aggiungere un'altra fermata, Waze gli chiede di avviare una nuova sessione di navigazione anziché aggiungere la fermata all'itinerario corrente.
Non è necessario modificare gli input di backend per supportare questa funzionalità.
Risolvere i problemi di autenticazione e avvio
Se non ricevi lo stato ENROUTE, è probabile che si sia verificato un errore di autenticazione. Le cause comuni includono parametri API errati o un token di viaggio scaduto. Controlla la data di scadenza del token nella risposta CreateTrip iniziale.
Se lo stato non cambia da NEW a ENROUTE, il dispositivo del conducente potrebbe
impedire l'autenticazione. Navigation Connect non invia messaggi di errore
per questi casi. Verifica quanto segue:
- Il conducente ha installato Waze versione 5.15.5 o successive oppure Google Maps versione 26.14 o successive.
- Il conducente non utilizza Android Auto o Apple CarPlay.
- Il conducente ha una connessione a internet attiva.
Gestire i dati rimanenti del percorso (solo Waze)
Se hai attivato la segnalazione del percorso rimanente durante la creazione della corsa, il backend riceve la polilinea del percorso attivo e le condizioni del traffico in tempo reale dalla posizione attuale del conducente alla destinazione finale.
Puoi importare ed elaborare questi dati per attivare diverse funzionalità nelle tue applicazioni, tra cui i seguenti esempi:
- Migliora le mappe di monitoraggio in tempo reale: esegui il rendering della polilinea del percorso rimanente su una mappa web o mobile rivolta ai clienti per fornire visibilità sul viaggio del conducente.
- Migliora la precisione dell'orario di arrivo stimato: combina la polilinea agganciata alla strada e le velocità degli intervalli di traffico per migliorare la logistica interna o le previsioni di arrivo delle consegne.
- Analizza la conformità del percorso: confronta la geometria del percorso rimanente con i percorsi di assegnazione previsti per valutare l'aderenza del conducente.
Navigation Connect restituisce i dettagli rimanenti dell'itinerario nel campo execution.remainingRoute, indipendentemente dal fatto che tu invii una richiesta GetTrip o riceva aggiornamenti basati su eventi utilizzando Google Cloud Pub/Sub. Tuttavia, il modo in cui i payload formattano e strutturano questi dati dipende dal metodo di recupero che utilizzi.
Metodo GetTrip
Quando chiami il metodo GetTrip, il formato della risposta per la polilinea dipende dal parametro routePolylineFormat specificato nella richiesta. Per ulteriori informazioni, consulta Personalizzare i formati delle polilinee.
Per tutti i formati polilinea, Navigation Connect restituisce il traffico come elenco separato di oggetti SpeedReadingInterval nel campo execution.remainingRoute.trafficInformation. Questi
oggetti mappano le categorie di traffico agli indici delle polilinee utilizzando i seguenti
valori:
startPolylinePointIndex: L'indice iniziale dell'intervallo di traffico sulla polilinea.endPolylinePointIndex: l'indice finale dell'intervallo di traffico.speed: la categoria di traffico per questo segmento:NORMAL,SLOWoTRAFFIC_JAM.
Aggiornamenti di Google Cloud Pub/Sub
Quando recuperi i dati di viaggio con Pub/Sub,
gli aggiornamenti restituiscono sempre i dati sul percorso rimanenti in un GeoJSON unificato
FeatureCollection nel campo execution.remainingRoute.
Questo formato combina direttamente la geometria della polilinea con le velocità del traffico, eliminando la necessità di mappare manualmente gli indici.
Visualizza un payload Pub/Sub di esempio
Il seguente esempio di codice mostra la struttura GeoJSON restituita nel campo execution.remainingRoute all'interno dell'oggetto updatedTrip di un messaggio 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" } } ] }
Ottimizzare le dimensioni del payload
Poiché gli array di coordinate sono grandi, l'inclusione dei dati del percorso rimanenti nei messaggi Pub/Sub può aumentare significativamente le dimensioni del payload (fino a 13-14 KB per messaggio). Se ricevi aggiornamenti ad alta frequenza, questo volume può aumentare il carico di elaborazione del backend e i costi di utilizzo.
Per ottimizzare lo stream, utilizza il parametro pubsubFieldMask nell'oggetto
TripConfig durante la creazione del viaggio per escludere i campi pesanti. Per
maggiori dettagli, vedi Configurazioni facoltative.
Gestire gli stati di fine viaggio
Quando un conducente raggiunge la destinazione o interrompe la navigazione, il payload restituisce uno dei seguenti stati finali. Utilizza questi stati per attivare i passaggi successivi appropriati nella tua app.
| Stato | Descrizione | Azione consigliata |
|---|---|---|
ARRIVED |
L'autista ha raggiunto la destinazione. | Controlla remainingDistanceMeters. Se l'autista ha parcheggiato
nelle vicinanze, ma non alle coordinate esatte, valuta la possibilità di fornire indicazioni
a piedi nella tua app. |
SUSPENDED |
L'autista ha interrotto manualmente la navigazione passo passo prima di arrivare
a destinazione. Poiché Google Maps o Waze non riportano automaticamente gli autisti nella tua app quando interrompono una sessione in anticipo, l'autista deve toccare manualmente il pulsante Indietro. |
Per aiutare i conducenti a completare il viaggio, confronta
execution.location con la destinazione. Se la distanza
rimane, fornisci un pulsante o un link per riprendere il viaggio o passare alla
modalità a piedi. |
FAILED |
Un errore tecnico ha interrotto la connessione. Ciò si verifica se l'app non riesce a calcolare un percorso o viene visualizzato un avviso di sicurezza. Il conducente potrebbe continuare a navigare, ma non riceverai aggiornamenti. | Ripiega sul monitoraggio manuale dello stato nell'app. |
CLIENT_ERROR |
Questo stato viene visualizzato per uno dei seguenti motivi:
|
Ripiega sul monitoraggio manuale dello stato nell'app. |