Un feed di dati con indicazioni stradali fornisce informazioni solo di navigazione ai dispositivi non progettati per le indicazioni stradali basate su mappe. Fornisce le manovre imminenti con gli elementi che fornisci:

• icone (sinistra, destra, inversione a U)
• numeri di svolta negli rotondi
• nomi delle strade
• distanze e tempi stimati per il passaggio di navigazione successivo o per la destinazione finale

Puoi utilizzare il feed dettagliato per creare esperienze in cui l'interfaccia utente completa dell'SDK Navigation non è appropriata, ad esempio per Android Auto o per display con schermo piccolo in cui non è disponibile uno stack Android completo. Ad esempio, potresti usarlo per i conducenti di veicoli a due ruote, in cui puoi proiettare indicazioni solo per la navigazione per aiutarli a raggiungere le loro destinazioni più velocemente e con maggiore sicurezza, con il minimo delle distrazioni.

Per utilizzare l'SDK, dovrai creare un servizio e registrarlo con l'SDK Navigation per Android in modo che possa ricevere nuove informazioni di navigazione in tempo reale (circa una volta al secondo durante la navigazione).

Questo documento spiega come creare e registrare un servizio di navigazione che riceve informazioni di navigazione dall'SDK e fornisce lo stato di navigazione al dispositivo di ricezione.

Panoramica

Questa sezione descrive come aggiungere la libreria TurnByTurn ai progetti e riassume il flusso di alto livello per creare la funzionalità di navigazione passo passo.

Aggiungi la libreria TurnByTurn al progetto utilizzando Maven (opzione consigliata)

Per utilizzare una versione autonoma della libreria TurnByTurn:

1. Configura il tuo ambiente per accedere al repository Maven host:

   Maven

   Aggiungi quanto segue al tuo file pom.xml:

       <project>
         ...
         <repositories>
           <repository>
             <id>google-maven-repository</id>
             <url>https://maven.google.com</url>
           </repository>
         </repositories>
         ...
       </project>
       
       

   Gradle

   Aggiungi quanto segue al tuo file build.gradle:

   repositories {
       ...
       google()
   }
       

2. Aggiungi la seguente dipendenza alla configurazione Maven o Gradle:

   Maven

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.maps</groupId>
       <artifactId>google_turnbyturn</artifactId>
       <version>1.0.0</version>
     </dependency>
   </dependencies>
       
       

   Gradle

   dependencies {
     ...
     implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
   }
       

Aggiungere la libreria TurnByTurn al progetto utilizzando un file JAR scaricato (alternativa)

La libreria TurnByTurn è disponibile come file JAR in questa cartella dell'SDK. Se non disponi dell'accesso, contatta il tuo rappresentante.

1. Scarica e decomprimi google_turnbyturn_*.jar.
2. Copia il file JAR scaricato nella directory app/libs del progetto.

3. Aggiungi quanto segue a build.gradle per includere il JAR nella build.

   dependencies {
       ...
       api fileTree(include: ['*.jar'], dir: 'libs')
   }
   

Utilizzo della libreria TurnByTurn

Ecco i passaggi di alto livello per attivare la funzionalità di navigazione passo passo. Le sezioni riportate di seguito forniscono dettagli su ogni passaggio.

1. Crea un servizio per ricevere gli aggiornamenti di navigazione.

2. Registra il servizio.

3. Informazioni sugli stati di navigazione.

Creare un servizio per ricevere aggiornamenti di navigazione

L'SDK Navigation si lega al servizio TurnByTurn e gli invia gli aggiornamenti di navigazione tramite Android Messenger. Puoi creare un nuovo servizio di navigazione per questi aggiornamenti o utilizzare un servizio esistente.

Il vantaggio dell'utilizzo di un servizio per ricevere gli aggiornamenti di navigazione è che il servizio può essere eseguito in un processo in background separato.

Il servizio nell'esempio seguente riceve le informazioni di navigazione e utilizza TurnByTurnManager per convertire i dati in un oggetto NavInfo contenente i dettagli di navigazione.

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

Codici messaggio

I messaggi NavInfo possono essere identificati tramite il campo Message.what della classe Message, impostato sul valore di TurnByTurnManager.MSG_NAV_INFO.

Registrazione del servizio per gli aggiornamenti di navigazione

I seguenti snippet di codice registrano il servizio di navigazione.

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

Avvio e arresto del servizio

Il servizio di navigazione è attivo finché l'SDK Navigation si lega. Puoi chiamare manualmente startService() e stopService() per controllare il ciclo di vita del servizio di navigazione, ma quando registri il servizio con l'SDK Navigation, il servizio si avvia automaticamente e si interrompe solo quando lo annulli. A seconda di come configuri l'app, potresti prendere in considerazione l'avvio di un servizio in primo piano, descritto nella Panoramica dei servizi della documentazione di Android.

Annullamento della registrazione del servizio

