Implementare le intent delle app di navigazione

L'Assistente Google utilizza tre diversi formati di intent che la tua app di navigazione può supportare. Puoi ottenere l'interoperabilità e integrare la tua app e l'Assistente Google dichiarando i filtri per intent descritti in questa pagina nel file manifest della tua app. Per scoprire di più sulle intenzioni, consulta Intent.

La classe Intent dell'app di navigazione dell'assistente supporta le seguenti intenzioni:

• Intento di navigazione
• Intenzione di ricerca
• Intento dell'azione personalizzata

Nota: non è obbligatorio supportare tutti e tre gli intent per l'interoperabilità, ma consigliamo di supportarli tutti per un'esperienza utente completa.

Figura 1. Flusso di dati degli intent.

Parametri nei dati sull'intenzione

I dati dell'intent seguono un formato URI contenente parametri in base all'intent che stai passando. Alcuni parametri vengono sempre forniti nei dati. Ciò significa che puoi aspettarti che abbiano sempre un valore esplicito. I parametri facoltativi, tuttavia, non hanno sempre un valore impostato nei dati. Per ulteriori informazioni, consulta Test dei dati.

Intent offline

Per tutti gli intent elencati in questa pagina sono disponibili le varianti offline. Puoi distinguerli aggiungendo .offline al loro schema. Ad esempio, l'intent di navigazione utilizza lo schema geo.offline. Questi filtri per intent nel manifest indicano la capacità dell'app di supportare queste azioni offline.

Intento di navigazione

Utilizza un'intenzione di navigazione per soddisfare la richiesta di un utente di passare a una destinazione specifica. Questa destinazione può essere una singola località (indirizzo) o più località (ad esempio bar e stazioni di servizio). I dati dell'intent seguono un formato URI specificato per ogni intent.

Formato dell'intent

La classe Intent utilizza il seguente formato per l'intent di app di navigazione:

Categoria: android.intent.category.DEFAULT

Azione:

• Android Auto e Android Automotive OS: androidx.car.app.action.NAVIGATE
• Altri fattori di forma: android.intent.action.NAVIGATE

Schema: geo

Esempi:

• geo:0,0?q=Googleplex
• geo:0,0?q=1600+Amphitheatre+parkway&mode=b&intent=add_a_stop
• geo:0,0?q=coffee+shop&mode=w&intent=navigation
• geo:1.1,2.2?q=Starbucks+on+Main+Street&mode=w&intent=navigation

Comportamento suggerito per l'app: viene avviata la navigazione verso la posizione specificata o viene chiesto all'utente di scegliere tra più opzioni.

Filtri di intent del manifest

Dichiara il seguente formato di intent nel file manifest della tua app in modo che l'Assistente Google sappia che la tua app di navigazione può ricevere intent di navigazione.

Tutti i fattori di forma, ad eccezione di Android Auto e Android Automotive OS:

<intent-filter>
  <action android:name="android.intent.action.NAVIGATE" />
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:scheme="geo" />
</intent-filter>

Android Auto e Android Automotive OS:

<intent-filter>
  <action android:name="androidx.car.app.action.NAVIGATE" />
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:scheme="geo" />
</intent-filter>

Parametri forniti

I seguenti parametri dovrebbero essere disponibili nei dati sull'intenzione dell'app di navigazione forniti.

Query sulla posizione o coordinate geografiche

Ogni query sull'intenzione di navigazione contiene uno o entrambi questi parametri, a seconda del tipo di dati richiesti:

• Query sulla posizione

  Si riferisce alla posizione a cui l'utente sta cercando di arrivare. Utilizza questi dati per risolvere la destinazione dell'utente.

  Chiave del parametro: q
  Valore: la destinazione della query dell'utente.

  Esempio: geo:0,0?q=Golden+Gate+Bridge
  Interpretazione: l'utente vuole raggiungere il Golden Gate Bridge.

• Coordinate geografiche (latitudine e longitudine)

  Si riferisce a coordinate specifiche utilizzate dall'utente per la navigazione.

  Chiave del parametro: geo:lat,long
  Valore: le coordinate richieste dall'utente.

  Esempio: geo:1.1,2.2?mode=w&intent=navigation
  Interpretazione: l'utente vuole andare alle coordinate (1.1, 2.2).

Parametri facoltativi

I parametri facoltativi forniti nei dati sull'intenzione dell'app di navigazione sono descritti in questa sezione.

Intent

Definisce l'intenzione dell'utente. Se questo parametro non è impostato, l'intent dell'utente predefinito viene considerato navigation.

Nota: è diversa dalla classe Intent disponibile in Android.

Chiave del parametro: intent
Valori possibili:

