Implementare le intent delle app di navigazione

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

La classe dell'app di navigazione Gemini Intent supporta i seguenti intent:

• Intent di navigazione
• Intenzione di ricerca
• Intent di azione personalizzata

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

Figura 1. Flusso di dati sugli intent.

Parametri nei dati di intent

I dati intent seguono un formato URI contenente parametri basati sull'intent che stai trasmettendo. Alcuni parametri vengono sempre forniti nei dati. Ciò significa che puoi aspettarti che abbiano sempre un valore esplicito. I parametri facoltativi, tuttavia, non sempre hanno un valore impostato nei dati. Per saperne di più, consulta Test dei dati.

Intent offline

Tutti gli intent elencati in questa pagina hanno le varianti offline disponibili. 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.

Intent di navigazione

Utilizza un intent di navigazione per soddisfare la richiesta di un utente di raggiungere una destinazione specifica. Questa destinazione può essere una singola posizione (indirizzo) o più posizioni (ad esempio, bar e stazioni di servizio). I dati sugli intent seguono un formato URI specificato per ogni intent.

Formato dell'intent

La classe Intent utilizza il seguente formato per l'intent dell'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 dell'app: inizia la navigazione verso la posizione specificata o all'utente viene chiesto di scegliere tra più opzioni.

Filtri per intent del manifest

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

Tutti i fattori di forma, tranne 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 devono essere disponibili nei dati intent dell'app di navigazione forniti.

Query sulla posizione o coordinate geografiche

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

• Query sulla posizione

  Si riferisce alla posizione che l'utente sta cercando di raggiungere. Utilizza questi dati per risolvere la destinazione dell'utente.

  Chiave parametro:q
  Valore:la destinazione richiesta dall'utente.

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

• Coordinate geografiche (latitudine e longitudine)

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

  Chiave parametro:geo:lat,long
  Valore:le coordinate della query dell'utente.

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

Parametri facoltativi

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

Intent

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

Nota: questo attributo è diverso dalla classe Intent disponibile in Android.

Chiave parametro: intent
Valori possibili:

• navigation [valore predefinito] - Sostituisce la destinazione e avvia la navigazione. Utilizza questo comando per query come naviga fino a x.
• add_a_stop: aggiunge la fermata come destinazione successiva insieme alle destinazioni precedenti. Utilizza questo tipo di query per richieste come aggiungere una fermata a x.
• directions: mostra le indicazioni stradali senza avviare la navigazione. Utilizza questo per query come indicazioni 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 questi intent.

Evita

Definisce le cose da evitare nella navigazione.

Chiave 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.

Modalità 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 di Android Automotive OS.

Chiave parametro: mode
Valori possibili:

• b - bicicletta
• d - drive
• x - taxi
• l - motociclo
• r - transito
• w - camminata

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

Entry

Utilizzato per registrare la fonte di ingresso.

Valori possibili: assistente

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

Intenzione di ricerca

Utilizza un intento 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 gli intent di ricerca:

Categoria: android.intent.category.DEFAULT

Azione: android.intent.action.VIEW

Schema: geo

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

Comportamento suggerito dell'app:aprire un elenco di località che corrispondono alla query dell'utente.

Suggerimento: l'intent dell'app di navigazione e l'intenzione di ricerca hanno tipi di azione diversi. La navigazione è ACTION_NAVIGATE mentre la ricerca è ACTION_VIEW come descritto nei filtri per intent del file manifest.

Filtri per intent del manifest

Dichiara il seguente formato di intent nel file manifest della tua app in modo che Gemini 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'intento di ricerca forniti.

Query sulla posizione

Una query di 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 potrebbe essere un tipo di località come caffetteria o università, ma potrebbe anche avere quantificatori come -vicino a me o -con la migliore valutazione.

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

Intent di azione personalizzata

Utilizza un intent personalizzato per azioni personalizzate come la segnalazione di incidenti e la fine 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'intent di azione personalizzata:

Categoria: android.intent.category.DEFAULT

Azione: android.intent.action.VIEW

Schema: geo.action

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

Filtri per intent del manifest

Dichiara il seguente formato di intent nel file manifest della tua app per comunicare a Gemini 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

I seguenti parametri devono essere disponibili nei dati dell'intent dell'azione personalizzata forniti:

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 le istruzioni vocali.

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

Comportamento suggerito dell'app: esegui l'azione richiesta nell'app di navigazione o mostra un messaggio di azione non supportata.

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

Figura 2. Flusso di dati degli intent 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 menzionato in precedenza, 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 Gemini può passare come azione che l'utente sta cercando di completare 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 dei parametri facoltativi	Valori dei parametri facoltativi
allow_ferries	Modifica la preferenza del percorso per consentire i traghetti.
allow_highways	Modifica la preferenza di percorso per consentire le autostrade.
allow_tolls	Modifica la preferenza di percorso per consentire i pedaggi.
avoid_ferries	Modifica la preferenza del percorso per evitare i traghetti.
avoid_highways	Modifica la preferenza del percorso per evitare le autostrade.
avoid_tolls	Modifica la preferenza del percorso per evitare i pedaggi.
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 dalla navigazione o annullarla.
follow_mode	Passa alla modalità Segui.
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 su cui si trova attualmente l'utente.
query_destination	Mostra la destinazione.
query_next_turn	Mostra la prossima svolta.
report_crash	Segnalare arresti anomali.	accident_type	minor
			major
		road_direction	this_side
			other_side
report_hazard	Segnala 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 attività della polizia.	road_direction	this_side
			other_side
report_road_closure	Segnala chiusure stradali.	road_closure_type	partial
			full
report_traffic	Segnala il traffico.	traffic_type	moderate
			heavy
			standstill
		road_direction	this_side
			other_side
route_overview	Mostra panoramica del percorso.
show_alternates	Mostra percorsi alternativi.
show_directions_list	Mostra le indicazioni 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 a destinazione.
time_to_next_turn	Mostra l'orario di arrivo stimato per la prossima svolta.
unmute	Riattiva la guida vocale.

Recuperare lo stato della navigazione

Per contribuire a garantire che Gemini possa fornire informazioni accurate e in tempo reale all'utente quando chiede informazioni sullo stato del suo viaggio, la tua app deve fornire metadati di navigazione utilizzando il NavigationManager servizio di auto. Per indicazioni sull'implementazione, consulta Comunicare i metadati di navigazione.