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

Las Acciones en apps te ayudan a extender el alcance de tu app para Android dado que permiten que los usuarios ejecuten contenido directamente en funciones de apps específicas desde Asistente de Google. Las Acciones en apps se compilan aparte de los vínculos directos de tu app, lo que proporciona a los usuarios más maneras de acceder a las funciones que ya quieren usar.

Como desarrollador de Android puedes implementar uno de los intents integrados disponibles para ayudar a los usuarios a realizar tareas más rápido y fácil.

Este codelab abarca conceptos de nivel intermedio para desarrollar contenido con Actions on Google. A fin de completar este codelab, necesitas experiencia previa con el desarrollo de apps para Android y la administración de vínculos directos. Aquellos desarrolladores que nunca trabajaron con Android, pueden comenzar con uno de los codelabs sobre aspectos básicos para desarrolladores de Android.

Qué compilarás

En este codelab, agregarás las siguientes funciones a una app de fitness de ejemplo para usar en Android:

  • Los usuarios pueden iniciar un temporizador de ejercicio en la app mediante Asistente de Google.
  • Los usuarios pueden detener el temporizador de ejercicio en la app mediante Asistente de Google.

Cuatro pantallas progresivas en las que Asistente de Google inicia un registro de carrera en una app

Qué aprenderás

  • Cómo determinar si las Acciones en apps son adecuadas para tu app de Android
  • Cómo conectar un intent integrado con una actividad de Android
  • Cómo obtener parámetros de las URL de vínculos directos para una app de Android desde Asistente
  • Cómo usar inventario intercalado para mapear identificadores a funcionalidades de la app
  • Cómo probar las Acciones en apps en Android Studio

Requisitos

Antes de continuar, asegúrate de contar con estas herramientas en tu entorno:

  • Una terminal para ejecutar comandos shell con git instalado
  • La versión más reciente de Android Studio
  • Una Cuenta de Google con acceso a Google Play Console
  • Un dispositivo Android físico en el que se puedan probar tus Acciones en apps

Se recomienda familiarizarse con Kotlin y XML, aunque no es obligatorio, para saber interpretar el código utilizado en este codelab.

Las Acciones en apps de este codelab solo se activarán correctamente para los idiomas de Asistente de Google en las siguientes configuraciones regionales: en-US, en-GB, en-CA, en-IN, en-BE, en-SG y en-AU. No hay otros idiomas ni configuraciones regionales disponibles para los intents integrados que usa la app para Android de este codelab.

En este codelab, usarás un dispositivo Android para probar las Acciones en apps. Antes de realizar pruebas en un dispositivo Android físico, asegúrate de que esté conectado a tu máquina de desarrollo local. Debes acceder a Google app en el dispositivo y acceder a Android Studio con la misma Cuenta de Google.

Las Acciones en apps conectan a los usuarios de Asistente de Google con tu app para Android, pero ¿sabes cómo funcionan?

Cuando un usuario le indica a Asistente que desea usar tu app, este busca Acciones en apps que hayas registrado en tu app, en un archivo actions.xml. En este archivo, se describen las Acciones en apps mediante una combinación de intents integrados (que describen una capacidad de la app de forma semántica) e instrucciones de entrega (como una plantilla de vínculo directo).

El archivo actions.xml contiene la siguiente información para cada Acción en la app:

  • El intent integrado que usa la Acción en la app
  • Cómo entregar la Acción en la app (por ejemplo, mediante un vínculo directo)
  • Cómo los parámetros del intent mapean a la información que proporciona el usuario a Asistente

Según la información que el usuario le brinda a Asistente, las Acciones en apps crean un vínculo directo para entregar el intent. Luego, la actividad de Android filtra y administra el vínculo directo proporcionado para brindarle al usuario la funcionalidad que desea.

En conjunto, el resultado es una experiencia del usuario en la que Asistente invoca la funcionalidad de tu app en respuesta a una consulta del usuario.

El punto de partida de este codelab es una app de fitness de ejemplo para Android. En ella, los usuarios podrán iniciar y detener temporizadores de ejercicio, así como ver información sobre sus rutinas de entrenamiento.

Descarga los archivos de base

Para obtener los archivos básicos de este codelab, ejecuta el comando que aparece a continuación a fin de clonar el repositorio de GitHub:

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

Al usar la opción --branch codelab-start, se busca la rama en la que comienza este codelab.

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

  1. En el diálogo Welcome to Android Studio, haz clic en la opción Open an existing Android Studio project (si ya tienes un proyecto abierto, primero debes cerrarlo).
  2. A fin de comenzar a trabajar en la app de fitness, busca y selecciona la carpeta donde clonaste el repositorio.

Cambia el ID de la aplicación para Android

A medida que implementes Acciones en apps para la app de fitness, deberás probar entradas con un complemento de Android Studio. Esto lo harás más adelante en el codelab, pero no podrás usar la herramienta de pruebas hasta que hayas subido la app a un proyecto en Google Play Console.

Para que tu versión de la app de fitness de ejemplo sea única en la consola, cambia el ID de aplicación que aparece en la configuración predeterminada de Android correspondiente a tu archivo app/build.gradle:

build.gradle

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

Reemplaza "MYUNIQUENAME" en applicationId con algo que te identifique. Se cambiará el nombre del paquete y se evitará que se produzca un error de nombre de paquete duplicado cuando lo cargues en Play Console.

Prueba la app

Antes de hacer cualquier otro cambio 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:

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

El emulador se inicia igual que un dispositivo físico, por lo que es posible que demore un tiempo, según la velocidad de tu computadora. Una vez que se compila la app y el emulador está listo, Android Studio sube la app al emulador y la ejecuta.

Teléfono que muestra estadísticas de entrenamiento en la app Fit Actions

Explora la app brevemente para descubrir lo que puede hacer. Si presionas el ícono de carrera, se iniciará un temporizador de ejercicio; y si presionas el ícono "X", se detendrá el temporizador. Estas son las dos tareas que podrás habilitar con Acciones en apps.

Repite los pasos anteriores en el dispositivo de prueba para comprobar que la app funcione de la misma manera en las dos plataformas. Antes de continuar, configura y verifica que Asistente funcione en tu dispositivo físico. Para ello, mantén presionado el botón de inicio. Si aún no lo hiciste, tendrás que acceder a Asistente en el dispositivo de prueba.

Sube la app a Play Console

Compila tu app en Android Studio y súbela a Play Console como una versión interna. Este es un requisito previo para poder usar la herramienta de pruebas de Acciones en apps en Android Studio.

En Android Studio, sigue estos pasos:

  1. Dirígete a Build > Generate Signed Bundle / APK.
  2. Selecciona "Android App Bundle" y haz clic en Next.
  3. Ingresa los detalles para firmar tu app de manera digital y haz clic en Next.
  4. Selecciona la variante de compilación "release" 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 Versión y busca la página Pruebas internas.
  4. Haz clic en Crear una versión nueva, en la página Pruebas internas.
  5. En el panel Paquetes de aplicaciones y APK, sube el archivo AAB que generaste anteriormente (es probable que lo encuentres en el directorio app/release).
  6. Haz clic en Guardar.

Ahora que ya subiste la app a Play Console, debes volver a Android Studio.

Instala el complemento de prueba

Debes indicarle de alguna manera a Asistente de Google cuáles son las Acciones en apps registradas en tu app. Durante la etapa de desarrollo, puedes hacerlo mediante el complemento de Android Studio "App Actions test tool".

Si aún no tienes ese complemento, sigue estos pasos para instalarlo:

  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".
  3. Instala la herramienta y reinicia Android Studio.

A fin de configurar una Acción en la app, debes buscar un intent integrado que mapee a una función que realiza tu app para Android. La página de referencia de intents integrados menciona los que están disponibles para Asistente de Google, y cada uno de ellos sirve como modelo para la forma en que los usuarios expresan las tareas que quieren realizar.

En la referencia, los intents integrados que las Acciones en apps pueden entregar se agrupan por categoría y funcionalidad.

En este codelab, implementarás dos intents para ayudar al usuario:

Para ello, deberás configurar un vínculo directo, definir la Acción en la app en los recursos XML de la app y, luego, conectar ambos.

Los vínculos directos pasan información del intent a la app para dirigir a los usuarios al contenido que desean. De forma predeterminada, Asistente usa vínculos directos para entregar el intent y pasar parámetros a la app. En este codelab, los vínculos directos entrantes usan el host "fit-actions.firebaseapp.com" y el esquema "https".

En el archivo de manifiesto de Android, agrega un filtro de intents para la actividad principal a fin de definir los vínculos directos admitidos.

AndroidManifest.xml

<activity android:name="com.devrel.android.fitactions.FitMainActivity" ...>
    ... // Other intent filters

    <!-- Define your supported deeplinks -->
    <intent-filter
        android:autoVerify="true"
        tools:targetApi="m">

        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:host="fit-actions.firebaseapp.com"
            android:scheme="https" />
    </intent-filter>
</activity>

En la actividad principal, agrega la siguiente función para definir el comportamiento de un vínculo directo entrante:

FitMainActivity.kt

private fun handleDeepLink(data: Uri?) {
    when (data?.path) {
        DeepLink.START -> {
            // Get the parameter defined as "exerciseType" and add it to the fragment arguments
            val exerciseType = data.getQueryParameter(DeepLink.Params.ACTIVITY_TYPE).orEmpty()
            val type = FitActivity.Type.find(exerciseType)
            val arguments = Bundle().apply {
                putSerializable(FitTrackingFragment.PARAM_TYPE, type)
            }

            updateView(FitTrackingFragment::class.java, arguments)
        }
        DeepLink.STOP -> {
            // Stop the tracking service if any and return to home screen.
            stopService(Intent(this, FitTrackingService::class.java))
            updateView(FitStatsFragment::class.java)
        }
        else -> {
            // Path is not supported or invalid, start normal flow.
            showDefaultView()
        }
    }
}

DeepLink.START y DeepLink.STOP se definen como constantes en la app de ejemplo y mapean a las rutas de acceso correspondientes de un vínculo directo entrante. En el caso de DeepLink.START, el controlador también obtiene argumentos que ingresan a través de parámetros de URL de vínculos directos.

Ahora debes actualizar la función handleIntent del mismo archivo para usar el controlador del vínculo directo.

FitMainActivity.kt

private fun Intent.handleIntent() {
    when (action) {
        // When the action is triggered by a deep-link, Intent.ACTION_VIEW will be used
        Intent.ACTION_VIEW -> handleDeepLink(data)
        // Otherwise start the app as you would normally do.
        else -> showDefaultView()
    }
}

Ahora, cuando la app filtra un intent con el formato "https://fit-actions.firebaseapp.com/start", se inicia un temporizador de ejercicio.

Si conoces Android Debug Bridge (adb), puedes probar el controlador del vínculo directo en un dispositivo que se esté ejecutando. Para ello, debes actualizar la app en el dispositivo y usar este comando shell:

adb shell am start -a android.intent.action.VIEW -d "https://fit-actions.firebaseapp.com/start"

A fin de que funcionen las Acciones en apps, Asistente de Google necesita saber cuáles están registradas en tu app. Para indicar esta información, debes subir un archivo actions.xml a Play Console como parte del paquete de Android.

Solo tendrás que seguir estos pocos pasos para crear el recurso nuevo y hacer referencia a él:

  1. Crea un archivo actions.xml para establecer qué intents integrados se deben conectar y cuáles son los parámetros necesarios.
  2. Mapea los parámetros de los intents integrados a parámetros de vínculos directos en las actividades.
  3. Agrega una referencia a tu archivo actions.xml en AndroidManifest.xml.

Cómo crear actions.xml

Para describir las Acciones en apps compatibles con tu app, debes crear un nuevo archivo en formato XML llamado actions.xml en app/src/main/res/xml.

En Android Studio, sigue estos pasos:

  1. Ve a File > New > XML > App Actions XML File.
  2. Ingresa "actions" como nombre en Actions File Name.
  3. Haz clic en Finish para crear el nuevo archivo actions.xml y agregar una referencia a él en tu archivo AndroidManifest.xml.

Una vez creado el archivo nuevo, reemplaza el contenido de actions.xml por el siguiente código:

actions.xml

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

<actions>
    <action intentName="actions.intent.START_EXERCISE">
        <fulfillment urlTemplate="https://fit-actions.firebaseapp.com/start{?exerciseType}">
            <parameter-mapping
                intentParameter="exercise.name"
                urlParameter="exerciseType" />
        </fulfillment>
    </action>

    <action intentName="actions.intent.STOP_EXERCISE">
        <fulfillment urlTemplate="https://fit-actions.firebaseapp.com/stop" />
    </action>
</actions>

En el código anterior, usas elementos para definir Acciones en apps que inician y detienen un temporizador de ejercicio en la app. Los atributos intentName corresponden a los dos intents integrados que entregas mediante las Acciones en apps, y los elementos le indican a Asistente cómo debe usar tu app para llevar a cabo la acción.

