Cómo implementar intents de apps de navegación

Gemini usa tres formatos diferentes de intents que tu app de navegación puede admitir. Para lograr la interoperabilidad y la integración de tu app y Gemini, declara los filtros de intents que se detallan en esta página en el manifiesto de tu app. Para obtener más información sobre las intenciones, consulta Intent.

La clase Intent de la app de navegación de Gemini admite los siguientes intents:

• Intent de navegación
• Intención de búsqueda
• Intent de acción personalizada

Nota: No es obligatorio que admitas las tres acciones para la interoperabilidad, pero te recomendamos que las admitas todas para brindar una experiencia del usuario completa.

Figura 1: Flujo de datos del intent.

Parámetros en los datos de intents

Los datos del intent siguen un formato de URI que contiene parámetros basados en el intent que pasas. Algunos parámetros siempre se proporcionan en los datos. Esto significa que siempre tendrán un valor explícito. Sin embargo, los parámetros opcionales no siempre tienen un valor establecido en los datos. Para obtener más información, consulta Prueba de datos.

Intents sin conexión

Todas las intents que se indican en esta página tienen sus variantes sin conexión disponibles. Puedes distinguirlos agregando .offline a su esquema. Por ejemplo, el intent de navegación usa el esquema geo.offline. Estos filtros de intents en el manifiesto indican la capacidad de la app para admitir estas acciones sin conexión.

Intent de navegación

Usa un intent de navegación para satisfacer la solicitud de un usuario de navegar a un destino específico. Este destino puede ser una sola ubicación (dirección) o varias ubicaciones (por ejemplo, cafeterías y gasolineras). Los datos de intención siguen un formato de URI especificado para cada intención.

Formato del intent

La clase Intent usa el siguiente formato para el intent de la app de navegación:

Categoría: android.intent.category.DEFAULT

Acción:

• Android Auto y SO Android Automotive: androidx.car.app.action.NAVIGATE
• Otros factores de forma: android.intent.action.NAVIGATE

Esquema: geo

Ejemplos:

• 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

Comportamiento sugerido de la app: Se inicia la navegación a la ubicación especificada o se le pide al usuario que elija entre varias opciones.

Filtros de intents del manifiesto

Declara el siguiente formato de intent en el archivo de manifiesto de tu app para que Gemini sepa que tu app de navegación puede recibir intents de navegación.

Todos los factores de forma, excepto Android Auto y el SO Android Automotive:

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

Android Auto y SO Android Automotive:

<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 proporcionados

Se espera que los siguientes parámetros estén disponibles en los datos del intent de la app de navegación proporcionada.

Consulta de ubicación o coordenadas geográficas

Cada búsqueda de intent de navegación contiene uno o ambos de estos parámetros, según el tipo de datos solicitados:

• Búsqueda de ubicación

  Hace referencia a la ubicación a la que el usuario intenta navegar. Usa estos datos para resolver el destino del usuario.

  Clave del parámetro: q
  Valor: Es el destino que consultó el usuario.

  Ejemplo: geo:0,0?q=Golden+Gate+Bridge
  Interpretación: El usuario quiere navegar al puente Golden Gate.

• Coordenadas geográficas (latitud y longitud)

  Se refiere a las coordenadas específicas que usa el usuario para la navegación.

  Clave del parámetro: geo:lat,long
  Valor: Las coordenadas consultadas por el usuario.

  Ejemplo: geo:1.1,2.2?mode=w&intent=navigation
  Interpretación: El usuario quiere navegar a las coordenadas (1.1, 2.2).

Parámetros opcionales

En esta sección, se describen los parámetros opcionales que se proporcionan en los datos del intent de la app de navegación.

Intent

Define la intención del usuario. Si no se establece este parámetro, la intención del usuario predeterminada se considera como navigation.

Nota: Esta clase es diferente de la clase Intent disponible en Android.

Clave del parámetro: intent
Valores posibles:

• navigation [valor predeterminado]: Reemplaza el destino y comienza la navegación. Úsalo para consultas como Navegar a X.
• add_a_stop: Agrega la parada como el próximo destino junto con los destinos anteriores. Úsalo para búsquedas como agregar una parada en X.
• directions: Muestra las instrucciones de la ruta sin iniciar la navegación. Úsalo para búsquedas como cómo llegar a X.

Ejemplo: geo:47.61594547836694,-122.20373173098756?q=575+Bellevue+Square,+Bellevue,+WA+98004&intent=add_a_stop Interpretación: El usuario quiere agregar una parada en Bellevue Square, Bellevue, con las coordenadas actuales [47.6, -122.2].

Nota: Puedes usar el emulador del SO Android Automotive para probar estos intents.

Evitar

Define las cosas que se deben evitar en la navegación.

Clave del parámetro: avoid
Valores posibles:

• f, ferris
• h, autopistas
• t: Peajes

Ejemplo: geo:0,0?q=googleplex&avoid=tf
Interpretación: El usuario quiere navegar al Googleplex evitando peajes y ferris.

Medio de viaje

El modo de viaje representa el medio de transporte que especificó el usuario en la búsqueda.

Nota: Este modo se aplica a todos los factores de forma, excepto al SO Android Automotive.

Clave del parámetro: mode
Valores posibles:

• b: Bicicleta
• d, en auto
• x, taxi
• l: Vehículo motorizado de dos ruedas
• r: Transporte público
• w: Caminar

Ejemplo: geo:0,0?q=Googleplex&mode=r
Interpretación: El usuario quiere navegar al Googleplex en transporte público.

Entrada

Se usa para registrar la fuente de entrada.

Valores posibles: asistente

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

Intención de búsqueda

Usar una intención de búsqueda para buscar una consulta y mostrar varios resultados a lo largo de la ruta mientras conduces

Formato del intent

La clase Intent usa el siguiente formato para los intents de búsqueda:

Categoría: android.intent.category.DEFAULT

Acción: android.intent.action.VIEW

Esquema: geo

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

Comportamiento sugerido de la app: Abre una lista de ubicaciones que coincidan con la búsqueda del usuario.

Nota: La intención de la app de navegación y la intención de búsqueda tienen diferentes tipos de acción. La navegación es ACTION_NAVIGATE, mientras que la búsqueda es ACTION_VIEW, como se describe en los filtros de intents del manifiesto.

Filtros de intents del manifiesto

Declara el siguiente formato de intent en el archivo de manifiesto de tu app para que Gemini sepa que tu app de navegación puede recibir intents de búsqueda:

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

Parámetros proporcionados

Se espera que los siguientes parámetros estén disponibles en los datos de intención de búsqueda proporcionados.

Consulta de ubicación

Una búsqueda de ubicación es la ubicación que el usuario busca mientras conduce. Esta búsqueda puede ser imprecisa o a lo largo de una ruta de navegación activa.

Clave del parámetro: q
Valor: Es el término de búsqueda del usuario, que podría ser un tipo de ubicación, como cafetería o universidad, pero también podría tener cuantificadores, como cerca de mí o con la mejor calificación.

Ejemplo: geo:0,0?q=restaurants+nearby
Interpretación: El usuario quiere buscar restaurantes cercanos.

Intent de acción personalizada

Usa un intent personalizado para acciones personalizadas, como informar accidentes y finalizar la navegación. El tipo de acción principal se define con el parámetro de consulta act. Puedes establecer parámetros adicionales según el tipo de acción.

Formato del intent

La clase Intent usa el siguiente formato para el intent de acción personalizado:

Categoría: android.intent.category.DEFAULT

Acción: android.intent.action.VIEW

Esquema: geo.action

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

Filtros de intents del manifiesto

Declara el siguiente formato de intent en el archivo de manifiesto de tu app para que Gemini sepa que tu app de navegación puede recibir intents de acción personalizados.

<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 proporcionados

Se espera que los siguientes parámetros estén disponibles en los datos del intent de acción personalizada proporcionado:

Tipo de acción

