Implementar intents de apps de navegação

O Gemini usa três formatos diferentes de intents que seu app de navegação pode oferecer suporte. Para alcançar a interoperabilidade e integrar seu app ao Gemini, declare os filtros de intent detalhados nesta página no manifesto do app. Para saber mais sobre intenções, consulte Intent.

A classe do app de navegação do Gemini Intent é compatível com estas intents:

• Intent de navegação
• Intenção da pesquisa
• Intent de ação personalizada

Observação: não é necessário oferecer suporte a todas as três intents para interoperabilidade, mas recomendamos que você ofereça suporte a todas elas para uma experiência completa do usuário.

Figura 1. Fluxo de dados de intenção.

Parâmetros nos dados de intent

Os dados de intent seguem um formato de URI que contém parâmetros com base na intent que você está transmitindo. Alguns parâmetros são sempre fornecidos nos dados. Isso significa que você pode esperar que eles sempre tenham um valor explícito. No entanto, os parâmetros opcionais nem sempre têm um valor definido nos dados. Para mais informações, consulte Teste de dados.

Intents off-line

Todas as intents listadas nesta página têm variantes off-line disponíveis. Para diferenciá-los, adicione .offline ao esquema. Por exemplo, a intent de navegação usa o esquema geo.offline. Esses filtros de intent no manifesto indicam a capacidade do app de oferecer suporte a essas ações off-line.

Intent de navegação

Use uma intent de navegação para atender ao pedido de um usuário de navegar até um destino específico. O destino pode ser um único local (endereço) ou vários locais (por exemplo, cafeterias e postos de gasolina). Os dados de intent seguem um formato de URI especificado para cada intent.

Formato da intent

A classe Intent usa o seguinte formato para a intent do app de navegação:

Categoria:android.intent.category.DEFAULT

Ação:

• Android Auto e Android Automotive OS: androidx.car.app.action.NAVIGATE
• Outros formatos: android.intent.action.NAVIGATE

Esquema: geo

Exemplos:

• 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 sugerido do app:a navegação até o local especificado é iniciada ou o usuário precisa escolher entre várias opções.

Filtros de intent do manifesto

Declare o seguinte formato de intent no arquivo de manifesto do app para que o Gemini saiba que seu app de navegação pode receber intents de navegação.

Todos os formatos, exceto 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>

Parâmetros fornecidos

Os seguintes parâmetros precisam estar disponíveis nos dados de intent do app de navegação fornecidos.

Consulta de local ou coordenadas geográficas

Cada consulta de intent de navegação contém um ou os dois parâmetros, dependendo do tipo de dados solicitado:

• Consulta de local

  Refere-se ao local para onde o usuário está tentando navegar. Use esses dados para resolver o destino do usuário.

  Chave do parâmetro:q
  Valor:o destino consultado pelo usuário.

  Exemplo:geo:0,0?q=Golden+Gate+Bridge
  Interpretação:o usuário quer navegar até a Ponte Golden Gate.

• Coordenadas geográficas (latitude e longitude)

  Refere-se a coordenadas específicas usadas pelo usuário para navegação.

  Chave do parâmetro:geo:lat,long
  Valor:as coordenadas consultadas pelo usuário.

  Exemplo:geo:1.1,2.2?mode=w&intent=navigation
  Interpretação:o usuário quer navegar até as coordenadas (1.1, 2.2).

Parâmetros opcionais

Os parâmetros opcionais fornecidos nos dados de intent do app de navegação são descritos nesta seção.

Intent

Define a intenção do usuário. Se esse parâmetro não for definido, a intenção padrão do usuário será considerada navigation.

Observação: isso é diferente da classe Intent disponível no Android.

Chave do parâmetro:intent
Valores possíveis:

• navigation [valor padrão]: substitui o destino e inicia a navegação. Use isso para consultas como navegar até x.
• add_a_stop: adiciona a parada como o próximo destino junto com os destinos anteriores. Use isso para consultas como adicionar parada em x.
• directions: mostra as rotas sem iniciar a navegação. Use isso para consultas como como chegar em x.

Exemplo:geo:47.61594547836694,-122.20373173098756?q=575+Bellevue+Square,+Bellevue,+WA+98004&intent=add_a_stop Interpretação:o usuário quer adicionar parada em Bellevue Square, Bellevue, com as coordenadas atuais [47.6, -122.2].

Dica: use o emulador do Android Automotive OS para testar essas intents.

Evitar

Define o que evitar na navegação.

Chave do parâmetro:avoid
Valores possíveis:

• f - balsas
• h: rodovias
• t: pedágios

Exemplo:geo:0,0?q=googleplex&avoid=tf
Interpretação:o usuário quer navegar até o Googleplex evitando pedágios e balsas.

Modo de viagem

O modo de viagem representa o método de transporte especificado na consulta pelo usuário.

Observação: esse modo se aplica a todos os formatos, exceto o Android Automotive OS.

Chave do parâmetro:mode
Valores possíveis:

• b: bicicleta
• d – carro
• x: táxi
• l - veículo de duas rodas
• r: transporte público
• w: caminhada

Exemplo:geo:0,0?q=Googleplex&mode=r
Interpretação:o usuário quer ir até o Googleplex usando transporte público.

Entrada

Usado para registrar a origem da entrada.

Valores possíveis:assistente

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

Intenção da pesquisa

Use uma intenção da pesquisa para pesquisar uma consulta e mostrar vários resultados ao longo da rota enquanto dirige.

Formato da intent

A classe Intent usa o seguinte formato para intents de pesquisa:

Categoria:android.intent.category.DEFAULT

Ação: android.intent.action.VIEW

Esquema: geo

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

Comportamento sugerido do app:abrir uma lista de locais que correspondem à consulta do usuário.