Per smettere di ricevere aggiornamenti di navigazione, annulla la registrazione del servizio dall'SDK Navigation.

navigator.unregisterServiceForNavUpdates();

Informazioni sugli stati di navigazione

Utilizza NavInfo.getNavState() per ottenere lo stato corrente della navigazione, che è uno di quanto segue:

• In viaggio: lo stato ENROUTE indica che la navigazione guidata è attualmente attiva e che l'utente si trova sul percorso fornito. Sono disponibili informazioni sul prossimo passaggio di manovra.

• Cambio percorso: REROUTING indica che la navigazione è in corso, ma il navigatore sta cercando un nuovo percorso. Il passaggio di manovra imminente non è disponibile perché non esiste ancora un nuovo percorso. Nell'app di esempio, viene visualizzato il messaggio "Rinnovo percorso…" nella schermata delle informazioni di navigazione. Una volta trovato un percorso, viene inviato un messaggio NavInfo con lo stato ENROUTE.

• Interrotta: STOPPED indica che la navigazione è terminata. Ad esempio, la navigazione si interrompe quando l'utente esce dalla navigazione nell'app. Nell'app di esempio, uno stato STOPPED cancella la visualizzazione delle informazioni di navigazione per impedire la visualizzazione di istruzioni passo passo inutilizzate.

Compilare la visualizzazione del feed

Ora che hai configurato il servizio di navigazione passo passo, questa sezione illustra gli elementi visivi e di testo che puoi utilizzare per compilare le schede di guida per il feed di navigazione passo passo.

Campi di informazioni delle schede di navigazione

Quando l'utente attiva la navigazione guidata, in alto viene visualizzata una scheda di navigazione contenente i dati di navigazione compilati dall'SDK Navigation. L'immagine correlata mostra un esempio di questi elementi di navigazione essenziali.

Questa tabella mostra i campi per le informazioni di navigazione e dove trovarli.

Campi per ogni passaggio di navigazione	Campi per la corsa complessiva
Risultati trovati in StepInfo	Risultati trovati in NavInfo
Nome completo della strada	Tempo rimanente
L'icona della manovra	Distanza dalla destinazione
Distanza dal passaggio successivo
Campi di indicazione delle corsie in cui posizionarsi

Indicazioni sulle corsie in cui posizionarsi

L'SDK Navigation rappresenta le corsie nella scheda di svolta della navigazione come oggetti di dati Corsia e LaneDirection. Un oggetto Lane rappresenta una corsia specifica durante la navigazione e contiene un elenco di oggetti LaneDirection che descrivono tutte le svolte che possono essere compiute da questa corsia.

La direzione consigliata che un utente deve seguire in una corsia è contrassegnata dal campo isRecommended.

Esempio di indicazione delle corsie in cui posizionarsi

Lo snippet seguente illustra la rappresentazione dei dati delle corsie visualizzate sopra.

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

Creare icone per le manovre

L'enum Maneuver definisce ogni possibile manovra che potrebbe verificarsi durante la navigazione e puoi recuperare la manovra per un determinato passaggio dal metodo StepInfo.getManeuver().

Devi creare icone di manovra e associarle alle manovre associate. Per alcune manovre, puoi configurare una mappatura uno a uno a un'icona, ad esempio DESTINATION_LEFT e DESTINATION_RIGHT. Tuttavia, poiché alcune manovre sono simili, ti consigliamo di mappare più di una manovra a una singola icona. Ad esempio, TURN_LEFT e ON_RAMP_LEFT potrebbero essere entrambi mappati all'icona di svolta a sinistra.

Alcune manovre contengono un'etichetta clockwise o counterclockwise aggiuntiva, che l'SDK determina in base al lato di guida di un paese. Ad esempio, nei paesi in cui si guida a sinistra, i conducenti fanno un giro a 360 gradi o un'inversione a U in senso orario, mentre nei paesi in cui si guida a destra, si gira in senso orario. L'SDK di navigazione rileva se una manovra avviene nel traffico a sinistra o a destra e la emette. Pertanto, l'icona della manovra può essere diversa per una manovra in senso orario rispetto a una in senso antiorario.

Utilizzare le icone generate

Per semplificare i casi d'uso di Android Auto, l'SDK Navigation supporta la generazione di icone di indicazione di manovre e corsie. Queste icone rispettano le indicazioni sulle dimensioni delle immagini della raccolta di app per auto Android Auto, che consiglia di scegliere come target una casella delimitante di 500 x 74 dp. Per informazioni dettagliate, consulta setsLaneImage e CarIcon nella documentazione di riferimento di Android.

Esempio di generazione di icone

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

Dopo aver attivato la generazione di icone, l'oggetto TurnbyTurn StepInfo compila i campi maneuverBitmap e lanesBitmap con le icone.

Passaggi successivi

• Per le app Android Auto:
  • Disegna la mappa e attiva la navigazione.