Pianificare un percorso

A volte, potresti voler pianificare il percorso che la tua app fornisce agli utenti. L'utilizzo di un token di percorso dell'API Routes o dell'API Route Optimization può aiutarti a specificare due cose per il percorso pianificato:

• Una polilinea per il percorso

• I tuoi obiettivi di percorso

Ecco alcuni esempi di obiettivi di routing che potresti avere:

• Ridurre al minimo i tempi di consegna: un'attività di consegna di cibo potrebbe voler ridurre al minimo i tempi di consegna.

• Ridurre al minimo il tempo di percorrenza o il consumo di carburante: un'azienda di logistica potrebbe voler migliorare l'efficienza dei propri conducenti e ridurre i costi del carburante.

• Ridurre al minimo il tempo per raggiungere la destinazione: un'operazione di invio di servizi potrebbe voler ridurre al minimo il tempo necessario per far arrivare gli operatori a una richiesta di intervento.

• Ridurre i costi e migliorare la sicurezza: un'attività di ride sharing potrebbe voler trovare un percorso che costi meno per i passeggeri ed eviti determinate aree per motivi di sicurezza.

Importante: il percorso seguito dai conducenti può essere diverso da quello pianificato. Le condizioni del traffico o della strada, l'uscita del veicolo dal percorso pianificato o il passaggio a un percorso più veloce possono modificare il percorso durante il viaggio. Ogni volta che l'SDK di navigazione calcola un nuovo percorso, utilizza le opzioni di routing impostate nel token del percorso, ad esempio per evitare i pedaggi.

Per ulteriori informazioni sulla pianificazione di un percorso utilizzando un token di percorso, consulta Ottieni un token di percorso nell'API Routes e Polilinee di transizione e token di percorso nell'API Route Optimization.

Perché utilizzare un token di percorso per gli obiettivi del percorso

Con un token di percorso dell'API Routes o dell'API Route Optimization, hai un maggiore controllo sul percorso fornito:

• Pianifica un percorso in anticipo per l'utilizzo da parte dell'SDK Navigation.

• Scegli il percorso migliore da utilizzare per l'SDK Navigation. Se richiedi i token di percorso durante la generazione dei percorsi nell'API Routes, ricevi un token di percorso per ogni percorso generato. Puoi quindi scegliere il token per il percorso che vuoi utilizzare quando lo passi all'SDK di navigazione.

• Stima il prezzo in anticipo, incluse le stime per l'orario di arrivo stimato e la distanza. Anche se il costo e il tempo effettivi potrebbero variare, questa stima riduce il divario tra il costo previsto e quello effettivo del percorso.

• Specifica obiettivi di percorso più avanzati, come il percorso ecosostenibile o il percorso più breve.

Suggerimento: un token di percorso è relativo a un'origine e una destinazione specifiche e a un momento particolare. Devi effettuare una nuova richiesta API Routes o API Route Optimization per un nuovo token di percorso.

Come funzionano i token di route

Puoi utilizzare l'API Routes o l'API Route Optimization per pianificare un percorso utilizzando gli obiettivi del percorso. Puoi passare un token di percorso restituito da una di queste API all'SDK Navigation per guidare il modo in cui viene calcolato il percorso del veicolo.

Ecco cosa succede quando richiedi e utilizzi un token di route:

1. L'API Routes o l'API Route Optimization restituisce un token di percorso criptato che include la polilinea del percorso e gli obiettivi del percorso.

2. Passi il token di percorso all'SDK Navigation.

3. L'SDK Navigation avvia la navigazione sul percorso pianificato, anche se è disponibile un percorso più veloce.

4. Durante il percorso, se il traffico o le condizioni stradali cambiano o se il veicolo esce dal percorso pianificato, l'SDK di navigazione calcola un nuovo percorso che segue gli obiettivi e le opzioni di routing impostati nel token di percorso.

Questo processo massimizza la vicinanza del percorso effettivo a quello pianificato.

Perché un percorso pianificato potrebbe non essere seguito esattamente

La navigazione inizia sul percorso pianificato, ma il percorso effettivo può differire da questo in situazioni come le seguenti:

• Il veicolo parte da un punto diverso da quello di partenza pianificato.
• Le condizioni del traffico o della strada cambiano durante il percorso.
• Il veicolo devia dal percorso pianificato.

