Attiva il feed di dati passo passo

Un feed di dati passo passo fornisce informazioni di sola navigazione ai dispositivi non progettati per indicazioni di navigazione basate su mappa. Fornisce manovre future con gli elementi che fornisci:

• icone (sinistra, destra, inversione a U)
• indica i numeri delle rotatorie
• nomi di strade
• distanze stimate e tempo per il passaggio successivo della navigazione o la destinazione finale

Puoi utilizzare il feed passo passo per creare esperienze in cui l'UI completa dell'SDK di navigazione non è appropriata, ad esempio per Android Auto o per schermi di piccole dimensioni in cui non è disponibile uno stack Android completo. Ad esempio, potresti utilizzare questa funzionalità per i conducenti di veicoli a due ruote, in cui puoi fornire indicazioni di sola navigazione per aiutarli a raggiungere le loro destinazioni più velocemente e con maggiore sicurezza, con il minimo di distrazioni.

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

Questo documento mostra come creare e registrare un servizio di navigazione che ricevi informazioni di navigazione dall'SDK e fornisce lo stato di navigazione al dispositivo ricevente.

Panoramica

Questa sezione descrive come aggiungere la libreria TurnByTurn ai progetti e riepiloga il flusso generale per la creazione di funzionalità passo passo.

Aggiungi la libreria TurnByTurn al tuo progetto utilizzando Maven (consigliato)

Nota: puoi saltare questo passaggio se hai già configurato la tua app con l'SDK di navigazione, che a sua volta contiene la libreria TurnByTurn.

Per utilizzare una versione autonoma della libreria TurnByTurn, segui questi passaggi:

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()
   }
       

Aggiungi la seguente dipendenza alla configurazione Maven o Gradle:

2. 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'
   }
       

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

La libreria TurnByTurn è disponibile come file JAR in questa cartella SDK. Se non hai 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

Di seguito è riportata la procedura generale per attivare la funzionalità passo passo. Le sezioni che seguono forniscono dettagli su ogni passaggio.

1. Crea un servizio per ricevere aggiornamenti sulla navigazione.

2. Registra il servizio.

3. Informazioni sugli stati di navigazione.

4. Guarda un esempio di visualizzazione della navigazione che mostra elementi essenziali.

Crea un servizio per ricevere aggiornamenti sulla navigazione

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

Il vantaggio di utilizzare un servizio per ricevere aggiornamenti di navigazione è che può trovarsi in un processo in background separato.

Il servizio nell'esempio seguente riceve informazioni di navigazione e utilizza TurnByTurnManager per convertire i dati in un oggetto NavInfo che contiene 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, che è impostato sul valore TurnByTurnManager.MSG_NAV_INFO.

Nota: assicurati di escludere l'intervallo di valori 7200-7299 per i codici messaggio, perché l'SDK di navigazione potrebbe utilizzare i codici messaggio di questo intervallo in futuro.

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 di navigazione è vincolato. Puoi richiamare manualmente startService() e stopService() per controllare il ciclo di vita del servizio di navigazione, ma quando registri il tuo servizio con l'SDK di navigazione, il servizio viene avviato automaticamente e si interrompe solo quando annulli la registrazione. A seconda di come configuri l'app, ti consigliamo di avviare un servizio in primo piano, descritto nella panoramica dei servizi della documentazione di Android.

Annullamento della registrazione del servizio

Per non ricevere più aggiornamenti sulla navigazione, annulla la registrazione del servizio dall'SDK di navigazione.

navigator.unregisterServiceForNavUpdates();

Informazioni sugli stati della navigazione

Utilizza NavInfo.getNavState() per ottenere lo stato attuale della navigazione, che è uno dei seguenti:

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

• Cambio percorso: REROUTING significa che la navigazione è in corso, ma il navigatore sta cercando un nuovo percorso. Il passaggio successivo della manovra non è disponibile, perché non c'è ancora un nuovo percorso. Nell'app di esempio, nel display delle informazioni di navigazione viene visualizzato il messaggio "Cambio percorso...". Una volta trovata una route, viene inviato un messaggio NavInfo con lo stato ENROUTE.

• Arrestato: STOPPED significa 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 dettagliate sul passaggio.

Compila la visualizzazione del feed

Ora che hai configurato il servizio passo passo, in questa sezione vengono trattati gli elementi visivi e di testo che puoi utilizzare per compilare le schede informative del feed passo passo.

Campi delle informazioni della scheda di navigazione

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

Questa tabella mostra i campi delle informazioni di navigazione e la posizione in cui puoi trovarli.

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

Indicazione delle corsie in cui posizionarsi

L'SDK di navigazione rappresenta le corsie nella scheda della navigazione come oggetti dati Lane e LaneDirection. Un oggetto Lane rappresenta una corsia specifica durante la navigazione e ha un elenco di oggetti LaneDirection che descrivono tutte le svolte che è possibile effettuare 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 mostrate sopra.

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

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

