Attiva il feed di dati passo passo

Un feed di dati passo passo fornisce informazioni di sola navigazione ai dispositivi non progettati per la guida alla navigazione basata su mappe. Fornisce le manovre imminenti con gli elementi che fornisci:

• Icone (svolta a sinistra, svolta a destra, inversione a U)
• numeri di svolta nelle rotatorie
• nomi di strade
• Distanze e tempi stimati per la tappa successiva della navigazione o la destinazione finale

Puoi utilizzare il feed passo passo per creare esperienze in cui l'interfaccia utente completa dell'SDK di navigazione non è appropriata, ad esempio per Android Auto o per display di piccole dimensioni in cui non è disponibile uno stack Android completo. Ad esempio, potresti utilizzarlo per i conducenti di veicoli a due ruote, per i quali puoi proiettare indicazioni di sola navigazione per aiutarli a raggiungere le loro destinazioni in modo più rapido e sicuro con distrazioni minime.

Per utilizzare l'SDK, devi 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 mostra come creare e registrare un servizio di navigazione che riceve informazioni di navigazione dall'SDK e fornisce lo stato di navigazione al dispositivo di destinazione.

Panoramica

Questa sezione riassume il flusso generale per l'attivazione della funzionalità di navigazione passo passo.

Utilizzo della funzionalità TurnByTurn

Di seguito sono riportati i passaggi generali 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.

Crea un servizio per ricevere gli aggiornamenti di navigazione

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

Il vantaggio di utilizzare 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 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 dei messaggi

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

Nota: assicurati di mettere da parte l'intervallo di valori 7200-7299 per i codici dei messaggi, perché l'SDK di navigazione potrebbe utilizzare i codici dei messaggi in 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 Navigation è associato. 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 annulli la registrazione. A seconda di come configuri l'app, potresti prendere in considerazione l'avvio di un servizio in primo piano, descritto nella documentazione di Android Panoramica dei servizi.

Annullamento della registrazione del servizio

Per interrompere la ricezione degli 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 attuale della navigazione, che è uno dei seguenti:

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

• Cambio percorso: REROUTING indica che la navigazione è in corso, ma il navigatore sta cercando un nuovo percorso. Il passaggio della manovra imminente non è disponibile perché non esiste ancora un nuovo percorso. Nell'app di esempio, viene visualizzato il messaggio "Cambio percorso in corso…" nel display 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 di passaggio persistenti.

Compila la visualizzazione del feed

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

Campi di informazioni della scheda di navigazione

Quando l'utente accede alla navigazione guidata, nella parte superiore 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 il percorso complessivo
Trovato in StepInfo	Trovato in NavInfo
Nome completo della strada	Tempo rimanente
Icona della manovra	Distanza dalla destinazione
Distanza dal passaggio successivo
Campi di indicazione delle corsie in cui posizionarsi

Indicazione delle corsie in cui posizionarsi

L'SDK di navigazione rappresenta le corsie nella scheda di svolta della navigazione come oggetti dati Lane 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 effettuate 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 icone di manovra e associarle alle manovre corrispondenti. Per alcune manovre, puoi configurare una mappatura uno a uno con un'icona, ad esempio DESTINATION_LEFT e DESTINATION_RIGHT. Tuttavia, poiché alcune manovre sono simili, potresti voler mappare più di una manovra a una singola icona. Ad esempio, TURN_LEFT e ON_RAMP_LEFT potrebbero essere mappati entrambi all'icona di svolta a sinistra.

Manovre di Android Auto: le manovre nell'SDK Navigation hanno una mappatura uno a uno con Android Auto, ma devi convertire i tipi nel formato corretto per Android Auto. Consulta Verifica i tipi di manovra corretti in Attiva la navigazione per Android Auto.

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 sul lato sinistro della strada, i conducenti percorrono una rotatoria o un'inversione a U in senso orario, mentre nei paesi in cui si guida sul lato destro della strada, la percorrono in senso antiorario. L'SDK Navigation rileva se una manovra avviene nel traffico a sinistra o a destra e genera la manovra appropriata. Pertanto, l'icona della manovra potrebbe essere diversa per una manovra in senso orario rispetto a una in senso antiorario.

Espandi per visualizzare le icone di esempio per le 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 le icone generate

Per facilitare i casi d'uso di Android Auto, l'SDK Navigation supporta la generazione di icone di indicazioni stradali e di corsia. Queste icone sono conformi alle indicazioni per le dimensioni delle immagini della raccolta di app per auto di Android Auto, che consiglia di utilizzare un riquadro di delimitazione di 500 x 74 dp. Per maggiori dettagli, consulta 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 attivato la generazione delle 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.