Navigare su percorsi per veicoli di grandi dimensioni

Nota:il routing per veicoli di grandi dimensioni è disponibile per un numero limitato di clienti. Contattaci per esprimere il tuo interesse.

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 iOS.

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. Richiedere l'accesso per il progetto

Il routing per veicoli di grandi dimensioni è disponibile per un numero limitato di clienti. Per esprimere il tuo interesse e richiedere l'accesso al 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. Configurare la generazione del percorso di backend e ottenere 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:

• API Routes: consigliata per il calcolo di singoli percorsi per camion tra origini e destinazioni. Per le istruzioni di configurazione, vedi Generare percorsi e ETA per veicoli di grandi dimensioni.
• API Route Optimization: consigliata per l'ottimizzazione dei percorsi con più fermate per una flotta. Per ulteriori informazioni, consulta la guida al routing per veicoli di grandi dimensioni dell'API Route Optimization.

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. Soddisfare i requisiti minimi di SDK e di sistema

La tua app deve utilizzare la versione minima richiesta dell'SDK Navigation 5.4.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 rimanere sempre 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	Giallo = avviso, il veicolo è vicino all'altezza massima consentita Rosso = il veicolo supera l'altezza massima consentita	Viene visualizzato un callout giallo quando l'altezza del veicolo è vicina alla limitazione. Viene visualizzato un callout rosso se il percorso non è conforme e viola una limitazione di altezza.
Peso		Viene visualizzato un callout rosso quando il peso del veicolo supera il limite della strada.
Camion vietati		Viene visualizzato un call0ut rosso quando si viaggia su un segmento stradale con una limitazione per i camion commerciali.
Merci pericolose		Viene visualizzato un callout rosso quando il carico di merci pericolose del veicolo è vietato su un segmento stradale.

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 prevede i seguenti passaggi:

1. Richiedere il percorso: il server di backend richiede un percorso per camion all' API Routes (o all'API Route Optimization).
2. Ricevere il token: l'API di routing calcola il percorso conforme e restituisce un routeToken al server di backend.
3. Inoltrare il token: il server di backend passa il routeToken e le coordinate della destinazione alla tua app mobile.
4. Passare all'SDK: l'app mobile passa il routeToken all' SDK Navigation.
5. Avviare 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: ottenere il token di percorso dal backend

L'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: passare il token al navigatore

Passa il routeToken e i waypoint della destinazione al metodo mapView.navigator setDestinations.

Quando configuri i waypoint e passi il token di percorso, 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 del 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, imposta preferSameSideOfRoad = true sui waypoint.
• Fermate del veicolo: per guidare il camion in una posizione appropriata per la fermata o lo scarico, imposta vehicleStopover = 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 3: gestire lo stato del percorso e avviare la guida

Valuta il GMSRouteStatus restituito nel callback setDestinations. Quando lo stato è .OK (GMSRouteStatusOK), imposta isGuidanceActive = true (guidanceActive = YES) per avviare la guida passo passo attiva.

Codice di esempio

Passa il token di percorso all'SDK Navigation utilizzando il metodo mapView.navigator setDestinations, specificando gli stessi waypoint della destinazione utilizzati durante la creazione del token di percorso:

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

mapView.navigator?.setDestinations([destination], routeToken: routeToken, callback: {...})

Display in-vehicle

Puoi visualizzare la sessione di navigazione per veicoli di grandi dimensioni sugli schermi del cruscotto utilizzando Navigation for CarPlay.

Passaggi successivi

• Modificare 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.
• Rimanere in ascolto per 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.