Navigare su percorsi per veicoli di grandi dimensioni

A chi è rivolta questa guida: leggi questa guida se sei uno sviluppatore mobile responsabile della creazione dell'esperienza di navigazione passo passo per i conducenti di camion, autobus o altri veicoli commerciali di grandi dimensioni.

Argomenti trattati in questa guida: questa guida spiega come utilizzare un percorso specifico per i camion generato dall'API Routes o dall'API Route Optimization per una sessione di navigazione passo passo con l'SDK di navigazione per Android.

Obiettivi didattici

Imparerai a eseguire le seguenti attività:

  • Utilizza un routeToken per collegare la pianificazione dei percorsi di backend con l'esperienza di navigazione in-app.
  • Configura l'SDK Navigation per utilizzare un percorso per camion pianificato in precedenza.
  • Scopri come vengono visualizzate le limitazioni specifiche per i camion per il conducente nell'interfaccia utente di navigazione.

Prerequisiti

Prima di iniziare, assicurati di soddisfare i seguenti requisiti:

1. Richiedi l'accesso per il tuo progetto

Il routing per veicoli di grandi dimensioni è disponibile per un gruppo limitato di clienti. Per esprimere il tuo interesse e richiedere l'accesso per il tuo progetto Google Cloud, compila il modulo di contatto. Un rappresentante di Google ti contatterà per i passaggi successivi.

Dopo che Google ha concesso l'accesso, assicurati che il tuo progetto Google Cloud sia predisposto per il routing di veicoli di grandi dimensioni.

Se la tua organizzazione utilizza progetti Google Cloud separati per le API di routing di backend e l'SDK di navigazione per dispositivi mobili, contatta Google per eseguire il provisioning di ogni progetto.

2. Configura la generazione di route di backend e ottieni un token di route

Prima di avviare la navigazione sul dispositivo, il server di backend deve generare un percorso per camion e ottenere un routeToken utilizzando una delle seguenti API:

La richiesta di backend deve specificare travelMode: TRUCK insieme agli attributi fisici del veicolo (altezza, larghezza, lunghezza, peso, numero di assi e carico di materiali pericolosi). L'API di routing restituisce un routeToken nella risposta, che il tuo server di backend passa alla tua app mobile.

3. Soddisfare i requisiti minimi di sistema e dell'SDK

La tua app deve utilizzare la versione minima richiesta dell'SDK Navigation, ovvero 5.2.0 o versioni successive.

Inoltre, il progetto deve soddisfare i requisiti di configurazione dell'SDK Navigation standard.

Limitazioni e linee guida operative

Prima di iniziare, tieni presente le seguenti limitazioni e linee guida operative:

  • Disponibilità geografica: il routing per veicoli di grandi dimensioni è disponibile nei 48 Stati Uniti contigui (disponibilità generale) e in Giappone (sperimentale). Non è disponibile in Alaska, alle Hawaii o nei territori degli Stati Uniti.
  • Avvisi e sicurezza per i conducenti: i conducenti non devono fare affidamento esclusivamente sui percorsi restituiti dall'SDK di navigazione per garantire la sicurezza o la legalità. I percorsi potrebbero non essere adatti al veicolo in tutte le condizioni stradali e seguirli potrebbe esporre i conducenti a pericoli come altezze ridotte o strade con limiti di peso. I conducenti devono sempre prestare attenzione e rispettare i segnali stradali e le normative locali.
  • Percorsi best-effort: quando l'API Routes non riesce a trovare un percorso che rispetti completamente le limitazioni del veicolo, restituisce un percorso "best-effort" che potrebbe comunque attraversare segmenti con limitazioni. Ad esempio, l'API Routes imposta il flag routeRestrictionsPartiallyIgnored nella risposta. Durante la navigazione di questi percorsi, l'SDK Navigation mostra i callout del percorso per evidenziare le limitazioni pertinenti. Pianifica i percorsi con attenzione in questi casi e non utilizzare un percorso segnalato come Single Source Of Truth per la pianificazione o la navigazione.
  • Funzionalità non supportate: il calcolo del percorso per veicoli di grandi dimensioni non supporta le seguenti funzionalità:
    • Prezzi dei pedaggi per i camion
    • Limiti di velocità specifici per camion o veicoli pesanti
    • Percorso per materiali pericolosi radioattivi
  • Limiti di utilizzo: le richieste effettuate all'SDK Navigation seguono i limiti di utilizzo e di quota standard. Per saperne di più, consulta Utilizzo e fatturazione.

Visualizza l'interfaccia utente specifica per i camion (callout del percorso)

L'SDK Navigation visualizza automaticamente sulla mappa avvisi visivi, chiamati callout del percorso, per avvisare i conducenti delle imminenti limitazioni per i camion. I callout vengono visualizzati per le limitazioni che si verificano lungo il percorso pianificato, ma non su altre strade vicine.

Navigation SDK include callout per le seguenti limitazioni:

Limitazione Icona e testo del callout Condizioni per la visualizzazione
Altezza Un'icona gialla di limitazione di altezza
Giallo = avviso, il tuo veicolo è vicino all'altezza massima consentita
Icona rossa di limitazione dell'altezza
Rosso = il tuo veicolo supera l'altezza massima consentita 		Quando l'altezza del veicolo è vicina al limite, viene visualizzato un callout giallo.
Una mappa che mostra un avviso di limitazione dell'altezza
Viene visualizzato un callout rosso se il percorso non è conforme e viola un limite di altezza.
Una mappa che mostra una violazione della limitazione di altezza
Peso Un'icona di limitazione di peso Viene visualizzato un callout rosso quando il peso del veicolo supera il limite della strada.
Una mappa che mostra un'icona di limitazione del peso
Camion vietati Icona di divieto di transito per i camion Viene visualizzato un callout rosso quando si viaggia su un segmento stradale con una limitazione per i camion commerciali.
Una mappa che mostra un'icona di divieto di transito per i camion
Merci pericolose Icona di merci pericolose Viene visualizzato un callout rosso quando il carico di materiali pericolosi del veicolo è vietato su un segmento stradale.
Una mappa che mostra un'icona di merci pericolose

Come funzionano i token di route

Un routeToken è uno snapshot criptato di un percorso creato dal backend di routing di Google. Incapsula la geometria del percorso pianificato, nonché le dimensioni fisiche e il profilo delle limitazioni del veicolo.

Il flusso di lavoro segue questi passaggi:

  1. Richiesta del percorso: il tuo server di backend richiede un percorso per camion all'API Routes (o all'API Route Optimization).
  2. Ricezione del token: l'API Routes calcola il percorso conforme e restituisce un routeToken al tuo server di backend.
  3. Inoltra il token: il tuo server di backend passa il routeToken e le coordinate di destinazione alla tua app mobile.
  4. Passaggio all'SDK: l'app mobile passa il routeToken all'SDK Navigation.
  5. Avvia le indicazioni: l'SDK di navigazione gestisce tutti gli aspetti dell'esperienza passo passo, tra cui il rendering dei callout del percorso e la gestione del cambio percorso dinamico in base alle limitazioni del veicolo.

Ricalcoli e cambi di percorso dinamici

Durante la navigazione attiva, le condizioni del traffico, le chiusure stradali o le svolte mancate potrebbero far deviare il veicolo dal percorso pianificato.

Quando viene cambiato il percorso:

  • L'SDK Navigation ricalcola automaticamente il percorso verso la destinazione.
  • L'SDK conserva gli attributi e le dimensioni del veicolo codificati nel routeToken originale.
  • Il nuovo percorso ricalcolato evita i sottopassaggi bassi, i ponti con limiti di peso e le strade vietate ai camion commerciali.

Implementazione: avvia un percorso specifico per i camion

Segui questi passaggi per inizializzare e avviare la navigazione passo passo con un token di percorso per veicoli di grandi dimensioni.

Passaggio 1: ottieni il token del percorso dal backend

La tua app mobile riceve la stringa routeToken insieme alle coordinate della destinazione dal tuo server di backend. Per saperne di più sulla generazione di questo token sul tuo server, consulta Genera percorsi ed ETA per veicoli di grandi dimensioni nella documentazione dell'API Routes.

Il seguente codice è un esempio di token di percorso:

{
  "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}

Passaggio 2: imposta le destinazioni con il token di percorso

Passa il routeToken a navigator.setDestinationsWithToken. L'SDK Navigation recupera le destinazioni dal token di percorso, insieme al profilo di routing TRUCK che lo indirizza ad applicare i vincoli per i veicoli di grandi dimensioni. Non è necessario passare waypoint o impostare una modalità di viaggio.

Imposta le opzioni dei waypoint nella richiesta dell'API Routes che crea il token del percorso. L'SDK Navigation li recupera dal token, insieme alle tue destinazioni. Per i veicoli di grandi dimensioni, valuta le seguenti opzioni:

  • Routing sul lato della strada: i veicoli commerciali di grandi dimensioni non possono fare facilmente inversioni a U su strade strette. Per assicurarti che il camion si avvicini alla destinazione sul lato corretto della strada, imposta sideOfRoad su true nel waypoint di destinazione.
  • Soste del veicolo: per guidare il camion in un luogo appropriato per la sosta o lo scarico, imposta vehicleStopover su true nel waypoint di destinazione.
  • Punti di navigazione: se la tua destinazione ha un ingresso per le merci o una banchina di carico designati, specificali utilizzando un token del punto di navigazione.

Passaggio 3: gestisci lo stato del percorso e avvia le indicazioni stradali

Quando l'SDK di navigazione termina il calcolo del percorso, passa un RouteDescription al callback. Quando getRouteStatus restituisce Navigator.RouteStatus.OK, chiama navigator.startGuidance per avviare la navigazione passo passo attiva.

Per verificare che l'SDK Navigation abbia applicato il token di route, consulta Verifica se l'SDK Navigation ha applicato il token di route.

Codice di esempio

Passa il token del percorso a navigator.setDestinationsWithToken, quindi avvia le indicazioni stradali quando lo stato del percorso è OK.

// Obtain the routeToken string from your backend
String routeToken = "route token returned by Routes API";

navigator.setDestinationsWithToken(
    routeToken,
    routeDescription -> {
      if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
        navigator.startGuidance();
      }
    });

Display dei veicoli

Puoi proiettare la sessione di navigazione per veicoli di grandi dimensioni sugli schermi integrati nel cruscotto utilizzando Navigazione per Android Auto.

Passaggi successivi

  • Modifica l'interfaccia utente di navigazione: personalizza i controlli dell'interfaccia utente e gli elementi visivi integrati, come la bussola, il pulsante di ricentramento e la prospettiva della fotocamera.
  • Ascolta gli eventi di navigazione: gestisci gli aggiornamenti di navigazione e gli eventi del ciclo di vita, come l'avanzamento del percorso, le modifiche all'orario di arrivo stimato e i cambi di percorso.