Aquí, se entregan las dos acciones creando vínculos directos que usan el atributo urlTemplate. Las plantillas de URL usan el host y el esquema que definiste para los vínculos directos en el archivo AndroidManifest.xml. Las rutas de acceso de cada plantilla de URL corresponden a lo que espera la función handleDeepLink (que agregaste antes a la actividad principal).

Ten en cuenta que para iniciar el temporizador, también mapeas el parámetro exercise.name del intent integrado al parámetro de URL exerciseType. Esto permite que tu controlador de vínculos directos obtenga argumentos para la lógica empresarial de Asistente.

Comprueba que tu manifiesto de Android hace referencia a actions.xml

En el paso anterior, Android Studio agregó una referencia a tu archivo actions.xml en AndroidManifest.xml. Para verificar esto, busca el siguiente elemento en el manifiesto de Android:

AndroidManifest.xml

<application>
    ...

    <meta-data
        android:name="com.google.android.actions"
        android:resource="@xml/actions" />
</application>

Si ves el elemento anterior en el archivo de manifiesto, prueba tu Acción en la app.

Si no encuentras el elemento en el archivo de manifiesto, agrégalo.

Prueba las Acciones en apps

Es momento de probar las Acciones en apps en tu dispositivo de prueba.

Conecta el dispositivo y usa la herramienta de pruebas a fin de probar la Acción en la app. Para ello, sigue estos pasos:

  1. Ve a Tools > App Actions > App Actions Test Tool. Es posible que debas acceder a Android Studio. Utiliza la misma cuenta que usaste antes con Google Play Console.
  2. En el campo Invocation Name, ingresa "Fit Actions".
  3. Si el idioma de Asistente no es "English (US)", ingresa la configuración regional que coincida con el idioma de Asistente en el campo Locale.
  4. Haz clic en Create Preview.
  5. En la lista desplegable Configure, selecciona el intent integrado que quieras probar.
  6. Haz clic en Run. Si aparece la opción para abrirlo con Google, selecciona "Siempre" a fin de permitir que Asistente abra los vínculos admitidos (puedes cambiar esto más tarde en la configuración).

Cuando la herramienta de pruebas de Acciones en apps crea o actualiza una vista previa de tus Acciones en apps, lo hace para una sola Cuenta de Google, por lo que registra tus Acciones en apps definidas de forma temporal. Esa vista previa permite que Asistente reconozca tus Acciones en apps antes de implementar la versión de producción de tu app en Google Play Console.

Cuando la herramienta de prueba recupera los intents integrados de tu app, puedes proporcionar directamente los intents con valores de parámetro y activar la acción en la app desde Android Studio.

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, start running in Fit Actions" (inicia una carrera en Fit Actions) para ejecutar la Acción en la app que inicia un temporizador de ejercicio.

Ya puedes iniciar y detener temporizadores de ejercicio en tu app de fitness mediante Asistente de Google, pero habrás notado que solo se reconocen determinadas actividades. Las solicitudes como "Start my swim in Fit Actions" (para iniciar un entrenamiento de natación) o "Start hiking in Fit Actions" (para iniciar en ejercicio de senderismo) activan un temporizador que comienza con el texto "Start unknown in…" (iniciar actividad desconocida en…).

Esto se debe a que los únicos tipos de ejercicio que se admiten actualmente en la app de ejemplo son "Running" (carrera), "Cycling" (ciclismo) y "Walking" (caminata). ¿Cómo se puede ajustar la funcionalidad para los usuarios que quieran registrar otros tipos de entrenamiento con la app?

Hay dos maneras en las que puedes aumentar la cantidad de ejercicios disponibles en esta app:

  • Agrega compatibilidad en la app con más tipos de ejercicio, como natación y senderismo (limitado por los valores de campo de texto admitidos para el intent integrado actions.intent.START_EXERCISE).
  • Mapea otro tipo de ejercicio admitido, como "hiking" (senderismo), a uno que está disponible en la app, como "walking" (caminata).

Si agregas compatibilidad con más tipos de ejercicio, podrás conectar más recorridos en tu app según el ejercicio que quiera realizar un usuario. Esa es una de las formas en las que puedes ayudar a los usuarios, y es la opción correcta si tu app puede llevar a cabo varias tareas diferentes para distintos entrenamientos.

