Inventario intercalado

Cuando implementes Acciones en apps para tu app para Android, es posible que debas controlar las solicitudes que son variaciones de un tema. Por ejemplo, supongamos que tu app de fitness implementa el intent integrado (BII) START_EXERCISE para permitir que los usuarios inicien una amplia variedad de entrenamientos mediante preguntas a Asistente, como "Hey Google, inicia una carrera en App de Ejemplo".

Cumplir con este intent requiere la lógica de coincidencia de tu solicitud para controlar cada tipo de entrenamiento, incluidas variaciones como "trotar", "sprint" o "carrera". Esta lógica se vuelve engorrosa en poco tiempo a medida que aumentan los entrenamientos compatibles.

Para los BIIs compatibles, como START_EXERCISE, puedes evitar esta lógica de coincidencia compleja con un inventario intercalado. Un inventario intercalado es un conjunto de atajos estáticos de Android definidos en shortcuts.xml que representan funciones y contenido en tu app.

Cada atajo contiene un identificador de elemento y una lista de sinónimos que representan variaciones en la forma en que los usuarios podrían referirse al elemento. Durante la invocación, el BII compara el parámetro de BII que proporciona el usuario con la lista de sinónimos. Cuando se encuentra una coincidencia, se actualiza el parámetro BII con el identificador del elemento del atajo.

Un inventario intercalado permite que Asistente de Google simplifique los valores de parámetros de BII que se proporcionan a tu aplicación durante las invocaciones de Acciones en apps.

Los inventarios intercalados funcionan como tablas de consulta para parámetros de BII, que expresan la variedad de formas en que los usuarios hacen referencia a las funciones o el contenido en tu app con los identificadores de elementos que defines. Simplifican la lógica de coincidencia de la solicitud de tu app, ya que permiten que las entregas anticipan los identificadores de elementos a partir de los parámetros de BII.

Diagrama de flujo de usuarios del inventario intercalado
Figura 1: Diagrama de flujo de una función START_EXERCISE que usa un inventario intercalado para interpretar los nombres de entrenamiento proporcionados por el usuario para los tipos de ejercicio compatibles en la app.

Limitaciones y alternativas

Los atajos de inventario intercalado tienen las siguientes limitaciones:

  • Límite de accesos directos: Se puede definir un máximo de 1,000 atajos de inventario intercalado por app.
  • Límite de sinónimos: Cada atajo del inventario intercalado puede contener un máximo de 20 valores de sinónimos.
  • Definición estática: Los atajos del inventario intercalado se declaran de forma estática en shortcuts.xml y solo se pueden actualizar para los usuarios si publicas una versión nueva de la app.

Dado el requisito de la configuración estática, es mejor usar un inventario intercalado para extender al Asistente la información de la app que cambia con poca frecuencia y no personalizada, como elementos del menú, rutas de autobuses o tamaños de bebidas. Para otros tipos de contenido, considera estas alternativas:

  • Inventario web: Permite que Asistente consulte contenido web público cuando hace coincidir las consultas de los usuarios con los identificadores de contenido de la app compatibles. Las consultas de inventario web se realizan en tiempo real durante una invocación, lo que te permite extender al Asistente catálogos de productos, publicaciones de redes sociales y otro contenido que se actualiza con frecuencia.

  • Atajos dinámicos: Extienden un inventario de contenido personalizado de la app al Asistente. Los atajos dinámicos permiten a los usuarios volver a reproducir acciones comunes con rapidez, como volver a pedir su bebida favorita desde una app de pedidos de comida o abrir una lista de compras en una app para tomar notas.

Cómo crear un inventario intercalado

Un inventario intercalado simplifica el desarrollo, ya que le brinda al Asistente una forma práctica de traducir las diferentes formas en que los usuarios solicitan el contenido y las funciones de tu app en los identificadores predecibles que espera tu aplicación. Por ejemplo, supongamos que tu app ofrece diferentes entrenamientos que los usuarios pueden comenzar a usar con su voz y espera que realicen las siguientes solicitudes para el mismo tipo de ejercicio:

  • Hey Google, inicia una actividad de correr en App de Ejemplo.
  • Hey Google, comienza a trotar en App de ejemplo.

En el acceso directo del inventario intercalado, configura shortcutId como "CARDIO_RUN", el identificador de ejercicio que espera tu app. Luego, especifica "correr" y "trotar" como sinónimos asociados a shortcutId. Luego, cuando un usuario active la Acción en la app con las consultas anteriores, Asistente usará el identificador "CARDIO_RUN" para el parámetro de BII cuando genere un intent de entrega.

En el siguiente fragmento de un archivo app/res/shortcuts.xml de muestra, se implementa este caso:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

En el ejemplo anterior, el inventario intercalado shortcut declara una etiqueta <parameter-binding> dentro de un elemento <capability-binding> y la vincula a el parámetro de BII exercise.name definido en <capability>.

El recurso de array de strings @array/run_names especifica una lista de sinónimos en res/values/arrays.xml que Asistente reconoce y asigna al ID de elemento "CARDIO_RUN":

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

Cuando se proporciona un <url-template> para la capability, el shortcutId de un valor coincidente se inserta en la URL generada en el marcador de posición correspondiente para el parámetro. Con el siguiente código de un archivo app/res/shortcuts.xml de muestra, se implementa este caso:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://workout{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

En el ejemplo anterior, Asistente genera el vínculo directo de entrega myapp://workout?exercise=CARDIO_RUN.

Entrega con intents de atajos

De forma predeterminada, un atajo brinda el shortcutId de un valor de inventario intercalado coincidente al intent de la capability a la que está vinculado el atajo, como se declara en su etiqueta <capability-binding>. Si quieres, puedes especificar que un intent definido en el atajo se use para la entrega si agregas una etiqueta <shortcut-fulfillment> a capability.

En el siguiente código de un archivo app/res/shortcuts.xml de muestra, se implementa la entrega de atajos:

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

En el ejemplo anterior, si la consulta del usuario coincide con un valor de inventario intercalado para el parámetro exercise.name, la etiqueta <shortcut-fulfillment> especifica que el intent del atajo vinculado se usa para la entrega.

Inventario intercalado para el BII de función abierta de la app

Si bien el inventario intercalado suele ser una capacidad opcional para los BIIs que lo admiten, es obligatorio en algunos BIIs, como OPEN_APP_FEATURE. Este BII de uso general permite a los usuarios establecer vínculos directos a funciones específicas de la app con Asistente. El BII de función abierta de la app requiere un inventario intercalado de nombres de funciones de la app para verificar que exista una función solicitada por el usuario antes de vincularlo directamente a tu app.

En el siguiente código de un archivo app/res/shortcuts.xml de muestra, se implementa este BII con un solo atajo que representa la función de estado del pedido de la app:

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

Los recursos de array de strings en res/values/arrays.xml, @array/order_status_names, especifican una lista de sinónimos para esta función:

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

Con la capacidad anterior implementada, Asistente puede entregar una variedad de frases para la misma función:

  • "Hey Google, muéstrame el estado de mi pedido en App de Ejemplo".
  • "Hey Google, muéstrame mis pedidos en App de Ejemplo".
  • "Hey Google, muéstrame mi historial de pedidos en AppDeEjemplo".

Cómo probar el inventario intercalado

Para probar tu inventario, inspecciona los valores de los parámetros de BII que proporciona Asistente a tu aplicación mientras entrega capacidades de Acciones en apps relevantes. Un inventario intercalado funciona reemplazando el valor proporcionado por el usuario de un parámetro de BII vinculado al inventario por el shortcutId de un atajo del inventario intercalado coincidente.

Por ejemplo, una función de BII START_EXERCISE podría usar un inventario intercalado para traducir el parámetro de BII proporcionado por el usuario "ejecutar" a su ID de ejercicio correspondiente, "CARDIO_RUN".

El complemento de Asistente de Google te permite obtener una vista previa de las Acciones en apps de tu inventario intercalado en Asistente en un dispositivo de prueba. Sigue estos pasos para probar tu inventario con el complemento:

  1. Configura los parámetros vinculados al inventario de tu capacidad de BII con valores de sinónimos asociados al inventario intercalado.
  2. Invoca el BII desde el complemento para activarlo en el dispositivo de prueba.
  3. Inspecciona los valores de parámetros resultantes que Asistente proporciona a tu aplicación durante la entrega de Acciones en apps.