Intents integrados para Acciones en apps

Los intents integrados (BIIs) permiten que la app exprese sus capacidades de entrega a Google. Si declaras capacidades en el archivo shortcuts.xml y asignas parámetros de intent a la entrega, posibilitarás que Asistente de Google inicie la app en una pantalla específica, en respuesta a una pregunta, para permitir que el usuario complete una tarea.

Los intents integrados se agrupan según las categorías de apps. Cada categoría representa un conjunto de tareas comunes que los usuarios desean completar con frecuencia en sus apps. La lista completa de BIIs disponibles, sus parámetros y consultas de ejemplo que se pueden usar para realizar pruebas se encuentra en la referencia del intents integrados.

Muchos BIIs tienen recomendaciones y requisitos de implementación específicos. Estos requisitos y recomendaciones ayudan a que tu app ofrezca la mejor experiencia posible a los usuarios.

Figura 1: Invoca el BII START_EXERCISE BII con una pregunta de voz al Asistente.
Figura 2: Inicia la app en una pantalla específica para comenzar la tarea de START_EXERCISE.
Figura 3: Muestra un widget en respuesta a la pregunta.

Cómo implementar BIIs y controlar parámetros de intents

Para las Acciones en apps, debes declarar las capacidades y controlar los parámetros de BIIs en el archivo shortcuts.xml. Para implementar un BII y controlar sus parámetros, sigue estos pasos:

  1. Declara la capability con el BII elegido.
  2. Agrega elementos parameter anidados para cada campo de BII que desees agregar.
    1. Si usas targetClass o targetPackage, asígnalos al intent de Android extras con un nombre que elijas.
    2. Si usas una URL de vínculo directo, usa los parámetros con nombre en la cadena consulta de la plantilla de URL.

Para controlar un parámetro de BII, asígnalo al parámetro correspondiente de un intent de Android explícito en tu capability. De esa manera, puede usar su valor en tu app. No es necesario que tu app controle los parámetros de BII. Sin, intenta controlar los campos de datos marcados como "Recomendados" en la referencia del intent integrado.

Puedes definir varias entregas de intents, cada una con su propio conjunto de parámetros recomendados. Google selecciona la entrega adecuada según los parámetros de capacidad que identificó en la consulta del usuario y los que se declararon en un intent.

Por ejemplo, el intent actions.intent.START_EXERCISE recomienda que tu app controle el parámetro de BII exercise.name, pero puedes implementar el BII en tu app sin parámetros. Podrías hacerlo si quisieras controlar las consultas de los usuarios sin el nombre de ejercicio específico, como "Pídele a AppdeEjemplo que inicie el seguimiento del ejercicio."

El siguiente fragmento tiene un resguardo de una entrega sin parámetros obligatorios si los parámetros no se incluyen en la consulta del usuario:

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">

    <capability android:name="actions.intent.START_EXERCISE">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity1"
            android:targetPackage="com.example.myapplication">
            <parameter
                android:name="exercise.name"
                android:key="exerciseType"
                android:required="true"
                />
        </intent>
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity2">
        </intent>
    </capability>
</shortcuts>

Asistente de Google hace todo lo posible para brindar la información más relevante al usuario cuando muestra los valores de parámetros en tu app. Por ejemplo, las consultas de los usuarios para pedir pizza de la app para dispositivos móviles de RestaurantedeEjemplo no siempre incluyen una ubicación. Para brindar un mejor servicio al usuario, Asistente puede indicar los valores de latitud y longitud del RestaurantedeEjemplo más cercano a esa app.

Como requisito adicional, tu app no debería realizar directamente una acción que modifique el estado real del usuario (por ejemplo, transferir dinero, realizar un pedido o enviar un mensaje) sin confirmarlo primero con el usuario.

Desambiguación

Los argumentos que se pasan a tu app a través de <url-parameter> o intents adicionales no identifiquen de forma única el elemento que quieres mostrar al usuario. En ese caso, te recomendamos que uses el valor de argumento como argumento de búsqueda y lleves al usuario a la página de búsqueda de la app para que pueda desambiguar y elegir el elemento correcto.

Por ejemplo, si la consulta de un usuario es "Pedir a RestaurantedeEjemplo" para el BII ORDER_MENU_ITEM, puedes mostrarle una lista de restaurantes cuyos nombres coincidan el término "Example Restaurant".

Compatibilidad con idiomas y configuraciones regionales

Las configuraciones regionales que admiten el desarrollo y las pruebas de cada BII de Acciones en apps se enumeran en la referencia del intent integrado. Algunos BIIs tienen una compatibilidad de configuración regional diferente para las pruebas de desarrolladores y la activación de usuarios desde Asistente.