Cómo extender una app para Android a Asistente de Google con Acciones en apps (nivel 2)

1. Descripción general

Si necesitas expandir el alcance de tu app para Android, las Acciones en apps permiten que los usuarios inicien funciones específicas de esa app directamente con el Asistente de Google. Como desarrollador de Android, puedes implementar funciones que informen al Asistente de Google el tipo de funcionalidad que tienen a disposición los usuarios, incluida la forma en que deseas que se lleven a cabo las solicitudes relacionadas.

En el primer codelab de Acciones en apps, aprendiste a implementar el Asistente de Google en una app de fitness de ejemplo configurando intents integrados (BII) de la categoría Salud y fitness. Los BII se organizan en categorías que representan los tipos de tareas que los usuarios suelen pedirle al Asistente para que las ejecute.

Término clave: En el Asistente, un intent integrado, o BII, es un activador predefinido de un tipo específico de funcionalidad que el usuario desea utilizar. Google compila y mantiene los modelos de lenguaje de los BII para interpretar una amplia variedad de consultas que se relacionan con cada intent determinado.

En este codelab, aprenderás a agregar Acciones en apps. Para ello, utilizarás una app en la que tendrás que configurar BII de la categoría "Comunes", que representa las tareas comunes que puede realizar prácticamente cualquier app para Android.

Este codelab abarca conceptos de nivel intermedio para el desarrollo con Acciones en apps. Es necesario que tengas experiencia previa en el desarrollo de apps para Android y la implementación de intents de Android.

Qué compilarás

En este codelab, agregarás dos BII comunes a una app de ejemplo de listas de tareas pendientes para que los usuarios puedan pedirle al Asistente lo siguiente:

• Navegar a funciones de la app (con el BII actions.intent.OPEN_APP_FEATURE)
• Buscar contenido mediante la función de búsqueda de la app (con el BII actions.intent.GET_THING)

Nota: Para poder implementar el BII actions.intent.GET_THING se requiere que las apps cuenten con una función de búsqueda. Obtén más información sobre los requisitos de implementación de Acciones en apps.

Figura 1: Tres pantallas progresivas en las que el Asistente de Google muestra tareas activas en una app

Qué aprenderás

Aprenderás a usar los BII de la categoría Comunes para implementar el Asistente en la mayoría de las apps para Android. También aprenderás a probar los BII comunes con el complemento Google Assistant de Android Studio.

Requisitos previos

• Una terminal para ejecutar comandos de shell con Git instalado
• La versión estable más reciente de Android Studio
• Un dispositivo Android físico o virtual con acceso a Internet que permita ingresar a Google Play Store para probar tus acciones
• Debes acceder a Android Studio, así como a la app de Google y la app del Asistente de Google en tu dispositivo de prueba, utilizando la misma Cuenta de Google

Nota: Las Acciones en apps que se describen en este codelab se pueden probar con el Asistente de Google en una cantidad limitada de configuraciones regionales. Consulta los documentos de referencia de BII comunes para saber qué intents están disponibles en cada configuración regional.

En este codelab, usarás un dispositivo Android (físico o virtual) para probar tus acciones. Si usas un dispositivo físico, asegúrate de que esté conectado a tu máquina de desarrollo local. También debes acceder a la app de Google en el dispositivo y a Android Studio con la misma Cuenta de Google. La app del Asistente de Google también tiene que estar instalada en ese dispositivo.

2. Comprende el funcionamiento

Las Acciones en apps conectan a los usuarios del Asistente de Google con tu app para Android. Pero ¿cómo funcionan?

Cuando un usuario le indica al Asistente que quiere usar tu app, el Asistente busca en un archivo shortcuts.xml Acciones en apps que estén registradas para esa app. Ese archivo contiene las funciones de la app, con las que se vincula un intent integrado o personalizado del Asistente a un vínculo directo o intent de Android.

Término clave: Las funciones son plantillas que defines en shortcuts.xml para declarar los tipos de acciones que los usuarios pueden ejecutar para iniciar tu app y pasar a una tarea específica directamente. Para conocer los detalles, consulta la documentación de Android sobre las funciones.

Cuando un usuario le hace una consulta al Asistente, este analiza la entrada del usuario y busca la coincidencia con un intent de Acciones en apps (en este codelab, será un BII). El Asistente sabe qué funciones admites por la información del archivo shortcuts.xml en tu app para Android. Con la coincidencia de intents, la función con ese BII indicará la forma en que deseas que se lleve a cabo la solicitud. En este codelab, la entrega es un intent de Android que inicia una actividad en tu app.