Dica: os intents de navegação e intenção da pesquisa têm tipos de ação diferentes. A navegação é ACTION_NAVIGATE e a pesquisa é ACTION_VIEW conforme descrito nos filtros de intent do manifesto.

Filtros de intent do manifesto

Declare o seguinte formato de intent no arquivo de manifesto do seu app para que o Gemini saiba que seu app de navegação pode receber intents de pesquisa:

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

Parâmetros fornecidos

Os seguintes parâmetros devem estar disponíveis nos dados de intenção da pesquisa fornecidos.

Consulta de local

Uma consulta de local é o local que o usuário está pesquisando enquanto dirige. Essa consulta pode ser imprecisa ou ao longo de uma rota de navegação ativa.

Chave do parâmetro:q
Valor:o termo de pesquisa do usuário, que pode ser um tipo de local, como cafeteria ou faculdade, mas também pode ter quantificadores, como -perto de mim ou -com a melhor classificação.

Exemplo:geo:0,0?q=restaurants+nearby
Interpretação:o usuário quer pesquisar restaurantes por perto.

Intent de ação personalizada

Use uma intent personalizada para ações personalizadas, como informar acidentes e encerrar a navegação. O tipo de ação principal é definido pelo parâmetro de consulta act. É possível definir outros parâmetros dependendo do tipo de ação.

Formato da intent

A classe Intent usa o seguinte formato para intents de ações personalizadas:

Categoria:android.intent.category.DEFAULT

Ação: android.intent.action.VIEW

Esquema: geo.action

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

Filtros de intent do manifesto

Declare o seguinte formato de intent no arquivo de manifesto do app para informar ao Gemini que seu app de navegação pode receber intents de ação personalizadas.

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

Parâmetros fornecidos

Espera-se que os seguintes parâmetros estejam disponíveis nos dados de intent da ação personalizada fornecida:

Tipo de ação

Ele define o tipo de ação personalizada que um usuário quer realizar.

Chave do parâmetro:act

Exemplos:

• geo.action:?act=report_crash&accident_type=major
  Interpretação:o usuário quer informar um acidente grave.

• geo.action:?act=mute
  Interpretação:o usuário quer desativar as instruções por voz.

• geo.action:?act=exit_navigation
  Interpretação:o usuário quer sair da navegação atual.

Comportamento sugerido do app:execute a ação solicitada no app de navegação ou mostre uma mensagem de ação não compatível.

A figura a seguir mostra um exemplo de pares de chave-valor na consulta de resposta:

Figura 2. Fluxo de dados de intent de ação personalizada.

Par de chave-valor:

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

Toda ação personalizada sempre tem um parâmetro act como chave. No exemplo de código mencionado acima, algumas ações podem ter outros pares de chave-valor. Por exemplo, act=report_crash aceita estas chaves adicionais: accident_type e road_direction.

A chave accident_type pode aceitar dois valores: minor e major.

Observação: outros parâmetros são opcionais e podem não estar presentes em todas as respostas de intent.

Valores possíveis

A tabela lista os valores possíveis que o Gemini pode transmitir como a ação que o usuário está tentando realizar no app de navegação.

Observação: se o app oferecer suporte apenas a um subconjunto dessas ações, ele precisará informar ao usuário sempre que uma ação não compatível for solicitada.

Valor	Descrição	Chaves de parâmetro opcionais	Valores de parâmetros opcionais
allow_ferries	Mude a preferência de rota para permitir balsas.
allow_highways	Mude a preferência de rota para permitir rodovias.
allow_tolls	Mude a preferência de rota para permitir pedágios.
avoid_ferries	Mude a preferência de trajeto para evitar balsas.
avoid_highways	Mude a preferência de rota para evitar rodovias.
avoid_tolls	Mude a preferência de trajeto para evitar pedágios.
distance_to_destination	Mostrar a distância até o destino.
distance_to_next_turn	Mostrar a distância até a próxima instrução.
eta	Mostrar a HEC para o destino.
exit_navigation	Sair ou cancelar a navegação.
follow_mode	Mude a visualização do mapa para o modo de acompanhamento.
go_back	Voltar à ação anterior no mapa.
hide_satellite	Mude a configuração do mapa para ocultar as informações de satélite.
hide_traffic	Mude a configuração do mapa para ocultar as informações de trânsito.
mute	Desativar a orientação por voz.
query_current_road	Mostra a via em que o usuário está.
query_destination	Mostrar qual é o destino.
query_next_turn	Mostrar qual é a próxima rua.
report_crash	Alertar sobre acidentes.	accident_type	minor
			major
		road_direction	this_side
			other_side
report_hazard	Denunciar perigos.	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	Denunciar atividades policiais.	road_direction	this_side
			other_side
report_road_closure	Alertar sobre vias interditadas.	road_closure_type	partial
			full
report_traffic	Alertar sobre trânsito.	traffic_type	moderate
			heavy
			standstill
		road_direction	this_side
			other_side
route_overview	Mostrar panorama do trajeto.
show_alternates	Mostrar rotas alternativas.
show_directions_list	Mostrar instruções de navegação guiada.
show_satellite	Mostrar informações de satélite no mapa.
show_traffic	Mostrar trânsito no mapa.
time_to_destination	Mostrar HEC até o destino.
time_to_next_turn	Mostrar a ETA até a próxima conversão.
unmute	Ative a orientação por voz.

Recuperar status de navegação

Para garantir que o Gemini possa fornecer informações precisas e em tempo real ao usuário quando ele perguntar sobre o status da viagem, seu app precisa fornecer metadados de navegação usando o serviço de carro NavigationManager. Para orientações de implementação, consulte Comunicar metadados de navegação.