• navigation [valore predefinito]: sostituisce la destinazione e avvia la navigazione. Utilizzalo per query come vai a x.
• add_a_stop: aggiunge la fermata come destinazione successiva insieme alle destinazioni precedenti. Utilizzalo per query come aggiungi una fermata a x.
• directions: mostra le indicazioni stradali del percorso senza avviare la navigazione. Utilizza questa opzione per query come indicazioni stradali per x.

Esempio: geo:47.61594547836694,-122.20373173098756?q=575+Bellevue+Square,+Bellevue,+WA+98004&intent=add_a_stop Interpretazione: l'utente vuole aggiungere una fermata a Bellevue Square, Bellevue, con le coordinate attuali [47,6, -122,2].

Suggerimento: puoi utilizzare l'emulatore Android Automotive OS per testare queste intenzioni.

Evita

Definisce gli elementi da evitare durante la navigazione.

Chiave del parametro: avoid
Valori possibili:

• f - traghetti
• h - autostrade
• t - pedaggi

Esempio: geo:0,0?q=googleplex&avoid=tf
Interpretazione: l'utente vuole raggiungere Googleplex evitando pedaggi e traghetti.

Modo di viaggio

La modalità di viaggio rappresenta il metodo di trasporto specificato nella query dall'utente.

Nota: questa modalità si applica a tutti i fattori di forma, ad eccezione del sistema operativo Android Automotive.

Chiave del parametro: mode
Valori possibili:

• b - bicicletta
• d - drive
• x - taxi
• l - veicolo a due ruote
• r - trasporto pubblico
• w - a piedi

Esempio: geo:0,0?q=Googleplex&mode=r
Interpretazione: l'utente vuole raggiungere Googleplex utilizzando i mezzi pubblici.

Voce

Utilizzato per registrare la sorgente della voce.

Valori possibili:assistant

Esempio: geo:47.61594547836694,-122.20373173098756?entry=assistant

Intenzione di ricerca

Utilizza un'intenzione di ricerca per cercare una query e visualizzare più risultati lungo il percorso mentre guidi.

Formato dell'intent

La classe Intent utilizza il seguente formato per le intenzioni di ricerca:

Categoria: android.intent.category.DEFAULT

Azione: android.intent.action.VIEW

Schema: geo

Esempio: geo:0,0?q=restaurants+nearby

Comportamento suggerito per l'app:apri un elenco di località corrispondenti alla query dell'utente.

Suggerimento: l'intenzione dell'app di navigazione e l'intenzione di ricerca hanno tipi di azioni diversi. La navigazione è ACTION_NAVIGATE mentre la ricerca è ACTION_VIEW come descritto in Filtri per intenzione del manifest.

Filtri di intent del manifest

Dichiara il seguente formato di intent nel file manifest della tua app in modo che l'Assistente Google sappia che la tua app di navigazione può ricevere intent di ricerca:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:scheme="geo" />
</intent-filter>

Parametri forniti

I seguenti parametri dovrebbero essere disponibili nei dati sull'intenzione di ricerca forniti.

Query sulla posizione

Una query sulla posizione è la posizione che l'utente sta cercando mentre guida. Questa query può essere imprecisa o lungo un percorso di navigazione attivo.

Chiave del parametro: q
Valore: il termine di ricerca dell'utente, che può essere un tipo di località come bar o università, ma può anche avere quantificatori come -vicino a me o -con la valutazione migliore.

Esempio: geo:0,0?q=restaurants+nearby
Interpretazione: l'utente vuole cercare ristoranti nelle vicinanze.

Intento dell'azione personalizzata

Utilizza un'intenzione personalizzata per azioni personalizzate come la segnalazione di incidenti e l'interruzione della navigazione. Il tipo di azione principale è definito dal parametro di query act. Puoi impostare parametri aggiuntivi a seconda del tipo di azione.

Formato dell'intent

La classe Intent utilizza il seguente formato per l'intenzione di azioni personalizzate:

Categoria: android.intent.category.DEFAULT

Azione: android.intent.action.VIEW

Schema: geo.action

Esempio: geo.action:?act=report&accident_type=major

Filtri di intent del manifest

Dichiara il seguente formato di intent nel file manifest della tua app per comunicare all'Assistente Google che la tua app di navigazione può ricevere intent di azioni personalizzate.

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:scheme="geo.action" />
</intent-filter>

Parametri forniti

Nei dati sull'intenzione dell'azione personalizzata forniti dovrebbero essere disponibili i seguenti parametri:

Tipo di azione

Definisce il tipo di azione personalizzata che un utente vuole eseguire.

Chiave parametro: act

Esempi:

• geo.action:?act=report_crash&accident_type=major
  Interpretazione: l'utente vuole segnalare un incidente grave.

• geo.action:?act=mute
  Interpretazione: l'utente vuole disattivare l'audio delle istruzioni vocali.

