Navigare su percorsi per veicoli di grandi dimensioni

A chi si rivolge questa guida:leggi questa guida se sei uno sviluppatore di app 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 camion generato dall'API Routes o dall'API Route Optimization per alimentare una sessione di navigazione passo passo con l'SDK Navigation per Android.

Obiettivi didattici

Imparerai a svolgere le seguenti attività:

  • Utilizzare un routeToken per collegare la pianificazione del percorso di backend con l'esperienza di navigazione in-app.
  • Configurare l'SDK Navigation per utilizzare un percorso per camion pianificato in anticipo.
  • Comprendere come le limitazioni specifiche per i camion vengono visualizzate al conducente nell'UI 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 numero 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 illustrarti i passaggi successivi.

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

Se la tua organizzazione utilizza progetti Google Cloud separati per le API di routing di backend e l'SDK Navigation mobile, contatta Google per configurare ogni progetto.

2. Configura la generazione del percorso di backend e ottieni un token di percorso

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 merci pericolose). L'API di routing restituisce un routeToken nella risposta, che il server di backend passa alla tua app mobile.

3. Soddisfa i requisiti minimi di SDK e di sistema

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

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

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 contigui degli Stati Uniti (disponibilità generale) e Giappone (sperimentale). Non è disponibile in Alaska, 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 Navigation per essere sicuri o legali. I percorsi potrebbero non essere adatti al veicolo in tutte le condizioni stradali e seguirli potrebbe esporre i conducenti a pericoli come spazi liberi ridotti o strade con limitazioni di peso. I conducenti devono sempre rimanere vigili e rispettare i segnali stradali e le normative locali.
  • Percorsi con il massimo impegno: quando l'API di routing non riesce a trovare un percorso che rispetti completamente le limitazioni del veicolo, restituisce un percorso "con il massimo impegno" che potrebbe comunque attraversare segmenti con limitazioni. Ad esempio, l'API Routes imposta il flag routeRestrictionsPartiallyIgnored nella risposta. Quando si naviga su questi percorsi, l'SDK Navigation visualizza i callout del percorso per evidenziare le limitazioni pertinenti. In questi casi, pianifica attentamente i percorsi e non utilizzare un percorso contrassegnato come unica fonte attendibile per la pianificazione o la navigazione.
  • Funzionalità non supportate: il routing per veicoli di grandi dimensioni non supporta le seguenti funzionalità:
    • Prezzi dei pedaggi per camion
    • Limiti di velocità specifici per camion o veicoli pesanti
    • Routing per materiali pericolosi radioattivi
  • Limiti di utilizzo: le richieste effettuate all'SDK Navigation seguono i limiti di utilizzo e di quota standard. Per ulteriori informazioni, vedi Utilizzo e fatturazione.

Visualizzare l'UI specifica per i camion (callout del percorso)

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

L'SDK Navigation include callout per le seguenti limitazioni:

Limitazione Icona e testo del callout Condizioni di visualizzazione
Altezza Un'icona gialla di limitazione dell'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 		Viene visualizzato un callout giallo quando l'altezza del veicolo è vicina alla limitazione.
Una mappa che mostra un avviso di limitazione di altezza
Viene visualizzato un callout rosso se il percorso non è conforme e viola una limitazione di altezza.
Una mappa che mostra una violazione del limite di altezza
Peso Un'icona di limitazione di peso Viene visualizzato un callout rosso quando il peso del veicolo supera il limite della strada.
Mappa che mostra un'icona di limitazione di peso
Camion vietati Icona di divieto per i camion Viene visualizzato un call0ut rosso quando si viaggia su un segmento stradale con una limitazione per i camion commerciali.
Una mappa che mostra un'icona di divieto per i camion
Merci pericolose Un'icona di merci pericolose Viene visualizzato un callout rosso quando il carico di merci pericolose del veicolo è vietato su un segmento stradale.
Una mappa che mostra un'icona di merci pericolose

Come funzionano i token di percorso

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 di limitazione del veicolo.

Il flusso di lavoro segue questi passaggi:

  1. Richiedi percorso: il server di backend richiede un percorso per camion all' API Routes (o all'API Route Optimization).
  2. Ricevi token: l'API di routing calcola il percorso conforme e restituisce un routeToken al server di backend.
  3. Inoltra token: il server di backend passa il routeToken e le coordinate della destinazione alla tua app mobile.
  4. Passa all'SDK: l'app mobile passa il routeToken all' SDK Navigation.
  5. Avvia la guida: l'SDK Navigation gestisce tutti gli aspetti dell' esperienza passo passo, inclusa la visualizzazione dei callout del percorso e la gestione del ricalcolo dinamico del percorso in base alle limitazioni del veicolo.

Ricalcoli e ricalcoli dinamici del percorso

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

Quando si verifica un ricalcolo del 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 percorso appena ricalcolato evita spazi liberi ridotti, ponti con limitazioni di peso e strade vietate ai camion commerciali.

Implementazione: avviare un viaggio specifico per 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 di percorso dal backend

La tua app mobile riceve la stringa routeToken insieme alle coordinate della destinazione dal server di backend. Per informazioni dettagliate sulla generazione di questo token sul server, vedi Generare percorsi e 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: configura CustomRoutesOptions

Passa il token di percorso a un'istanza CustomRoutesOptions utilizzando CustomRoutesOptions.builder:

  • Passa il token utilizzando setRouteToken(routeToken).
  • Imposta la modalità di viaggio utilizzando setTravelMode(CustomRoutesOptions.TravelMode.DRIVING).

Passaggio 3: definisci i waypoint e imposta le destinazioni

Passa i waypoint di destinazione e CustomRoutesOptions a navigator.setDestinations.

Quando configuri i waypoint e passi le opzioni di percorso personalizzate, tieni presente le seguenti considerazioni:

  • Requisito di corrispondenza della destinazione: le coordinate della destinazione passate a setDestinations devono corrispondere alle coordinate della destinazione utilizzate durante la generazione di routeToken. Se specifichi una destinazione diversa, si verifica un errore.
  • Routing sul lato della strada: i veicoli commerciali di grandi dimensioni non possono effettuare facilmente inversioni a U su strade strette. Per assicurarti che il camion si avvicini alla destinazione sul lato corretto della strada, chiama setPreferSameSideOfRoad(true) sui waypoint.
  • Fermate del veicolo: per guidare il camion in una posizione appropriata per la fermata o lo scarico, chiama setVehicleStopover(true) sui waypoint.
  • Punti di navigazione: se la tua destinazione ha un ingresso merci o una banchina di carico designati, specificali utilizzando un token di punto di navigazione.

Passaggio 4: gestisci lo stato del percorso e avvia la guida

Registra un OnResultListener su ListenableResultFuture<Navigator.RouteStatus>. Quando lo stato del percorso è OK, chiama navigator.startGuidance per avviare la navigazione passo passo attiva.

Codice di esempio

Utilizza CustomRoutesOptions.builder per impostare il token e poi passalo a navigator.setDestinations.

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

val customRoutesOptions = CustomRoutesOptions.builder()
    .setRouteToken(routeToken)
    .setTravelMode(TravelMode.DRIVING)
    .build()

// Specify the same destination used to create the route token
ArrayList <Waypoint> destinations = Lists.newArrayList();
val destination = Waypoint.builder()
    .setLatLng(10.0, 20.0)
    .setTitle("title")
    .setVehicleStopover(true)
    .build()
destinations.add(destination);

navigator.setDestinations(destinations, customRoutesOptions)

Display in-vehicle

Puoi proiettare la sessione di navigazione per veicoli di grandi dimensioni sugli schermi del cruscotto utilizzando Navigation per Android Auto.

Passaggi successivi

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