Configura Acciones en apps para implementar el Asistente de Google en una app para Android

1. Descripción general

Con Acciones en apps, puedes utilizar el Asistente de Google para acceder directamente a las funciones de una app y completar tareas con tu voz. Como desarrollador de Android, puedes implementar elementos de capabilities para integrar Acciones en apps. Las capabilities informan al Asistente qué funciones de la app admiten solicitudes de los usuarios por voz y cómo esperas que se lleven a cabo esas solicitudes.

Este codelab abarca conceptos de nivel principiante para el desarrollo con Acciones en apps. Para poder comprender el contenido de este codelab, es necesario que tengas experiencia previa en el desarrollo de apps para Android y de intents de Android. Si recién comienzas a trabajar con Android, tal vez te resulte conveniente empezar por uno de los codelabs de Conceptos básicos para desarrolladores de Android.

Qué harás

En este codelab, agregarás a una app de fitness de ejemplo para Android dos intents integrados (BII) de Acciones en apps para permitir que los usuarios inicien y detengan con su voz un cronómetro de ejercicio.

Qué aprenderás

Aprenderás a usar los BII de la categoría Salud y fitness para implementar el Asistente en una app para Android. También descubrirás cómo utilizar el complemento Google Assistant de Android Studio para probar los BII.

Requisitos previos

Antes de continuar, asegúrate de tener las siguientes herramientas en tu entorno:

• Una terminal para ejecutar comandos de 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 o virtual con acceso a Internet que permita ingresar en Play Store

En primer lugar, tienes que asegurarte de acceder a Android Studio, así como a la app de Google en tu dispositivo de prueba, utilizando la misma Cuenta de Google.

2. Comprende el funcionamiento

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

Cuando un usuario le pide al Asistente que realice una tarea con tu app, el Asistente busca una coincidencia entre esa consulta y un elemento capability de Acciones en apps definido en el recurso XML (es decir, el archivo shortcuts.xml) de tu app.

Término clave: Los elementos de capabilities 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 capabilities.

Figura 1: Un diagrama de flujo que muestra cómo el Asistente procesa una consulta por voz de Acciones en apps

Cada elemento de capability define lo siguiente:

• Un intent, es decir, el objeto que establece un comando por voz de Acciones en apps y que debe activar la capability
• Una o más entregas, es decir, los vínculos directos o intents de Android que genera el Asistente para iniciar la app y llevar a cabo la solicitud del usuario por voz (las definiciones de las entregas especifican qué parámetros se esperan de la consulta del usuario y cómo se deben codificar esos parámetros en las instrucciones de inicio)

Intents

En el ámbito de la comprensión del lenguaje natural (CLN), un intent se compone de un grupo de frases de usuario que tienen significados similares. Google creó decenas de intents "integrados" (BII) que abarcan una amplia variedad de tipos de solicitudes disponibles para las Acciones en apps. Por ejemplo, el Asistente está entrenado para relacionar las frases "Pide una pizza" o "Muéstrame el menú de postres" con el BII ORDER_MENU_ITEM. Con Acciones en apps, puedes aprovechar estos BII para configurar las funciones de la app de forma tal que se puedan utilizar mediante solicitudes comunes por voz.

Entregas

Cuando la solicitud de un usuario activa una Acción en la app que se encuentra incluida en el archivo shortcuts.xml, tu actividad de Android tiene que detectar y procesar el vínculo directo o el intent de Android entrante para proporcionarle al usuario la funcionalidad deseada. El resultado es una experiencia del usuario basada en comandos por voz 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 fitness de ejemplo para Android. Esta app permite a los usuarios iniciar y detener un cronómetro de ejercicio, y ver estadísticas sobre sus rutinas de ejercicio.

Descarga los archivos fundamentales

Para obtener los archivos fundamentales de este codelab, ejecuta el siguiente comando para clonar el repositorio de GitHub:

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

Una vez que hayas clonado el repositorio, ábrelo 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.

Nota: El comando git clone anterior muestra la rama codelab-start del repositorio, es decir, el punto inicial de este codelab. Para adelantarte y ver la app como se mostraría después de completadas las instrucciones del codelab, consulta la rama principal del repositorio.

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, verás la advertencia "Gradle files have changed since last project sync…" en Android Studio. En ese cuadro de advertencia, haz clic en Sync Now para evitar que ocurran problemas cuando subas tu app.

Prueba la app en tu dispositivo

Antes de realizar más cambios en el código de la app, es conveniente probarla en tu entorno de desarrollo para tener una idea de lo que puede hacer la app de ejemplo. Esto abarca los siguientes pasos:

