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:

   let 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 setDestinationsWithToken:completionHandler: di mapView.navigator. Il Navigation SDK recupera le destinazioni e le opzioni di routing dal token di route, quindi non è necessario passare i waypoint.

   La modalità di viaggio impostata nella tua app, ad esempio mapView.travelMode, deve essere uno dei seguenti valori:

   • .driving (GMSNavigationTravelModeDriving): Guida. Questo è il valore predefinito, quindi la maggior parte delle app non deve modificarlo.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): veicolo a due ruote.

   Qualsiasi altra modalità di viaggio causa l'errore della richiesta con .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). Con entrambi i valori supportati, il percorso utilizza la modalità di viaggio nel token del percorso. Ad esempio, se la tua app utilizza la guida e il token di percorso è per un percorso per veicoli a due ruote, l'SDK Navigation fornisce un percorso per veicoli a due ruote. Per verificare la modalità di viaggio utilizzata dal percorso, controlla resolvedParameters.travelMode. Per saperne di più, consulta Opzioni di routing risolte.

   Nota: Se la tua app utilizza una versione dell'SDK di navigazione precedente alla 11.3, usa la versione deprecatasetDestinations:routeToken:callback: invece, usa questo metodo e passa gli stessi waypoint di destinazione che hai usato per creare il token di rotta.

3. Controlla lo stato del percorso nel gestore del completamento. Quando l'SDK Navigation termina il calcolo del percorso, passa un GMSNavigationRouteDescription al gestore del completamento. Se trova un percorso dalla posizione del veicolo alle destinazioni nel token del percorso, il valore di routeStatus della descrizione del percorso è .OK (GMSRouteStatusOK) e puoi avviare le indicazioni stradali. In caso contrario, il gestore del completamento riceve anche un NSError che descrive l'errore. Ad esempio:

   mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
     if routeDescription?.routeStatus == .OK {
       self?.mapView.navigator?.isGuidanceActive = true
     }
   }
   

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 gestore di completamento:

1. Verifica che il valore di routeStatus nella descrizione della route sia .OK. L'SDK Navigation fornisce i dettagli del token di route solo quando trova una route. Per saperne di più, consulta il passaggio 2.

2. Recupera l'oggetto routeTokenExecutionDetails della descrizione del percorso, che è conforme al protocollo GMSNavigationRouteTokenExecutionDetails. Se il server non fornisce i dettagli del token di percorso, questa proprietà è nil.

3. Controlla la proprietà tokenExecutionStatus dei dettagli di esecuzione. Se è .tokenSuccessfullyApplied, il percorso corrisponde a quello pianificato. Qualsiasi altro stato indica che il percorso potrebbe essere diverso da quello pianificato. Per saperne di più su ogni stato, consulta Valori dello stato di esecuzione del token.

4. (Facoltativo) Se lo stato è .tokenSuccessfullyApplied, controlla la proprietà resolvedParameters degli stessi dettagli di esecuzione per vedere 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 routeStatus è .OK, puoi avviare la guida con qualsiasi stato di esecuzione del token. Lo stato indica se il percorso segue quello pianificato.

Stato	Segue il percorso pianificato	Descrizione
.tokenSuccessfullyApplied	Sì	L'SDK Navigation ha applicato il token di route.
.tokenAppliedWithLocationMismatch	Non necessariamente	L'SDK di navigazione non è riuscito a ricostruire il percorso pianificato e il dispositivo si trovava a più di 25 metri dall'origine nel token del percorso. Il percorso utilizza comunque le destinazioni e le opzioni di routing del token del percorso.
.tokenIgnoredOther	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 utilizza comunque le destinazioni e le opzioni di routing del token del percorso.
.noTokenProvided	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

resolvedParameters è un oggetto conforme al protocollo GMSNavigationRouteTokenResolvedParameters o nil se le opzioni di routing non sono disponibili. Ha le seguenti proprietà:

• travelMode: la modalità di viaggio utilizzata dal percorso, ad esempio .driving (GMSNavigationTravelModeDriving). L'SDK Navigation segnala anche .driving quando il percorso utilizza una modalità di viaggio che non ha un valore corrispondente o quando la modalità di viaggio non è disponibile.
• avoidTolls: indica se il percorso evita i pedaggi.
• avoidHighways: indica se il percorso evita le autostrade.
• avoidFerries: indica se il percorso evita i traghetti.
• avoidTunnels: indica se il percorso è stato calcolato per evitare i tunnel, se possibile.
• avoidVignettes: i paesi in cui è stato calcolato il percorso per evitare i bollini per i pedaggi, se possibile, come codici regione di due lettere CLDR Unicode, ad esempio CH per la Svizzera.
• rerouteStrategy: la strategia utilizzata dal backend di routing per calcolare i nuovi percorsi durante il percorso. Le strategie includono .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), che utilizza i parametri di routing nel token di route per calcolare nuove route.

Se lo stato di esecuzione del token non è .tokenSuccessfullyApplied, l'SDK di navigazione segnala solo travelMode, avoidTolls, avoidHighways e avoidFerries. Le altre proprietà hanno i valori predefiniti, anche se hai chiesto di evitare tunnel o bollini per pedaggi quando hai richiesto il token del percorso: avoidTunnels è false (NO), avoidVignettes è vuoto e rerouteStrategy è .unknown (GMSNavigationRerouteStrategyUnknown).

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.

Swift

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

Objective-C

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

Scenari con più fermate

Puoi configurare un massimo di 25 waypoint.

L'SDK Navigation non passa automaticamente alla destinazione successiva. Quando il veicolo arriva a un waypoint, chiama continueToNextDestinationWithCompletion: per iniziare la tappa successiva della corsa. Questo vale anche per i token di percorso con waypoint intermedi. Quando passi alla destinazione successiva, l'SDK Navigation continua a seguire il percorso dal token di percorso anziché pianificare un nuovo percorso.

Attenzione: la chiamata al metodo continueToNextDestinationWithCompletion: a volte può generare un evento di arrivo errato, in cui la destinazione appena completata sembra essere selezionata di nuovo.

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:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • 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:completionHandler:, non passi i waypoint, quindi l'SDK di navigazione utilizza le destinazioni e le opzioni dei waypoint dal token del percorso. Per impostare le opzioni dei waypoint, ad esempio 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.