En el siguiente diagrama se muestra el flujo mencionado del Asistente:

Figura 2: Un flujo que describe cómo el Asistente de Google procesa una consulta por voz

El archivo de proyecto shortcuts.xml contiene la siguiente información de cada Acción en la app:

• Qué intent integrado o personalizado utiliza la Acción en la app
• Qué vínculo directo o actividad de Android se le debe proporcionar al usuario
• Cómo se relacionan los parámetros del intent integrado con la información que el usuario le proporciona al Asistente

Luego, tu actividad de Android filtra y procesa el vínculo directo o intent de Android proporcionado para brindarle al usuario la funcionalidad deseada. El resultado es una experiencia del usuario en la que el Asistente invoca funciones de tu app para responder a una consulta del usuario.

3. Prepara tu entorno de desarrollo

En este codelab se utiliza la app de ejemplo de listas de tareas pendientes para Android. En particular, la app de ejemplo permite agregar tareas a esas listas, buscar tareas por categoría y ver información sobre las tareas completadas.

Descarga los archivos fundamentales

Ejecuta el siguiente comando para clonar el repositorio de GitHub de la app de ejemplo:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

Una vez que hayas clonado el repositorio, sigue estos pasos para abrirlo en Android Studio:

1. En el diálogo Welcome to Android Studio, haz clic en Import project.
2. Busca y selecciona la carpeta donde clonaste el repositorio.

Para ver una versión de la app que represente el codelab completado, clona el repositorio de la app de ejemplo con el parámetro --branch master.

Actualiza el ID de aplicación para Android

La actualización del ID de aplicación identifica de forma exclusiva la app en tu dispositivo de prueba y evita que se muestre el error "Duplicate package name" si la app se sube a Play Console. Para actualizar el ID de aplicación, abre app/build.gradle:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

Reemplaza "MYUNIQUENAME" en el campo applicationId por algo que sea único para ti.

Nota: Después de actualizar applicationId, recibirás la advertencia "Gradle files have changed since last project sync…" en Android Studio. Haz clic en Sync Now para evitar problemas cuando subas tu app.

Prueba la app en tu dispositivo

Antes de realizar más cambios en la app, es conveniente ejecutarla en tu emulador para tener una idea de lo que puede hacer la app de ejemplo. Para ello, sigue estos pasos:

1. En Android Studio, selecciona Run > Run app, o haz clic en Run en la barra de herramientas.
2. En el diálogo Select Deployment Target, selecciona un dispositivo y haz clic en OK. La versión de SO recomendada es Android 10 (nivel de API 30) o posterior, aunque las Acciones se pueden ejecutar en dispositivos que tengan hasta la versión Android 5 (nivel de API 21).
3. Mantén presionado el botón de inicio para configurar el Asistente y verificar que funcione. Si aún no lo hiciste, tendrás que acceder al Asistente en tu dispositivo.

Para obtener más información sobre los dispositivos virtuales de Android, consulta Cómo crear y administrar dispositivos virtuales.

Figura 3: Una animación que muestra la app de ejemplo de listas de tareas pendientes

Explora la app brevemente para ver lo que puede hacer. Si presionas el ícono de signo más, puedes crear una tarea nueva. Además, los elementos de menú en la esquina superior derecha te permiten buscar y filtrar tareas por estado de finalización.

Instala el complemento de prueba

El complemento Google Assistant te permite probar tus Acciones en apps en un dispositivo de prueba. Si aún no tienes la herramienta de prueba, instálala siguiendo estos pasos:

1. Ve a File > Settings (Android Studio > Preferences en MacOS).
2. En la sección Plugins, ve a Marketplace y busca "Google Assistant". También puedes descargar e instalar la herramienta de prueba manualmente.
   • Si no encuentras el complemento en Marketplace, descárgalo manualmente y sigue las instrucciones que se indican en Install the plugin from disk.
3. Instala la herramienta y reinicia Android Studio.

Nota: El complemento de prueba envía información al Asistente por medio de la app de Google de tu dispositivo Android.

4. Agrega la función de BII Get Thing

El BII actions.intent.GET_THING extiende la función de búsqueda de tu app al Asistente de Google. En este paso, implementarás y probarás el BII GET_THING para permitir que los usuarios busquen tareas específicas en la app de ejemplo.

Nota: El BII GET_THING se usa para buscar contenido o entidades con la función de búsqueda predeterminada de una app. Específicamente, propaga los criterios de búsqueda con el nombre de contenido o entidad mediante el parámetro de intent thing.name y presenta al usuario los resultados de la búsqueda más relevantes.

Define la función Get Thing

Durante una Acción en la app relacionada con una búsqueda, el Asistente extrae términos de búsqueda de la consulta del usuario y los agrega al parámetro de BII thing.name con el fin de pasarle el valor correspondiente a la aplicación para Android.

Para agregar el BII GET_THING a tu app, actualiza el archivo shortcuts.xml, ubicado en el directorio del proyecto de ejemplo (app/src/main/res/xml), con un elemento <capability> dentro de la etiqueta <shortcuts> de nivel superior:

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

La configuración anterior:

1. Declara que la app responde al BII GET_THING.
2. Especifica cómo compilar un intent de Android que inicia la app en respuesta a ese BII.
   • La actividad se identifica mediante targetPackage y targetClass.
   • El parámetro de BII thing.name se asigna al valor Extra de intent denominado q.

La actividad designada debe estar presente en el manifiesto de la app y se debe exportar.

La aplicación para Android proporcionada contiene metadatos, por lo que AndroidManifest reconoce el archivo shortcuts.xml:

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

Prueba tu Acción en la app

Para probar la búsqueda en tu app desde el Asistente, sigue estos pasos:

1. Asegúrate de que tu dispositivo Android esté conectado.
2. Ve a Tools > Google Assistant > App Actions Test Tool.
3. Haz clic en Create Preview para aceptar los valores predeterminados que se muestran en App name y Locale. Si se te solicita, revisa y acepta las políticas y las Condiciones del Servicio de Acciones en apps.
4. En el primer paso, en el que la herramienta te solicita que elijas y configures un BII, selecciona actions.intent.GET_THING. Cambia el valor name de running shoes a milk.
5. Haz clic en Run App Action.

En esta prueba, el BII GET_THING usa el atributo name para buscar en la app tareas que contengan "milk". Al igual que con la Acción en la app anterior, puedes probar tu acción con la herramienta de prueba, o simplemente decir "Hey Google, busca ingredientes para pastel en Lista de Tareas", o bien otras frases de búsqueda, en tu dispositivo de prueba.

Sugerencia: Consulta la guía de solución de problemas si tienes algún inconveniente al ejecutar la herramienta de prueba.

5. Agrega la función de BII Open app feature

En este paso, implementarás BII Open app feature para que los usuarios puedan usar el Asistente para ver sus tareas activas y completadas. Para ello, tendrás que completar la función en el archivo shortcuts.xml, que contiene información sobre cómo se activa esa función, cómo se pasan los parámetros y qué intents de Android se deben invocar. En este codelab, utilizarás el BII OPEN_APP_FEATURE. Después de implementar este BII, podrás probar la Acción en tu dispositivo.

Nota: Este BII inicia una función de la app. Se trata de un intent particularmente útil para ayudar a los usuarios a navegar hacia funciones de tu app que podrían no ser fáciles de encontrar de otra manera o incluso requerir que presionen varias veces para acceder a ellas. Debes especificar el inventario intercalado para el parámetro feature.

Agrega la función Open app feature

Agrega una segunda función para Open app feature en el archivo shortcuts.xml, debajo del elemento de función Get Thing:

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

Esta función asigna conjuntamente el BII Open app feature y el intent de Android, de modo que este último se active cuando lo haga el primero.

Antes de que se active el intent de Android, los parámetros admitidos se extraen de la entrada del usuario. El BII OPEN_APP_FEATURE admite un solo parámetro, feature, que representa la función de la app que se extrae de la consulta del usuario. Esta aplicación admitirá dos tipos de funciones: tarea activa y tarea completada. Estas funciones permiten que los usuarios abran la app con una vista filtrada de su lista de tareas. Para ofrecer ambas funciones, tienes que utilizar un inventario intercalado.

Término clave: Un inventario intercalado guía la extracción de entidades para los BII, ya que proporciona, a un parámetro de BII que admite ese tipo de inventario, un conjunto de entidades que es inteligible para una app. Si deseas obtener información detallada, consulta Inventario intercalado para Acciones en apps.

Controla los parámetros de intent con un inventario intercalado

Los parámetros de intent representan los elementos extraídos de una consulta del usuario. Por ejemplo, si un usuario dice algo como "Hey Google, pide una pizza en App de Ejemplo", el Asistente extraerá "pizza" y lo agregará a un parámetro de intent food.item de schema.org para pasárselo a tu acción con el fin de que lo procese.

El BII Open app feature admite un solo parámetro, feature, que representa la función de la app que se extrae de la consulta del usuario. Este parámetro requiere el uso de un inventario intercalado para que el Asistente disponga de un conjunto de nombres de función admitidos de la app y pueda establecer una coincidencia con el valor del parámetro.

