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

En el primer codelab de Acciones en apps, aprendiste a extender Asistente de Google a una app de fitness de ejemplo implementando intents incorporados (BII) de la categoría de intents de salud y bienestar. Los BII se organizan en categorías que representan los tipos de tareas que los usuarios suelen pedirle a Asistente.

En este codelab, aprenderás a agregar Acciones en apps a una app que usa BII de la categoría de intents comunes [Common BII category], que representa tareas comunes que prácticamente cualquier app para Android puede realizar.

Este codelab abarca conceptos de nivel intermedio para desarrollar con Acciones en apps. Necesitas experiencia previa con el desarrollo de apps para Android, la administración de vínculos directos, la creación de un recurso actions.xml y el uso del complemento App Actions Test Tool. Se recomienda que los desarrolladores que nunca trabajaron con Acciones en apps comiencen con el codelab anterior.

Qué compilarás

En este codelab, agregarás dos BII comunes a una app de ejemplo de lista de tareas que les permitirán a los usuarios solicitarle lo siguiente a Asistente:

Tres pantallas progresivas en las que Asistente de Google muestra las tareas activas en una app

Qué aprenderás

  • Cómo usar los BII comunes para extender el uso de Asistente a la mayoría de las apps para Android
  • Cómo probar los BII comunes con el complemento App Actions Test Tool

Requisitos previos

  • Una terminal para ejecutar comandos shell con git instalado
  • La versión estable más reciente de Android Studio
  • Una Cuenta de Google con acceso a Google Play Console
  • Un emulador o dispositivo Android con acceso a Google Play Store mediante Internet para probar las acciones

En este codelab, utilizarás un dispositivo Android (físico o un emulador) para probar las acciones. Si usas un dispositivo físico, asegúrate de que esté conectado a tu máquina de desarrollo. Además, debes acceder a Google app en el dispositivo (o el emulador) y a Android Studio con la misma Cuenta de Google. También debes instalar la app de Asistente de Google en el dispositivo.

Este codelab comienza con la app de ejemplo To-do list para Android. Los usuarios de esta app de ejemplo podrán agregar elementos a listas de tareas, buscar elementos por categorías y ver información sobre tareas completadas.

Descarga los archivos de base

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

Cuando hayas clonado el repositorio, ábrelo en Android Studio de esta manera:

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

Para ver una versión de la app To-do list en la que se representa el codelab terminado, debes clonar el repositorio de la app de ejemplo con la marca --branch master.

Cambia el ID de aplicación para Android a fin de habilitar las pruebas

Más adelante en este codelab, usarás la herramienta de pruebas de Acciones en apps para probar tus acciones en un emulador o dispositivo Android. La herramienta requiere que primero subas tu app a un proyecto de Google Play Console para poder ejecutarse. A fin de evitar que se produzca un error por duplicación de nombre del proyecto cuando subes la app a Play Console, debes cambiar el applicationId de la app de ejemplo a uno único para ti.

En app/build.gradle, actualiza el valor de applicationId "com.example.myapp" a un ID único, como "com.codelabs.myname". Si quieres obtener ayuda para determinar un ID de aplicación, visita la página de referencia de Android.

build.gradle

android {
...
    defaultConfig {
        // This ID uniquely identifies your app on the device and in Google Play Store
        applicationId "com.example.myapp"
    ...
    }
}

Después de actualizar applicationId, es posible que veas un cuadro de advertencia amarillo en el IDE etiquetado "Gradle files have changed since last project sync…" (los archivos de Gradle cambiaron desde la última sincronización del proyecto). En ese caso, haz clic en Sync now, en el cuadro, para evitar problemas que podrían ocurrir cuando subes tu app a Play Console.

Prueba la app en tu dispositivo

Antes de realizar más cambios en la app, te recomendamos que la ejecutes en un emulador para tener una idea de lo que puede hacer la app de ejemplo. Para ello, haz lo siguiente:

  • En Android Studio, selecciona Run > Run app o haz clic en Run , en la barra de herramientas.
  • En el diálogo "Select Deployment Target", selecciona un dispositivo virtual y haz clic en "OK". La versión de SO recomendada es Android 10 (nivel de API 30) o una posterior, aunque las acciones se pueden ejecutar hasta la versión Android 5 (nivel de API 21).

Para configurar y verificar que Asistente funcione en tu dispositivo, mantén presionado el botón de inicio. Si aún no lo hiciste, tendrás que acceder a Asistente en el dispositivo.

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

Animación que muestra cómo funciona la app de ejemplo To-do list

Explora la app brevemente para descubrir lo que puede hacer. Si tocas el ícono de signo más, se creará un nuevo elemento de tarea, y los elementos del menú en la parte superior derecha te permitirán buscar y filtrar elementos de tareas por estado de finalización.

Sube la app a Play Console

La carga de la app a un proyecto de Google Play Console es un requisito previo para usar la herramienta de pruebas de Acciones en apps en Android Studio. Compila tu app en Android Studio y súbela a Play Console como un borrador de versión interna.

Sigue estos pasos para compilar la app en Android Studio:

  1. Ve a Build > Generate Signed Bundle / APK.
  2. Selecciona "Android App Bundle" y haz clic en Next.
  3. Ingresa los detalles para firmar tu app y haz clic en Next.
  4. Selecciona la variante de compilación "prodRelease" y haz clic en Finish.

En Google Play Console, sube el paquete de aplicación que creaste como una app nueva. Para ello, sigue estos pasos:

  1. En la página Todas las apps, haz clic en Crear app.
  2. Asígnale el nombre que quieras a la app y haz clic en Crear app. Para este codelab, no necesitas completar la información de la app cuando la creas.
  3. Desde el menú de la barra lateral, ve a Pruebas y busca la página Pruebas internas.
  4. Haz clic en Crear una versión nueva, en la página Pruebas internas.
  5. Haz clic en Continuar a fin de aceptar la firma de apps de Google Play.
  6. En el panel Paquetes de aplicaciones y APK, sube el archivo AAB que generaste anteriormente (es probable que lo encuentres en el directorio app/prod/release). Haz clic en Guardar.

Instala el complemento de prueba

El complemento App Actions Test Tool te permite probar tus acciones para un solo usuario en un dispositivo de prueba. Si aún no tienes esta herramienta, instálala mediante estos pasos:

  1. Ve a File > Settings (Android Studio > Preferences en macOS).
  2. En la sección Plugins, ve a Marketplace y busca la herramienta "App Actions test tool". También puedes descargar e instalar la herramienta de pruebas manualmente.
  3. Instala la herramienta y reinicia Android Studio.

En este paso, implementarás el BII Open app feature, que les permite a los usuarios ver las tareas activas y las completadas mediante Asistente. Para ello, debes extender los vínculos directos existentes de la función para filtrar tareas a Asistente mediante la definición del BII en actions.xml. Habrás completado esta sección una vez que pruebes la acción en el dispositivo.

Antes de implementar tu BII, verifica que los vínculos directos existentes en tu app cumplan con el comportamiento de las Acciones en apps identificadas.

A fin de probar vínculos directos con la herramienta de línea de comandos Android Debug Bridge (adb), sigue estos pasos:

  1. Actualiza la app en el dispositivo.
  2. Presiona el botón para actualizar ubicado en la barra de la aplicación ampliada a fin de propagar la lista de tareas con elementos de ejemplo.

Menú ampliado de la barra de herramientas de la app de lista de tareas

Si aparece la opción para abrirla con Google, selecciona "Siempre" a fin de permitir que la app de tareas abra los vínculos admitidos. Puedes cambiar esta preferencia más tarde en la configuración de la app.

En la terminal, ingresa cada uno de los siguientes comandos adb a fin de probar los vínculos directos para filtrar tareas de la app:

Ver tareas activas

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/active-tasks"

Ver tareas completadas

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/completed-tasks"

Ver todas las tareas

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/all-tasks"

Los comandos anteriores sirven para abrir la función de vista de lista de la app, que muestra tareas filtradas por el estado de progreso especificado en cada ruta de acceso final de los vínculos directos.

Agrega el intent integrado

A fin de extender los vínculos directos de filtro de tareas a Asistente de Google, define un BII Open app feature, configurado para abrir estos vínculos, en actions.xml.

Para definir el BII, actualiza actions.xml, que se encuentra en el directorio del proyecto de ejemplo app/src/main/res/xml, con el siguiente código:

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        //TODO: Handle intent parameters

        //TODO: Handle action fulfillment

    </action>
</actions>

Administra los parámetros de intents con inventario intercalado

Los parámetros de intents representan los elementos que se extraen de la consulta de un usuario. Por ejemplo, si un usuario dice "Hey Google, pide una pizza en AppdeEjemplo", Asistente extrae el elemento "pizza" y lo importa en un parámetro de intent food.item de schema.org para pasarlo a tu acción y que esta lo procese.

El BII Open app feature admite un parámetro (feature) que representa la función de la app extraída de la consulta del usuario. Para usar este parámetro, se requiere un inventario intercalado, lo que le proporciona a Asistente un conjunto de nombres de funciones de apps admitidas a los que se puede asociar el valor del parámetro.

Para procesar el parámetro de intent feature, actualiza actions.xml con el siguiente código:

actions.xml

<?xml version="1.0" encoding="utf-8"?>

<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        <parameter name="feature">
            <entity-set-reference entitySetId="FeatureEntitySet" />
        </parameter>

        //TODO: Handle action fulfillment

    </action>
</actions>

Con el código anterior, le solicitaste a Asistente que asociara valores de parámetros de función a un inventario intercalado (FeatureEntitySet), que se define como entity-set-reference en la etiqueta del parámetro.

Agrega el siguiente entity-set a actions.xml, debajo del elemento action para definir el inventario intercalado de tu BII:

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action>
       ...
    </action>

    <entity-set entitySetId="FeatureEntitySet">
        <entity  url="https://todo.androidappactions.com/completed-tasks"
            name="completed tasks" alternateName="@array/completed_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/active-tasks"
            name="active tasks" alternateName="@array/active_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/all-tasks"
            name="all tasks" alternateName="@array/all_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/statistics"
            name="statistics" alternateName="@array/statistics_synonyms"/>
    </entity-set>
</actions>

En el código anterior, definiste un inventario intercalado representado como un elemento entity-set que contiene cuatro elementos entity. Cuando un usuario activa este BII con una solicitud, Asistente asocia el valor del parámetro feature al atributo name de una entity pasando la url de una entity coincidente a tu entrega.

Por ejemplo, si un usuario dice "Hey Google, muéstrame mis tareas completadas en AppdeEjemplo", Asistente asociará el valor del parámetro de intent feature "tareas completadas" a la entity de inventario correspondiente. Luego, Asistente pasará la URL asociada (https://todo.androidappactions.com/completed-tasks) a tu entrega.

Define la entrega de acciones

Para entregar una acción, debes definir un elemento fulfillment en actions.xml para procesar la URL que pasa Asistente. Agrega una fulfillment a tu action con el siguiente código:

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        ... //Parameter definition

        <fulfillment urlTemplate="{@url}"/>
        <fulfillment urlTemplate="https://todo.androidappactions.com/all-tasks"/>

    </action>
   ...
</actions>

Con el ejemplo anterior, definiste dos elementos fulfillment. El primero activa el vínculo directo que generó Asistente con el parámetro feature, representado como un marcador de posición {@url} en el atributo urlTemplate. El segundo elemento fulfillment es un resguardo que abre una vista de tareas, que muestra una lista de tareas no filtradas, para situaciones en las que falta el parámetro feature o cuando no se encuentra un element del inventario intercalado coincidente.

Prueba tu Acción en la app

Durante las etapas de desarrollo y prueba, usas la herramienta de pruebas de Acciones en apps a fin de obtener una vista previa de tu Acción en la app con Asistente en un dispositivo de prueba. También puedes usar la herramienta para ajustar los parámetros de intents de una Acción en la app, con el fin de probar la forma en que tu acción procesa las diferentes maneras en que un usuario puede pedirle a Asistente que la ejecute.

Sigue estos pasos a fin de probar tu acción en la app con la herramienta de pruebas:

  1. Conecta tu dispositivo de prueba físico de Android o inicia Android Emulator.
  2. Ve a Tools > App Actions > App Actions Test Tool. Es posible que debas acceder a Android Studio. Usa la misma cuenta que usaste antes con Google Play Console.
  3. En el campo Invocation Name, ingresa "Task List".
  4. Si el idioma de Asistente no es "English (en)", ingresa la configuración regional que coincida con el idioma de Asistente en el campo "Locale".
  5. Haz clic en Create Preview.
  6. En la lista desplegable Configure, selecciona el intent actions.intent.OPEN_APP_FEATURE.
  7. En el cuadro feature, actualiza el valor "History" predeterminado con las "Completed tasks".
  8. Haz clic en "Run".

De manera alternativa, puedes usar el nombre de invocación en la app de Asistente desde tu dispositivo para probar la Acción en la app. Por ejemplo, puedes decir "Hey Google, show completed tasks in Task List" (muestra las tareas completadas en la Lista de tareas).

El BII Get thing extiende la funcionalidad de búsqueda en tu app a Asistente de Google. En este paso, implementarás y probarás el BII Get thing, que les permite a los usuarios buscar tareas específicas en la app de ejemplo.

La app de ejemplo tiene un vínculo directo existente para la funcionalidad de búsqueda en la app. Antes de implementar tu BII, usa adb para verificar que este vínculo directo cumpla con el comportamiento de las Acciones en apps identificadas.

Prueba el vínculo directo de búsqueda con este comando adb:

# GET_THING deep link: in-app search
adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/search?q=milk"

El comando anterior activa un vínculo directo que carga la actividad de la lista de elementos filtrada para mostrar elementos que contengan la búsqueda "home".

Agrega el intent integrado

Durante una Acción en la app relacionada con una búsqueda, Asistente extrae términos de búsqueda de la consulta del usuario y los importa en un parámetro de intent thing.name. Luego, Asistente mapea el parámetro a una plantilla de URL que defines en un elemento fulfillment para generar una URL de entrega.

A fin de definir el BBI Get thing en tu app, debes actualizar actions.xml con esta acción nueva:

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
   <action intentName="actions.intent.OPEN_APP_FEATURE">...</action>

   <action intentName="actions.intent.GET_THING">

        <parameter-mapping
                intentParameter="thing.name"
                urlParameter="q"/>

        <fulfillment urlTemplate="https://todo.androidappactions.com/search?q={q}">
        </fulfillment>

   </action>

   ...
</actions>

En el ejemplo anterior, el elemento parameter-mapping asigna el parámetro de intent thing.name al valor "q" del atributo urlParameter del elemento fulfillment. Luego, Asistente mapea el valor urlParameter al marcador de posición "{q}" en la urlTemplate de fulfillment para generar el vínculo directo.

Prueba tu Acción en la app

Sigue estos pasos para probar la búsqueda en la app de tu app desde Asistente:

  1. Conecta tu dispositivo de prueba físico de Android o inicia Android Emulator.
  2. Ve a Tools > App Actions > App Actions Test Tool.
  3. Haz clic en Update Preview.
  4. En la lista desplegable "Configure", selecciona el intent actions.intent.GET_THING. Cambia el valor "name" de "running shoes" a "milk".
  5. Haz clic en Run.

En esta prueba, el BII Get thing usa el atributo name para buscar en la app tareas que contengan el término "home". Al igual que con la Acción en la app anterior, puedes probar tu acción con la herramienta correspondiente o decir "Hey Google, search for cake mix in Task List" (busca premezcla de torta en la Lista de tareas), u otras frases de búsqueda, en tu dispositivo de prueba.

Felicitaciones.

Ahora puedes permitir que casi cualquier aplicación para Android funcione con Asistente de Google mediante el uso de BII comunes.

Temas abordados

En este codelab, aprendiste lo siguiente:

  • Cómo permitir que los usuarios exploren en detalle funciones específicas de una app con Asistente
  • Cómo los usuarios pueden acceder a la búsqueda desde una app con Asistente
  • Cómo probar BII comunes con la herramienta de pruebas de Acciones en apps

¿Cuáles son los pasos siguientes?

A partir de ahora, puedes probar más ajustes en tu app de lista de tareas. Para hacer referencia al proyecto finalizado, consulta el repositorio –master branch en GitHub.

Estas son algunas sugerencias para descubrir más sobre el alcance extendido de esta app con Acciones en apps:

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

Síguenos en Twitter (@ActionsOnGoogle) para mantenerte al tanto de los anuncios más recientes y enviar tuits con #AoGDevs para compartir tu compilación.

Encuesta de opinión

Por último, completa esta encuesta a fin de enviar comentarios sobre tu experiencia con este codelab.