Gestire i dati sul percorso

Quando recuperi i dati della corsa, il tuo backend riceve payload JSON che descrivono in dettaglio l'avanzamento della corsa del conducente. Analizza questi payload per monitorare la corsa, aggiornare i sistemi di invio e interpretare gli stati correnti della corsa per determinare il passaggio successivo per il conducente man mano che procede o quando una corsa si conclude.

Leggi il payload dei dati

Google Maps o Waze invia i payload dei dati sui viaggi ai server di Navigation Connect quando il conducente avvia la navigazione, periodicamente lungo il percorso (ogni 60 secondi per impostazione predefinita) e quando il conducente arriva a destinazione. Ogni messaggio JSON contiene dati di viaggio pertinenti, tra cui le coordinate del conducente agganciate alla strada, la distanza percorsa e l'orario di arrivo stimato (ETA). Poiché questi aggiornamenti riflettono il percorso attivo in tempo reale del conducente, potrebbero differire dai percorsi precalcolati dal tuo backend (consulta le domande frequenti).

Il seguente esempio di codice mostra un payload di dati di un percorso quando un conducente avvia la navigazione per un percorso 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
  }
}

Monitora gli stati delle corse attive

Per confermare l'avvio riuscito e monitorare l'avanzamento, valuta il campo state in ogni payload.

Stato Descrizione
NEW La corsa è stata creata, ma il conducente non ha ancora avviato la navigazione.
ENROUTE Il conducente sta navigando attivamente verso la destinazione. Utilizza questo stato per confermare che la corsa è stata autenticata e avviata correttamente.

Gestisci le tappe aggiunte

I conducenti possono aggiungere tappe 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 il conducente verso la destinazione originale. Metriche come l'orario di arrivo stimato, la distanza e la durata aumentano per includere le tappe aggiunte.

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 percorso.
  • Waze: i conducenti 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 al percorso corrente.

Non è necessario modificare gli input di backend per supportare questa funzionalità.

Risolvi i problemi di autenticazione e avvio

Se non ricevi uno stato ENROUTE, è probabile che si sia verificato un errore di autenticazione. Le cause comuni includono parametri API scritti in modo errato o un token di percorso scaduto. Controlla la data e 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.

Gestisci i dati rimanenti sul percorso

Se hai attivato i report sul percorso rimanente durante la creazione del viaggio, il tuo backend riceve la polilinea del percorso rimanente e le condizioni del traffico in tempo reale dalla posizione attuale del conducente alla destinazione finale. I conducenti devono avere Waze versione 5.20.0.2 o successive su Android, 5.20.0.1 o successive su iOS oppure Google Maps per Android versione 26.27 o successive.

Puoi importare ed elaborare questi dati per potenziare diverse funzionalità nelle tue applicazioni, tra cui i seguenti esempi:

  • 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 percorso del conducente.
  • Migliora l'accuratezza 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 spedizione previsti per valutare l'aderenza del conducente (consulta le domande frequenti per i dettagli sul motivo per cui i percorsi in tempo reale e quelli precalcolati potrebbero 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 il payload formatta e struttura questi dati dipende dal metodo di recupero utilizzato.

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 Personalizza i formati delle polilinee.

Per tutti i formati di polilinee, Navigation Connect restituisce il traffico come un 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:

Aggiornamenti di Google Cloud Pub/Sub

Quando recuperi i dati del percorso con Pub/Sub, gli aggiornamenti restituiscono sempre i dati del percorso rimanente in un GeoJSON FeatureCollection unificato nel campo execution.remainingRoute.

Questo formato combina la geometria della polilinea direttamente 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"
      }
    }
  ]
}
    

Ottimizza le dimensioni del payload

Poiché gli array di coordinate sono di grandi dimensioni, l'inclusione dei dati del percorso rimanente 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 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.

Gestisci le deviazioni dal percorso (solo Waze)

I conducenti devono avere Waze versione 5.22 o successive.

Se hai attivato i report sulle deviazioni dal percorso durante la creazione del viaggio, quando un conducente esce dal percorso, l'API restituisce i metadati della deviazione dal percorso. Puoi accedere a questi dati nei seguenti modi:

  • On demand: chiama il metodo GetTrip. Il server mantiene l'ultimo stato di deviazione noto.
  • In tempo reale: iscriviti a Google Cloud Pub/Sub. Il servizio pubblica gli aggiornamenti sulle deviazioni utilizzando l'evento updated_trip esistente entro 5 secondi dal rilevamento.

Leggi il payload della deviazione

L'oggetto last_route_deviation fornisce i seguenti metadati per aiutarti ad analizzare l'evento.

Campo Tipo Descrizione
location LatLng Le coordinate di latitudine e longitudine in cui il dispositivo client ha registrato la deviazione.
source TriggerSource Il motivo della deviazione. Utilizza questa opzione per determinare se il conducente ha eseguito un'azione imprevista o ha seguito le indicazioni del sistema:
  • DRIVER_INITIATED_REROUTE: il conducente ha effettuato una scelta attiva (ad esempio, ha svoltato nella direzione sbagliata o ha selezionato manualmente un nuovo percorso).
  • SYSTEM_INITIATED_REROUTE: l'app di navigazione ha calcolato un nuovo percorso (ad esempio, a causa di condizioni del traffico mutevoli o chiusure stradali).
client_timestamp Timestamp L'ora in cui il dispositivo client ha rilevato la deviazione.
server_timestamp Timestamp L'ora in cui il server ha elaborato l'aggiornamento della deviazione.

Gestisci gli stati di fine corsa

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 Il conducente ha raggiunto la destinazione. Dai un'occhiata al remainingDistanceMeters. Se il conducente ha parcheggiato nelle vicinanze, ma non alle coordinate esatte, valuta la possibilità di fornire indicazioni a piedi nella tua app.
SUSPENDED Il conducente è uscito manualmente dalla navigazione passo passo prima di arrivare a destinazione.
Poiché Google Maps o Waze non riportano automaticamente i conducenti alla tua app quando escono da una sessione in anticipo, il conducente deve toccare manualmente il pulsante di ritorno.
Per aiutare i conducenti a completare il viaggio, confronta execution.location con la destinazione. Se rimane della distanza da percorrere, fornisci un pulsante o un link per riprendere il percorso o passare alla modalità a piedi.
FAILED Un errore tecnico ha interrotto la connessione. Questo accade se l'app non riesce a calcolare un percorso o se viene visualizzato un avviso di sicurezza. Il conducente potrebbe continuare a navigare, ma non riceverai aggiornamenti. Utilizza il monitoraggio manuale dello stato nella tua app.
CLIENT_ERROR Questo stato viene visualizzato per uno dei seguenti motivi:
  • Il conducente revoca il consenso.
  • Il conducente utilizza una piattaforma non supportata, ad esempio Android Auto o Apple CarPlay.
  • La tua app riutilizza un token di percorso per percorsi separati. Ad esempio, Navigation Connect rifiuta le richieste che modificano la destinazione di una corsa o aggiornano una corsa completata.
  • Il conducente si trova negli Stati Uniti in un qualsiasi momento durante la corsa, ma la tua app non ha la condivisione dei dati negli Stati Uniti attivata quando hai verificato l'app durante la configurazione.
Utilizza il monitoraggio manuale dello stato nella tua app.