Un feed di dati passo passo fornisce informazioni di sola navigazione ai dispositivi non progettati per fornire indicazioni di navigazione basate su mappe. Offre le manovre imminenti con gli elementi da te forniti:
- icone (sinistra, destra, inversione a U)
- svolta numeri nelle rotonde
- nomi di strade
- le distanze e il tempo stimati per il passaggio di navigazione successivo o per la destinazione finale
Puoi usare 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 utilizzarlo per i passeggeri di veicoli a due ruote, in cui puoi proiettare indicazioni solo per la 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 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 riceve informazioni di navigazione dall'SDK e fornisce lo stato di navigazione al dispositivo ricevente.
Panoramica
Questa sezione descrive come aggiungere la libreria TurnByTurn ai tuoi progetti e riassume il flusso di alto livello per la creazione di funzionalità passo passo.
Aggiungi la libreria TurnByTurn al tuo progetto utilizzando Maven (consigliato)
Per utilizzare una versione autonoma della libreria TurnByTurn, segui questi passaggi:
Configura il tuo ambiente per accedere al Repository Maven dell'host come descritto in Guida introduttiva all'SDK Driver nella Documentazione di Viaggi e ordini.
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' }
Aggiungi la libreria TurnByTurn al tuo progetto utilizzando un file JAR scaricato (in alternativa)
La libreria TurnByTurn è disponibile come file JAR in questa cartella SDK. Se non hai accesso, contatta il tuo rappresentante.
- Scarica e decomprimi
google_turnbyturn_*.jar
. - Copia il file JAR scaricato nella directory
app/libs
del progetto. Aggiungi quanto segue a
build.gradle
per includere il JAR nella build.dependencies { ... api fileTree(include: ['*.jar'], dir: 'libs') }
Uso della libreria TurnByTurn
Di seguito sono riportati i passaggi generali per attivare la funzionalità passo passo. Le sezioni successive forniscono i dettagli su ogni passaggio.
Creare un servizio per ricevere aggiornamenti di navigazione.
Esempio di visualizzazione di navigazione che mostra gli elementi essenziali.
Crea un servizio per ricevere aggiornamenti di navigazione {#service}
L'SDK di navigazione si associa al servizio TurnByTurn e gli invia gli aggiornamenti della 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 il servizio 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
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
, che è impostato sul valore
TurnByTurnManager.MSG_NAV_INFO
.
Registrazione del servizio per gli aggiornamenti di navigazione {#register}
I seguenti snippet di codice registrano il servizio di navigazione.
boolean isNavInfoReceivingServiceRegistered = navigator.registerServiceForNavUpdates( getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);
Avvio e interruzione del servizio
Il servizio di navigazione è attivo purché
l'SDK di navigazione sia associato. Puoi chiamare manualmente startService()
e stopService()
per controllare il ciclo di vita del servizio di navigazione; tuttavia, quando registri il servizio con l'SDK di navigazione, il servizio si avvia automaticamente e si interrompe solo quando ne annulli la registrazione. A seconda di come hai configurato l'app, ti consigliamo di avviare un servizio in primo piano, come descritto nella Panoramica dei servizi della documentazione Android.
Annullamento della registrazione del servizio in corso...
Per interrompere la ricezione degli aggiornamenti di navigazione, annulla la registrazione del servizio da SDK di navigazione.
navigator.unregisterServiceForNavUpdates();
Informazioni sugli stati di navigazione {#states}
Usa NavInfo.getNavState()
per ottenere lo stato di navigazione attuale, che è uno dei seguenti:
Instrada: lo stato
ENROUTE
indica che la navigazione guidata è attualmente attiva e l'utente si trova sul percorso fornito. Sono disponibili informazioni sull'attuale passaggio di manovra da seguire.Ricalcolo:
REROUTING
indica che la navigazione è in corso, ma il navigatore sta cercando un nuovo percorso. Il passo della manovra non è disponibile, perché non c'è ancora un nuovo percorso. Nell'app di esempio, viene visualizzato il messaggio "Rerouting..." nella visualizzazione delle informazioni di navigazione. Una volta trovata una route, viene inviato un messaggioNavInfo
con lo statoENROUTE
.Arrestata:
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 statoSTOPPED
cancella la visualizzazione delle informazioni di navigazione per impedire la visualizzazione di istruzioni sui passaggi continui.
Completa la visualizzazione del feed
Ora che hai configurato il servizio passo passo, questa sezione illustra gli elementi visivi e di testo che puoi utilizzare per completare le schede indicazioni per il feed passo passo.
Campi con informazioni sulla scheda di navigazione
Quando il conducente accede alla navigazione guidata, in alto viene visualizzata una scheda di navigazione contenente la data di navigazione compilata 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 dove puoi trovarli.
Campi per ogni passaggio della navigazione | Campi per l'intero percorso |
---|---|
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 Navigation rappresenta le corsie nella scheda di svolta della navigazione come oggetti dati Corsia 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 fare da questa corsia.
La direzione consigliata che un conducente deve seguire in una corsia è contrassegnata tramite il 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 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ù di una manovra a una singola icona. Ad esempio, TURN_LEFT
e ON_RAMP_LEFT
potrebbero essere entrambe mappate all'icona di svolta a sinistra.
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 guidare si trova sul lato sinistro della strada, gli automobilisti fanno una rotatoria o un'inversione a U in senso orario, mentre nei paesi che si trovano sul lato destro della strada vanno in senso orario. L'SDK di navigazione rileva se una manovra avviene nel traffico sul lato sinistro o sul lato destro e genera la manovra appropriata. Di conseguenza, l'icona della manovra potrebbe essere diversa
per una manovra in senso orario e antiorario.
Espandi per vedere esempi di icone per diverse manovre
Icona di esempio | manovre turn-by-turn |
---|---|
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 indicazioni relative alle manovre e alle corsie. Queste icone si adattano alle linee guida sulle dimensioni delle immagini della libreria di app Android Auto Auto che consiglia di scegliere come target un riquadro di delimitazione da 500 x 74 dp. Per informazioni dettagliate, consulta setsLaneImage e CarIcon nella documentazione di riferimento di Android.
Esempio di generazione dell'icona
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
completa i campi maneuverBitmap e lanesBitmap con le icone.
Passaggi successivi
- Per le app Android Auto: