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

Flusso di dati sugli intent

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.

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.

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

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.

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.

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:

Flusso di dati sull&#39;intent dell&#39;azione personalizzata

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.

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.

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.