Define el tipo de acción personalizada que un usuario desea realizar.

Clave del parámetro: act

Ejemplos:

• geo.action:?act=report_crash&accident_type=major
  Interpretación: El usuario quiere informar un accidente grave.

• geo.action:?act=mute
  Interpretación: El usuario quiere silenciar las instrucciones por voz.

• geo.action:?act=exit_navigation
  Interpretación: El usuario quiere salir de la navegación actual.

Comportamiento sugerido de la app: Cumple con la acción solicitada en la app de navegación o muestra un mensaje de acción no admitida.

En la siguiente figura, se muestra un ejemplo de pares clave-valor en la consulta de respuesta:

Figura 2: Flujo de datos de intents de acciones personalizadas.

Par clave-valor:

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

Cada acción personalizada siempre tiene un parámetro act como clave. En el código de ejemplo mencionado anteriormente, algunas acciones pueden tener pares clave-valor adicionales. Por ejemplo, act=report_crash admite estas claves adicionales: accident_type y road_direction.

La clave accident_type puede admitir dos valores: minor y major.

Nota: Los parámetros adicionales son opcionales y es posible que no estén presentes en todas las respuestas de intención.

Valores posibles

En la tabla, se enumeran los valores posibles que Gemini puede pasar como la acción que el usuario intenta completar en la app de navegación.

Nota: Si tu app solo admite un subconjunto de estas acciones, debe informar al usuario cada vez que solicite una acción no admitida.

Valor	Descripción	Claves de parámetros opcionales	Valores de parámetros opcionales
allow_ferries	Cambia la preferencia de ruta para permitir transbordadores.
allow_highways	Cambia la preferencia de ruta para permitir autopistas.
allow_tolls	Cambia la preferencia de ruta para permitir peajes.
avoid_ferries	Cambia la preferencia de ruta para evitar los transbordadores.
avoid_highways	Cambiar la preferencia de ruta para evitar autopistas
avoid_tolls	Cambia la preferencia de ruta para evitar los peajes.
distance_to_destination	Mostrar la distancia hasta el destino
distance_to_next_turn	Mostrar la distancia hasta el siguiente giro
eta	Mostrar la ETA al destino
exit_navigation	Salir de la navegación o cancelarla
follow_mode	Cambia la vista del mapa al modo de seguimiento.
go_back	Regresa a la acción anterior del mapa.
hide_satellite	Cambia el parámetro de configuración del mapa para ocultar la información satelital.
hide_traffic	Cambia la configuración del mapa para ocultar la información sobre el tráfico.
mute	Silencia las indicaciones por voz.
query_current_road	Mostrar la ruta actual en la que se encuentra el usuario
query_destination	Mostrar el destino
query_next_turn	Mostrar cuál es el próximo giro
report_crash	Avisar que hay accidentes automovilísticos	accident_type	minor
			major
		road_direction	this_side
			other_side
report_hazard	Informa peligros.	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	Avisar sobre actividad policial	road_direction	this_side
			other_side
report_road_closure	Informar sobre rutas cerradas	road_closure_type	partial
			full
report_traffic	Avisa sobre el tráfico.	traffic_type	moderate
			heavy
			standstill
		road_direction	this_side
			other_side
route_overview	Mostrar el resumen de la ruta
show_alternates	Mostrar rutas alternativas
show_directions_list	Mostrar instrucciones paso a paso
show_satellite	Mostrar información satelital en el mapa
show_traffic	Mostrar el tráfico en el mapa
time_to_destination	Mostrar la ETA al destino
time_to_next_turn	Mostrar la ETA para el próximo giro
unmute	Activar el sonido de las indicaciones por voz

Recupera el estado de navegación

Para garantizar que Gemini pueda proporcionar información precisa y en tiempo real al usuario cuando pregunte sobre el estado de su viaje, tu app debe proporcionar metadatos de navegación con el servicio de automóvil NavigationManager. Para obtener orientación sobre la implementación, consulta Cómo comunicar metadatos de navegación.