Para controlar el parámetro de intent feature, agrega un atajo a tu archivo shortcuts.xml con el siguiente código arriba de la función Open app feature:

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

En el código anterior, definiste un inventario intercalado, representado por los elementos shortcut, con vinculaciones de funciones y parámetros. En los parámetros de BII se pueden usar atajos como inventario. El Asistente de Google busca una coincidencia entre la consulta del usuario y los valores de la vinculación de parámetros de los atajos. Si hay una coincidencia con el valor del parámetro, el shortcutId se agregará al intent de entrega. Cuando la solicitud de un usuario activa el BII OPEN_APP_FEATURE, el Asistente establece la coincidencia del valor del parámetro feature con el atributo de valor de un atajo, por lo que pasa el valor a targetClass como parameter en Extra.

Por ejemplo, si un usuario dice algo como "Hey Google, muéstrame mis tareas completadas en App de Ejemplo", el Asistente buscará coincidencias entre el valor del parámetro feature del intent, "tareas completadas", y el atajo del inventario correspondiente, que pasa ese valor a la función OPEN_APP_FEATURE. Luego, el Asistente activará el intent de Android.

Prueba tu Acción en la app

Durante las etapas de desarrollo y prueba, puedes utilizar el complemento Google Assistant para obtener una vista previa de tu Acción en la app con el Asistente en un dispositivo de prueba. También puedes usar la herramienta para ajustar los parámetros de intent de una Acción en la app y probar cómo tu acción procesa las diferentes maneras en que un usuario podría pedirle al Asistente que la ejecute.

Para probar tu Acción en la app con la herramienta de prueba, sigue estos pasos:

1. Conecta tu dispositivo físico Android de prueba, o inicia Android Emulator.
2. Si no ves la herramienta de prueba, ábrela accediendo a Tools > Google Assistant > App Actions Test Tool.
3. Haz clic en el botón Update para actualizar la vista previa.
4. En el primer paso, en el que la herramienta te solicita que elijas y configures un BII, selecciona actions.intent.OPEN_APP_FEATURE.
5. En el cuadro feature, actualiza el valor predeterminado History con Completed tasks.
6. Haz clic en Run App Action.

Sugerencia: Consulta la guía de solución de problemas si tienes algún inconveniente al ejecutar la herramienta de prueba.

Como alternativa, para probar la Acción en la app puedes usar el nombre de invocación directamente en la app del Asistente de tu dispositivo. Por ejemplo, podrías decir "Hey Google, muestra las tareas completadas en Lista de Tareas".

6. Próximos pasos

¡Felicitaciones!

Ahora sabes cómo configurar prácticamente cualquier app para Android con BII comunes de forma tal que funcionen con el Asistente de Google.

Temas abordados

En este codelab, aprendiste lo siguiente:

• Cómo permitir que los usuarios utilicen directamente funciones específicas de una app por medio del Asistente
• Cómo pueden acceder los usuarios a la función de búsqueda de una app desde el Asistente
• Cómo probar los BII comunes con el complemento Google Assistant

¿Qué sigue?

De ahora en adelante, puedes definir mejor tu app de listas de tareas pendientes. Para consultar el proyecto finalizado, accede al repositorio de la rama –master en GitHub.

A continuación, se presentan algunas sugerencias para adquirir más conocimientos sobre cómo configurar esta app con Acciones en apps:

• Para aprender a hacer un seguimiento del rendimiento de tus Acciones en apps, consulta el ejemplo de listas de tareas pendientes con Google Analytics para Firebase.
• Consulta la referencia de intents integrados de Acciones en apps para descubrir otras maneras de implementar el Asistente en tus apps.

Para continuar tu recorrido de Actions on Google, explora estos recursos:

• developers.google.com/assistant (sitio de documentación oficial sobre Actions on Google)
• Índice de muestra de Acciones en apps (apps de ejemplo y código de muestra para explorar las funciones de Acciones en apps)
• Repositorio de Actions on Google en GitHub (código de muestra y bibliotecas)
• r/GoogleAssistantDev (comunidad oficial de Reddit para desarrolladores que trabajan con el Asistente de Google)

Síguenos en Twitter (@ActionsOnGoogle) para mantenerte al tanto de nuestros anuncios más recientes y utiliza #AoGDevs para compartir tus compilaciones.

Encuesta de comentarios

Por último, completa esta encuesta para enviarnos comentarios sobre tu experiencia con este codelab.