Queste differenze possono influire sulla distanza, sull'orario di arrivo stimato e su altre qualità importanti del percorso che hai pianificato.

Suggerimento: come best practice, richiedi sempre un nuovo token di percorso ogni volta che imposti la destinazione nell'SDK Navigation e pianifica alcune variazioni per evitare qualsiasi impatto sulla tua attività.

Pianifica un percorso utilizzando un token di percorso

Puoi pianificare un percorso creando un token di percorso e passandolo poi all'SDK Navigation, come descritto nei seguenti passaggi:

Passaggio 1: crea un token di percorso utilizzando l'API Routes o l'API Route Optimization

1. Richiedi un token di route con uno dei seguenti metodi:

   • API Routes: computeRoutes. Per saperne di più sulla richiesta di un token di percorso nell'API Routes, consulta Calcola un percorso e Ottieni un token di percorso.

   • API Route Optimization: optimizeTours o batchOptimizeTours. Per ulteriori informazioni sulla richiesta di un token di percorso nell'API Route Optimization, consulta Polilinee di transizione e token di percorso.

2. Configura la richiesta API Routes in modo che soddisfi i requisiti per l'utilizzo di un token di percorso:

   • Imposta travelMode su DRIVE o TWO_WHEELER.
   • Imposta routingPreference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
   • Non utilizzare i waypoint Via.

Nota: puoi specificare valori precisi di origine e destinazione, come ingressi, banchine di carico o aree di ritiro designate, nel token del percorso utilizzando un token del punto di navigazione.

Passaggio 2: passa il token del percorso all'SDK Navigation

1. Memorizza il token del percorso: nell'SDK Navigation, configura una stringa per memorizzare il token del percorso. Ad esempio:

   String routeToken = "route token returned by Routes API";
   

   Esempio di token di route restituito:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Passa il token di route all'SDK Navigation utilizzando il metodo Navigator.setDestinationsWithToken. L'SDK Navigation recupera le destinazioni e le opzioni di routing dal token di percorso, quindi non è necessario passare i waypoint o una modalità di viaggio.

   setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
   setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
   

   Nota: se la tua app utilizza una versione dell'SDK di navigazione precedente alla 8.1, utilizza i metodi setDestinations deprecati che accettano CustomRoutesOptions e passa gli stessi waypoint di destinazione che hai utilizzato per creare il token di percorso.

3. Controlla lo stato del percorso nel callback. Quando l'SDK di navigazione termina il calcolo del percorso, passa un RouteDescription al callback. Se trova un percorso dalla posizione del veicolo alle destinazioni nel token di percorso, RouteDescription.getRouteStatus restituisce Navigator.RouteStatus.OK e puoi avviare le indicazioni stradali. Ad esempio:

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

Nota: se devi percorrere di nuovo lo stesso percorso, richiedi un nuovo token di percorso.

Verifica se l'SDK Navigation ha applicato il token di route

Uno stato del percorso OK indica che l'SDK Navigation ha trovato un percorso, ma non necessariamente quello pianificato. Per verificare se il percorso corrisponde a quello pianificato, segui questi passaggi nel callback:

1. Verifica che RouteDescription.getRouteStatus restituisca Navigator.RouteStatus.OK. L'SDK Navigation fornisce i dettagli del token di percorso solo quando trova un percorso. Per saperne di più, vedi il passaggio 2.

2. Chiama RouteDescription.getRouteTokenExecutionDetails per ottenere un oggetto RouteTokenExecutionDetails. Se il server non fornisce i dettagli del token di percorso, questo metodo restituisce null.

3. Chiama getTokenExecutionStatus sull'oggetto RouteTokenExecutionDetails. Se restituisce TOKEN_SUCCESSFULLY_APPLIED, il percorso corrisponde a quello pianificato. Qualsiasi altro stato indica che il percorso potrebbe differire da quello pianificato. Per saperne di più su ogni stato, consulta Valori dello stato di esecuzione del token.

4. (Facoltativo) Se lo stato è TOKEN_SUCCESSFULLY_APPLIED, chiama getResolvedParameters sullo stesso oggetto RouteTokenExecutionDetails per verificare quali opzioni di routing utilizza il percorso, ad esempio se evita i pedaggi. Per saperne di più, consulta Opzioni di routing risolte.

Valori dello stato di esecuzione del token