Crea icone per le manovre

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

Devi creare le icone delle manovre e accoppiarle alle manovre associate. Per alcune manovre, puoi configurare una mappatura one-to-one su un'icona, ad esempio DESTINATION_LEFT e DESTINATION_RIGHT. Tuttavia, poiché alcune manovre sono simili, potresti voler mappare più manovre a una singola icona. Ad esempio, TURN_LEFT e ON_RAMP_LEFT possono essere mappati sull'icona di svolta a sinistra.

Utilizzo di Android Auto: le manovre nell'SDK di navigazione hanno una mappatura one-to-one ad Android Auto, ma devi convertirli nel formato corretto per Android Auto. Vedi Garantire i tipi di manovra corretti nella sezione Attivare la navigazione per Android Auto.

Alcune manovre contengono un'etichetta clockwise o counterclockwise aggiuntiva, che l'SDK determina in base al lato guida di un paese. Ad esempio, nei paesi in cui la guida si trova sul lato sinistro della strada, i conducenti fanno una rotatoria o l'inversione a U in senso orario, mentre quelli a destra vanno in senso orario. L'SDK di navigazione rileva se si verifica una manovra nel traffico sul lato destro o sinistro e restituisce la manovra appropriata. Pertanto, l'icona della manovra potrebbe essere diversa da quella in senso orario rispetto a quella in senso antiorario.

Espandi per visualizzare esempi di icone di diverse manovre

Icona di esempio	Manovre passo passo
	DEPART UNKNOWN
	STRAIGHT ON_RAMP_UNSPECIFIED OFF_RAMP_UNSPECIFIED NAME_CHANGE
	TURN_RIGHT ON_RAMP_RIGHT
	TURN_LEFT ON_RAMP_LEFT
	TURN_SLIGHT_RIGHT ON_RAMP_SLIGHT_RIGHT OFF_RAMP_SLIGHT_RIGHT
	TURN_SLIGHT_LEFT ON_RAMP_SLIGHT_LEFT OFF_RAMP_SLIGHT_LEFT
	TURN_SHARP_RIGHT ON_RAMP_SHARP_RIGHT OFF_RAMP_SHARP_RIGHT
	TURN_SHARP_LEFT ON_RAMP_SHARP_LEFT OFF_RAMP_SHARP_LEFT
	TURN_U_TURN_COUNTERCLOCKWISE ON_RAMP_U_TURN_COUNTERCLOCKWISE OFF_RAMP_U_TURN_COUNTERCLOCKWISE
	TURN_U_TURN_CLOCKWISE ON_RAMP_U_TURN_CLOCKWISE OFF_RAMP_U_TURN_CLOCKWISE
	ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
	ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_RIGHT_CLOCKWISE
	ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
	ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_STRAIGHT_CLOCKWISE
	ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
	ROUNDABOUT_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_LEFT_CLOCKWISE
	ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_SHARP_LEFT_CLOCKWISE
	ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
	ROUNDABOUT_U_TURN_CLOCKWISE
	ROUNDABOUT_COUNTERCLOCKWISE
	ROUNDABOUT_CLOCKWISE
	ROUNDABOUT_EXIT_COUNTERCLOCKWISE
	ROUNDABOUT_EXIT_CLOCKWISE
	MERGE_RIGHT OFF_RAMP_RIGHT
	MERGE_LEFT OFF_RAMP_LEFT
	FORK_RIGHT TURN_KEEP_RIGHT ON_RAMP_KEEP_RIGHT OFF_RAMP_KEEP_RIGHT
	FORK_LEFT TURN_KEEP_LEFT ON_RAMP_KEEP_LEFT OFF_RAMP_KEEP_LEFT
	MERGE_UNSPECIFIED
	DESTINATION
	DESTINATION_RIGHT
	DESTINATION_LEFT
	FERRY_BOAT
	FERRY_TRAIN

Utilizza icone generate

Per facilitare i casi d'uso di Android Auto, l'SDK di navigazione supporta la generazione di icone di manovra e indicazioni di corsia. Queste icone si adattano alle indicazioni di dimensionamento delle immagini della libreria di app Android Auto Car App, che consiglia il targeting di un riquadro di delimitazione di 500 x 74 dp. Per maggiori dettagli, vedi setsLaneImage e CarIcon nella documentazione di riferimento di Android.

Nota: la generazione di icone è disattivata per impostazione predefinita.

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 abilitato la generazione delle icone, l'oggetto TurnbyTurn StepInfo compila i campi maneuverBitmap e lanesBitmap con le relative icone.

Passaggi successivi

• Per le app Android Auto:
  • Traccia la mappa e abilita la navigazione.