• geo.action:?act=exit_navigation
  Interpretazione: l'utente vuole uscire dalla navigazione corrente.

Comportamento suggerito per l'app:soddisfa l'azione richiesta nell'app di navigazione o mostra un messaggio relativo a un'azione non supportata.

La figura seguente mostra un esempio di coppie chiave-valore nella query di risposta:

Figura 2. Flusso di dati relativo alle intenzioni delle azioni personalizzate.

Coppia chiave-valore:

"act": "report_crash"
"road_direction": other_side"

Ogni azione personalizzata ha sempre un parametro act come chiave. Nel codice di esempio riportato sopra, alcune azioni possono avere coppie chiave-valore aggiuntive. Ad esempio, act=report_crash supporta queste chiavi aggiuntive: accident_type e road_direction.

La chiave accident_type può supportare due valori, minor e major.

Nota: i parametri aggiuntivi sono facoltativi e potrebbero non essere presenti in ogni risposta all'intent.

Valori possibili

La tabella elenca i possibili valori che l'Assistente Google può passare come azione che l'utente sta cercando di eseguire nell'app di navigazione.

Nota: se la tua app supporta solo un sottoinsieme di queste azioni, deve informare l'utente ogni volta che richiede un'azione non supportata.

Valore	Descrizione	Chiavi parametro facoltative	Valori dei parametri facoltativi
allow_ferries	Modifica la preferenza di percorso per consentire i traghetti.
allow_highways	Modifica la preferenza di percorso in modo da consentire le autostrade.
allow_tolls	Modifica la preferenza di percorso per consentire i pedaggi.
apply_electric_vehicle_connector_filter	Mostra solo le stazioni di ricarica EV che corrispondono al connettore dell'auto.
apply_electric_vehicle_fast_charging_filter	Mostra solo le stazioni di ricarica EV che sono stazioni di ricarica rapida.
apply_electric_vehicle_payment_filter	Mostra solo le stazioni di ricarica EV che richiedono un pagamento.
avoid_ferries	Modificare la preferenza di percorso per evitare i traghetti.
avoid_highways	Modificare la preferenza di percorso per evitare le autostrade.
avoid_tolls	Modificare la preferenza di percorso per evitare i pedaggi.
clear_search_results	Cancella i risultati di ricerca sulla mappa.
distance_to_destination	Mostra la distanza dalla destinazione.
distance_to_next_turn	Mostra la distanza dalla svolta successiva.
eta	Mostra l'orario di arrivo stimato alla destinazione.
exit_navigation	Uscire o annullare la navigazione.
follow_mode	Passa alla modalità di follow nella visualizzazione mappa.
go_back	Torna all'azione precedente sulla mappa.
hide_satellite	Modifica l'impostazione della mappa per nascondere le informazioni satellitari.
hide_traffic	Modifica l'impostazione della mappa per nascondere le informazioni sul traffico.
mute	Disattiva la guida vocale.
query_current_road	Mostra la strada attuale percorsa dall'utente.
query_destination	Mostra la destinazione.
query_next_turn	Indica la prossima svolta.
remove_electric_vehicle_connector_filter	Rimuovi i filtri per le stazioni di ricarica EV che corrispondono al connettore dell'auto.
remove_electric_vehicle_fast_charging_filter	Rimuovi i filtri per le stazioni di ricarica EV che sono punti di ricarica rapida.
remove_electric_vehicle_payment_filter	Rimuovi i filtri per le stazioni di ricarica EV che richiedono il pagamento.
report_crash	Segnalare arresti anomali.	accident_type	minor
			major
		road_direction	this_side
			other_side
report_hazard	Segnala i pericoli.	hazard_type	animal
			broken_traffic_light
			construction
			flooding
			fog
			hail
			ice
			missing_sign
			object_on_road
			pothole
			roadkill
			snow
			vehicle
			weather
		road_direction	this_side
			other_side
		location_on_road	on_road
			on_shoulder
report_police	Segnala l'attività della polizia.	road_direction	this_side
			other_side
report_road_closure	Segnalare chiusure stradali.	road_closure_type	partial
			full
report_traffic	Segnala il traffico.	traffic_type	moderate
			heavy
			standstill
		road_direction	this_side
			other_side
resume_navigation	Riprendi la navigazione.
route_overview	Mostra la panoramica del percorso.
show_alternates	Mostrare percorsi alternativi.
show_directions_list	Mostra le istruzioni stradali passo passo.
show_satellite	Mostra le informazioni satellitari sulla mappa.
show_traffic	Mostra il traffico sulla mappa.
time_to_destination	Mostra l'orario di arrivo stimato alla destinazione.
time_to_next_turn	Mostra l'orario di arrivo stimato al prossimo tratto.
unmute	Riattiva la guida vocale.