Se lo stato del percorso è OK, puoi avviare le indicazioni con qualsiasi stato di esecuzione del token. Lo stato indica se il percorso segue quello pianificato.

Stato	Segue il percorso pianificato	Descrizione
TOKEN_SUCCESSFULLY_APPLIED	Sì	L'SDK Navigation ha applicato il token di route.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH	Non necessariamente	L'SDK Navigation non ha potuto ricostruire il percorso pianificato perché una località nella richiesta di percorso si trovava a più di 25 metri dalla località corrispondente nel token del percorso. Con setDestinationsWithToken, questo significa che il dispositivo si trovava a più di 25 metri dall'origine nel token del percorso. Il percorso porta comunque alle tue destinazioni, ma l'SDK Navigation non può confermare che utilizzi le opzioni di routing del token di percorso, ad esempio l'evitamento dei pedaggi.
TOKEN_IGNORED_OTHER	Non necessariamente	L'SDK Navigation non è riuscito a ricostruire il percorso pianificato per un altro motivo, ad esempio perché una strada del percorso pianificato è chiusa. Il percorso porta comunque alle tue destinazioni, ma l'SDK Navigation non può confermare che utilizzi le opzioni di routing del token di percorso, ad esempio l'evitamento dei pedaggi.
NO_TOKEN_PROVIDED	Non applicabile	La richiesta di percorso non includeva un token di percorso.
UNKNOWN	Sconosciuto	Lo stato è sconosciuto.

Se il percorso non segue necessariamente quello pianificato e il percorso esatto è importante, ad esempio perché lo hai utilizzato per calcolare un prezzo, registra lo stato o richiedi un nuovo token di percorso dalla posizione attuale del veicolo.

Opzioni di routing risolte

getResolvedParameters restituisce un oggetto RouteTokenResolvedParameters o null se le opzioni di routing non sono disponibili. RouteTokenResolvedParameters ha i seguenti metodi:

• getTravelMode: la modalità di viaggio utilizzata dal percorso, ad esempio RoutingOptions.TravelMode.DRIVING. Il Navigation SDK restituisce anche RoutingOptions.TravelMode.DRIVING quando il percorso utilizza una modalità di viaggio che non ha un valore corrispondente o quando la modalità di viaggio non è disponibile.
• getAvoidTolls: indica se il percorso evita i pedaggi.
• getAvoidHighways: indica se il percorso evita le autostrade.
• getAvoidFerries: indica se il percorso evita i traghetti.

Esempio

Il seguente esempio di codice mostra come pianificare un percorso utilizzando un token di percorso, verificare se l'SDK Navigation ha applicato il token e avviare le indicazioni stradali.

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

Nota: puoi configurare un massimo di 25 waypoint.

Interazione tra i token di percorso e l'SDK Navigation

Ecco come l'SDK Navigation gestisce il percorso pianificato:

• Sostituisce le destinazioni impostate in precedenza.

• Utilizza la posizione di partenza del veicolo.

• Si adatta alle condizioni della strada e del traffico. Consulta la sezione Perché un percorso pianificato potrebbe non essere seguito esattamente.

• Utilizza le opzioni di routing impostate nel token di percorso anziché le seguenti impostazioni nell'app, anche quando calcola un nuovo percorso durante il viaggio:

  • RoutingOptions.avoidHighways
  • RoutingOptions.avoidTolls
  • RoutingOptions.avoidFerries
  • Navigator.setLicensePlateRestrictionInfo
  • La modalità di viaggio impostata nell'app

• Segue queste impostazioni quando calcola o modifica il percorso:

  • Obiettivi del percorso dal token del percorso, ad esempio il percorso ecologico o il percorso più breve. Se l'SDK di navigazione deve modificare il percorso, utilizza gli obiettivi del percorso specificati quando hai richiesto il token del percorso.
  • Opzioni relative ai waypoint dal token del percorso, ad esempio la preferenza per il lato della strada.

Nota: con setDestinationsWithToken, non passi i waypoint, quindi l'SDK Navigation utilizza le destinazioni e le opzioni dei waypoint dal token del percorso. Per impostare le opzioni dei waypoint, come la preferenza per il lato della strada o le soste del veicolo, utilizza i campi sideOfRoad e vehicleStopover sui waypoint nella richiesta all'API Routes. L'origine è sempre la posizione del dispositivo, pertanto le opzioni impostate sull'origine nella richiesta API Routes non vengono applicate.