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.
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:
- 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).
- 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:
- 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 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.
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:
- Dirígete a Build > Generate Signed Bundle / APK.
- Selecciona "Android App Bundle" y haz clic en Next.
- Ingresa los detalles para firmar tu app de manera digital y haz clic en Next.
- 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:
- En la página Todas las apps, haz clic en Crear app.
- 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.
- Desde el menú de la barra lateral, ve a Versión y busca la página Pruebas internas.
- Haz clic en Crear una versión nueva, en la página Pruebas internas.
- 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
). - 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:
- Ve a File > Settings (Android Studio > Preferences en macOS).
- En la sección Plugins, ve a Marketplace y busca la herramienta "App Actions test tool".
- 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:
actions.intent.START_EXERCISE
para iniciar el seguimiento de ejercicioactions.intent.STOP_EXERCISE
para detener el seguimiento de ejercicio
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.
Implementa vínculos directos
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:
- Crea un archivo
actions.xml
para establecer qué intents integrados se deben conectar y cuáles son los parámetros necesarios. - Mapea los parámetros de los intents integrados a parámetros de vínculos directos en las actividades.
- Agrega una referencia a tu archivo
actions.xml
enAndroidManifest.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:
- Ve a File > New > XML > App Actions XML File.
- Ingresa "actions" como nombre en Actions File Name.
- Haz clic en Finish para crear el nuevo archivo
actions.xml
y agregar una referencia a él en tu archivoAndroidManifest.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:
- 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.
- En el campo Invocation Name, ingresa "Fit Actions".
- 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.
- Haz clic en Create Preview.
- En la lista desplegable Configure, selecciona el intent integrado que quieras probar.
- 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:
- Haz clic en Update Preview.
- Desde la lista desplegable Configure, selecciona "actions.intent.START_EXERCISE".
- Escribe "hiking" (senderismo) en el campo exercise.name.
- Selecciona tu dispositivo en la lista desplegable Select Target Device.
- Haz clic en Run.
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:
- actions.google.com: Sitio de documentación oficial sobre Actions on Google
- Índice de ejemplos de Acciones en apps: Código y apps de ejemplo para explorar las capacidades de Acciones en apps
- Repositorio de GitHub de Actions on Google: Código de muestra y bibliotecas
- r/GoogleAssistantDev: Comunidad oficial de Reddit para desarrolladores que trabajan con Asistente de Google
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.