1. Abrir tu dispositivo Android físico o virtual de prueba
2. Verificar que la app del Asistente funcione correctamente
3. Utilizar Android Studio para implementar y ejecutar la app de ejemplo en tu dispositivo

Para probar la app, sigue estos pasos:

1. En Android Studio, selecciona Run > Run app, o haz clic en Run en la barra de herramientas.
2. Si utilizas un dispositivo virtual, en el diálogo Select Deployment Target, selecciona un dispositivo 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 en dispositivos que tengan hasta la versión Android 5 (nivel de API 21).
3. Después de abrir la app, mantén presionado el botón de inicio para configurar el Asistente y verificar que funcione. Si aún no lo hiciste, accede al Asistente.
4. Vuelve a abrir la app.

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

Figura 2: La app de ejemplo FitActions, en la que se muestran estadísticas de ejercicio

Explora la app brevemente para ver lo que puede hacer. Si presionas el ícono de persona que corre, se iniciará un cronómetro de ejercicio que luego podrás detener presionando el ícono de X. Estas son las tareas que habilitarás para el control por voz en las Acciones en apps.

Instala el complemento Google Assistant

El complemento Google Assistant te permite probar tus Acciones en apps en un dispositivo de prueba. Sigue estos pasos para agregarlo a Android Studio:

1. Ve a File > Settings (Android Studio > Preferences en MacOS).
2. En la sección Plugins, accede a Marketplace y busca "Google Assistant".
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. Para que las Acciones en apps funcionen correctamente, tu dispositivo de prueba debe tener acceso a Play Store para poder actualizar la app de Google.

4. Agrega la capability de BII Start Exercise

El BII actions.intent.START_EXERCISE permite que los usuarios abran una app y utilicen su voz para iniciar un entrenamiento. En este paso, implementarás una capability para ese BII, que permite que los usuarios le pidan al Asistente que inicie una actividad de correr en la app de fitness.

Define la capability

El Asistente utiliza elementos capability, definidos en el archivo shortcuts.xml, para procesar los comandos por voz siguiendo estos pasos:

1. El Asistente vincula la consulta por voz del usuario con un BII definido en las capabilities de tu app.
2. Luego, el Asistente extrae valores de la consulta y los agrega a parámetros de BII. Cada parámetro se incluye en un Bundle adjunto a un Intent generado.
3. El Asistente ejecuta el Intent para iniciar la app y permitir que esta pueda acceder a los parámetros empaquetados.

El BII START_EXERCISE admite el parámetro de BII exercise.name. Específicamente, tendrás que utilizar este parámetro para permitir que los usuarios indiquen el tipo de ejercicio del que quieren que la app haga un seguimiento.

Agrega el elemento capability al archivo shortcuts.xml, ubicado en el directorio del proyecto de ejemplo (app/src/main/res/xml), para configurar tu app con el BII START_EXERCISE:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <parameter
      android:name="exercise.name"
      android:key="exerciseType"/>
  </intent>
</capability>

Reemplaza PUT_YOUR_APPLICATION_ID_HERE por el applicationId único que definiste en el paso anterior.

El XML de ejemplo anterior:

• Declara una capability para el BII START_EXERCISE.
• Especifica el intent de Android que el Asistente genera para iniciar la app:
  • Los atributos targetPackage y targetClass especifican la actividad receptora.
  • El atributo parameter asigna el parámetro de BII exercise.name a exerciseType en los extras de Bundle que recibe la actividad.

Controla los parámetros de BII con un inventario intercalado

Los parámetros de BII representan elementos extraídos de una consulta que el usuario le hace al Asistente. Por ejemplo, si un usuario dice "Hey Google, inicia una actividad de correr en App de Ejemplo", el Asistente extraerá "correr" y lo agregará al parámetro de BII exercise.name de schema.org. Para algunos BII, puedes ordenarle al Asistente que establezca la coincidencia de los parámetros de BII con un conjunto de identificadores que espera tu app.

Para ello, puedes vincular elementos del inventario intercalado al parámetro de BII en cuestión. Un inventario intercalado es un conjunto de valores de parámetros de BII admitidos, como "correr", "hacer una caminata" y "trotar", cada uno con su correspondiente ID de atajo, como EXERCISE_RUN. Esta vinculación del inventario permite que el Asistente le pase a tu actividad de entrega el ID de atajo para los parámetros coincidentes, en vez del valor sin procesar de la consulta.

Para que funcionen, algunos parámetros de BII, como exercise.name, requieren un inventario intercalado. Puedes ejercer el control sobre ese parámetro si agregas los siguientes elementos shortcut del inventario al archivo shortcuts.xml:

<!-- shortcuts.xml -->

<shortcuts>
  <shortcut
    android:shortcutId="running"
    android:shortcutShortLabel="@string/activity_running">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/runningSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="walking"
    android:shortcutShortLabel="@string/activity_walking">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/walkingSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="cycling"
    android:shortcutShortLabel="@string/activity_cycling">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/cyclingSynonyms"/>
    </capability-binding>
  </shortcut>

  <capability> ... </capability>
</shortcuts>

En el código anterior, definiste tres atajos que representan un inventario intercalado para los tipos de ejercicios admitidos por la app: correr, caminar y andar en bicicleta. Cada atajo está vinculado a la capability de las siguientes maneras:

• Cada atributo android:key del elemento capability-binding hace referencia al mismo BII START_EXCERCISE definido para la capability.
• El elemento parameter-binding de cada atajo está codificado con el parámetro de BII exercise.name.

Nota: Después de completar este paso, es posible que Android Studio te advierta que no puede resolver los símbolos correspondientes a los valores de sinónimos. Completa el paso que se indica a continuación para solucionar ese problema.

Agrega sinónimos al inventario intercalado

Los atributos android:value del elemento parameter-binding en los atajos anteriores del inventario hacen referencia a un recurso de array de sinónimos para cada elemento del inventario. Los sinónimos introducen variaciones de un tipo de elemento, como "correr", "trotar" y "esprintar", para hacer referencia al mismo shortcutId. Agrega las siguientes entradas de sinónimos al recurso array.xml del proyecto:

<!-- array.xml -->
<array name="runningSynonyms">
  <item>Run</item>
  <item>Jog</item>
  <item>Jogging</item>
  <item>Sprint</item>
</array>

<array name="walkingSynonyms">
  <item>Walk</item>
  <item>Hike</item>
  <item>Hiking</item>
</array>

<array name="cyclingSynonyms">
  <item>Biking</item>
  <item>Riding</item>
  <item>Pedaling</item>
</array>

Procesa los intents de Android entrantes

Los intents de Android son objetos de transmisión de mensajes que Android utiliza para solicitar una acción de otra app. Para llevar a cabo las consultas que los usuarios hacen con comandos por voz, el Asistente genera un intent tomando en cuenta los detalles de configuración incluidos en la capability activada. Para ejecutar los intents de la capability START_EXERCISE, tienes que actualizar la clase de destino FitMainActivity de forma tal que procese el intent entrante y los parámetros de BII.

En primer lugar, reemplaza la función Intent.handleIntent por el siguiente código:

//FitMainActivity.kt

private fun Intent.handleIntent() {
  when (action) {
    // When the BII is matched, Intent.Action_VIEW will be used
    Intent.ACTION_VIEW -> handleIntent(data)
    // Otherwise start the app as you would normally do.
    else -> showDefaultView()
  }
}

A continuación agrega a la clase una nueva función handleIntent con el siguiente código:

//FitMainActivity.kt

/**
 * Use extras provided by the intent to handle the different BIIs
 */

private fun handleIntent(data: Uri?) {
  // path is normally used to indicate which view should be displayed
  // i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
  var actionHandled = true

  val startExercise = intent?.extras?.getString(START_EXERCISE)
  // Add stopExercise variable here

  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  else{
   // path is not supported or invalid, start normal flow.
   showDefaultView()

   // Unknown or invalid action
   actionHandled = false
  }
  notifyActionSuccess(actionHandled)
}

En la función Intent.handleIntent anterior, cuando se activa ACTION_VIEW, los datos del intent de la Acción en la app se pasan a la función handleIntent. Se puede acceder a los parámetros de BII empaquetados en el intent START_EXERCISE mediante intent?.extras?.getString(START_EXERCISE). El resto de la función actualiza FitTrackingFragment para mostrar el tipo de ejercicio elegido (startExercise).

Prueba la Acción en la app

Durante el desarrollo de Acciones en apps, puedes utilizar el complemento Google Assistant para obtener una vista previa de tus Acciones en un dispositivo de prueba. También puedes usar el complemento para ajustar los valores de parámetros de intent de una Acción y probar cómo tu app procesa las diferentes maneras en que un usuario podría formular una solicitud para que el Asistente la lleve a cabo en esa app.

Para probar la Acción en la app con el complemento, sigue estos pasos:

1. Ejecuta la app en Android Studio. Para ello, selecciona Run > Run App, o haz clic en el ícono del botón Run en la barra de herramientas superior.
2. Ve a Tools > App Actions > Google Assistant > App Actions Test Tool.
3. Haz clic en Create Preview. Si se te solicita, revisa y acepta las políticas y las Condiciones del Servicio de Acciones en apps.
4. Selecciona el intent integrado actions.intent.START_EXERCISE.
5. En el cuadro exercise, deja el valor predeterminado running.
6. Haz clic en Run App Action. Verifica que el Asistente establezca una vinculación directa con el cronómetro de ejercicio de la app y que se inicie un entrenamiento que represente el tipo de actividad de correr en el cronómetro.

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

Acabas de implementar tus primeras Acciones en apps con el BII START_EXERCISE. ¡Felicitaciones! A continuación aprenderás cómo permitir que los usuarios detengan en la app un entrenamiento relacionado con la actividad de correr.

5. Agrega la capability de BII Stop Exercise

El BII actions.intent.STOP_EXERCISE permite que los usuarios detengan una sesión de entrenamiento con frases como "Hey Google, detén mi actividad de correr en App de Ejemplo". Agrega un segundo elemento capability al archivo shortcuts.xml para implementar ese BII en la app de fitness:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.STOP_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <!-- Eg. name = "Running" -->
    <parameter
        android:name="exercise.name"
        android:key="stopExercise"/>
  </intent>
</capability>

Reemplaza PUT_YOUR_APPLICATION_ID_HERE por tu applicationId único.

Controla los parámetros de BII con un inventario intercalado

Este BII admite el mismo parámetro exercise.name que el BII START_EXERCISE, lo que permite que los usuarios especifiquen qué entrenamiento activo desean finalizar. Para habilitar este funcionamiento, agrega al archivo shortcuts.xml un segundo conjunto de elementos de atajos del inventario:

<!-- shortcuts.xml -->

<shortcut
  android:shortcutId="running"
  android:shortcutShortLabel="@string/activity_running">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/runningSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="walking"
  android:shortcutShortLabel="@string/activity_walking">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/walkingSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="cycling"
  android:shortcutShortLabel="@string/activity_cycling">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/cyclingSynonyms"/>
  </capability-binding>
</shortcut>

Procesa los intents de Android entrantes

Actualiza la clase FitMainActivity para permitir que la app procese los intents STOP_EXERCISE de Android entrantes. Primero, agrega una variable a la función handleIntent para que contenga los datos del intent STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
  //...
}

A continuación, actualiza la lógica condicional de la función handleIntent para que controle los intents STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  //...
  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  <strong>
  } else if(stopExercise != null){
    // Stop the tracking service if any and return to home screen.
    stopService(Intent(this, FitTrackingService::class.java))
    updateView(FitStatsFragment::class.java)
  }
  </strong>
  //...
}

En el código anterior, actualizaste la función handleIntent para que busque el BII STOP_EXERCISE en el intent de Android entrante. Si lo encuentra, la función detendrá el cronómetro activo y redireccionará al usuario a la pantalla principal.

Prueba la Acción en la app

Utiliza el complemento Google Assistant para probar la Acción en la app siguiendo estos pasos:

1. Ejecuta la app en Android Studio. Para ello, selecciona Run > Run App, o haz clic en el ícono del botón Run en la barra de herramientas superior.
2. En la app, inicia un nuevo ejercicio de "correr".
3. Abre el complemento en Android Studio. Para ello, ve a Tools > App Actions > Google Assistant > App Actions Test Tool.
4. Haz clic en Create Preview.
5. Selecciona el intent integrado actions.intent.STOP_EXERCISE.
6. En el cuadro exercise, deja el valor predeterminado running.
7. Haz clic en Run App Action. Verifica que el Asistente detenga el entrenamiento y te redireccione a la pantalla principal.

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

6. Próximos pasos

¡Felicitaciones!

Ahora sabes cómo configurar intents integrados para implementar el Asistente en una app para Android y permitir que los usuarios la utilicen mediante comandos por voz. 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 utilizar un inventario intercalado
• Cómo probar los BII con el complemento Google Assistant

¿Qué sigue?

De ahora en adelante, podrás definir mejor tu app de fitness. Para consultar el proyecto finalizado, accede a la rama principal en GitHub.

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

• Consulta nuestros otros codelabs de Acciones en apps.
• Consulta la referencia de intents integrados de Acciones en apps para conocer BII adicionales y extender la implementación del 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 capabilities 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 el hashtag #appactions para compartir tus compilaciones.

Encuesta de comentarios

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