En el caso de la app de fitness, puedes usar la segunda opción para hacer que Asistente de Google se ajuste mejor de inmediato. Cuando lo hagas, los usuarios podrán iniciar un temporizador mediante consultas que incluyan otro valor de campo de texto admitido. En este codelab, usarás inventario intercalado para mapear "Start hiking" (iniciar senderismo) a la funcionalidad de la app correspondiente a "Start walking" (iniciar caminata).

Inventario intercalado

El inventario intercalado define entidades específicas que tu app cree que los usuarios incluirán cuando activen Acciones en apps con Asistente. Agrega este tipo de inventario en tu archivo actions.xml a fin de crear directamente una ficha de opciones admitidas para los usuarios. Los elementos del inventario se agrupan en un elemento , y las definiciones de acciones pueden hacer referencia a conjuntos de entidades para usarlos en los parámetros de asignación.

Como ya se mencionó, la app de ejemplo tiene funcionalidad para admitir "Running", "Cycling" y "Walking". Crea un conjunto de entidades y haz referencia a él en actions.intent.START_EXERCISE a fin de que tu app solo deba usar identificadores de entidad para los vínculos directos.

actions.xml

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

        <!-- Map a parameter to an entity set reference -->
        <parameter name="exercise.name">
            <entity-set-reference entitySetId="ExerciseEntitySet" />
        </parameter>
    </action>
    ...

    <!-- Define an inline inventory -->
    <!-- This sample maps supported entities with the class FitActivity.Type -->
    <entity-set entitySetId="ExerciseEntitySet">
        <entity
            name="@string/activity_running"
            identifier="RUNNING" />
        <entity
            name="@string/activity_walking"
            identifier="WALKING" />
        <entity
            name="@string/activity_hiking"
            identifier="WALKING" />
        <entity
            name="@string/activity_cycling"
            identifier="CYCLING" />
    </entity-set>
</actions>

Cada elemento del inventario intercalado representa una coincidencia única con la consulta del usuario. Las entidades permiten que Asistente distinga entre las entradas admitidas, como las de carrera, caminata y ciclismo. En especial, resultan útiles cuando quieres que Asistente reconozca determinada información específica de tu app, como elementos del menú o servicios.

Si agregas una entidad para la string "hiking" (senderismo), los usuarios que practiquen esa actividad podrán aprovechar la funcionalidad que ya creaste para la de caminata.

Prueba tu inventario

En la herramienta de prueba, la creación o actualización de una vista previa recupera los intents integrados que se registraron en tu app. Luego, puedes proporcionar directamente los intents con valores de parámetro y activar la Acción en la app desde Android Studio.

Sigue estos pasos para probar el inventario en la herramienta de prueba de Acciones en apps:

  1. Haz clic en Update Preview.
  2. Desde la lista desplegable Configure, selecciona "actions.intent.START_EXERCISE".
  3. Escribe "hiking" (senderismo) en el campo exercise.name.
  4. Selecciona tu dispositivo en la lista desplegable Select Target Device.
  5. Haz clic en Run.

La herramienta de prueba de Acciones en apps utiliza la entrada &quot;hiking&quot; (senderismo) para iniciar un temporizador de ejercicio para caminatas (en un dispositivo de prueba).

Felicitaciones.

Ya aprendiste las habilidades necesarias para agregar Acciones en apps a una app de Android.

Temas abordados

  • Cómo identificar actividades de Android con un intent integrado asociado que los usuarios pueden activar mediante Acciones en apps
  • Cómo pasar parámetros de un intent integrado a una app para Android
  • Cómo usar inventario intercalado para mapear valores admitidos a los identificadores de funcionalidades de la app
  • Cómo probar las Acciones en apps en Android Studio

¿Cuáles son los pasos siguientes?

A partir de ahora, puedes probar más ajustes en tu app de fitness. Para brindarte algo de inspiración, proporcionamos una versión extendida de la app en la rama master del repositorio de GitHub. Esta usa Android Slices para brindar información adicional sobre el ejercicio a través de Asistente. Además, incorpora los requisitos de implementación de Acciones en apps para las apps de Android en etapa de producción.

Para obtener más información sobre 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

Antes de salir, completa este formulario para ayudarnos a mejorar el codelab. Comunícate con nosotros si tuviste algún problema, si necesitaste más información para completar los pasos o, incluso, si todo salió bien.