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 a navigare, periodicamente lungo il percorso (ogni 60 secondi per impostazione predefinita) e quando il conducente arriva a destinazione. Ogni messaggio JSON contiene dati sul percorso pertinenti, tra cui le coordinate del conducente allineate alla strada, la distanza percorsa e l'orario di arrivo stimato (ETA). Poiché questi aggiornamenti riflettono il percorso attivo in tempo reale dell'autista, potrebbero differire dai percorsi precalcolati dal backend (vedi le domande frequenti).
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 |
Il conducente 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, probabilmente si è verificato un errore di autenticazione. Le cause comuni includono parametri API con errori ortografici o un token di viaggio scaduto. Controlla l'ora 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 del viaggio, il backend riceve la polilinea del percorso rimanente 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à dell'itinerario: confronta la geometria dell'itinerario rimanente con gli itinerari di spedizione previsti per valutare l'aderenza del conducente (vedi le domande frequenti per informazioni dettagliate sul motivo per cui gli itinerari in tempo reale e quelli precalcolati possono differire).
Navigation Connect restituisce i dettagli del percorso rimanente 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 formati e le strutture del payload
di 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 saperne di più, 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 notevolmente 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 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 |
Il conducente ha chiuso manualmente la navigazione passo passo prima di arrivare
a destinazione. Poiché Google Maps o Waze non riportano automaticamente i conducenti alla tua app quando escono anticipatamente da una sessione, il conducente deve toccare manualmente il pulsante di ritorno. |
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. |