Inventario intercalado

Cuando implementas Acciones en apps para tu app para Android, es posible que te encuentres con tener que controlar solicitudes que son variaciones de un tema. Por ejemplo, digamos que app de fitness implementa el intent integrado (BII) START_EXERCISE para permitir los usuarios inician una amplia variedad de entrenamientos preguntándole al Asistente "Hey Google, inicia una carrera en App de Ejemplo".

Completar este intent requiere que tu lógica de coincidencia de solicitudes maneje cada tipo de entrenamiento, incluidas las 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 coincidencia compleja lógica con un inventario intercalado. Un inventario intercalado es un conjunto Combinaciones de teclas de Android definidas en shortcuts.xml que representan funciones y contenido en tu app.

Cada acceso directo contiene un identificador de elemento y una lista de sinónimos que representan variaciones en cómo 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 el parámetro de BII proporcionados a tu aplicación durante las invocaciones de Acciones en apps.

Los inventarios intercalados funcionan como tablas de consulta de parámetros de BII expresar la variedad de formas en las que los usuarios se refieren a las funciones o el contenido de la aplicación con identificadores de artículos que tú definas. Simplifican la coincidencia de solicitudes de tu app lógica, ya que permite que tus entregas prevean identificadores de elementos de BII parámetros.

Figura 1: Diagrama de flujo de una función START_EXERCISE que usa un inventario intercalado para interpretar los nombres de los entrenamientos proporcionados por el usuario para los de ejercicios en la app.

Nota: El inventario intercalado es compatible con parámetros específicos de ciertos BII. Para obtener más información, consulta la sección de "Inventario disponibilidad por campo" en la referencia de BII.

Limitaciones y alternativas

Los atajos del inventario intercalado tienen las siguientes limitaciones:

• Límite de atajos: Se puede agregar un máximo de 1,000 atajos de inventario intercalado. definidos por app.
• Límite de sinónimos: Cada atajo del inventario intercalado puede contener un máximo de 20. los valores de los sinónimos.
• Definición estática: Los atajos del inventario intercalado se declaran estáticamente. en shortcuts.xml y solo se puede actualizar para los usuarios mediante la publicación de un nuevo versión de tu app.

Dado el requisito de la configuración estática, es mejor tener un inventario intercalado. adecuado para extender la información de la aplicación no personalizada y que cambia con poca frecuencia a Asistente, 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 Hacer coincidir las consultas de los usuarios con los identificadores de contenido de la app admitidos. Inventario web las consultas ocurren en tiempo real durante una invocación, lo que te permite extender catálogos de productos, publicaciones en redes sociales y otro contenido que se actualiza con frecuencia al Asistente.

• Atajos dinámicos: Extienden el inventario de contenido personalizado de la app. al Asistente. Los atajos dinámicos permiten a los usuarios volver a reproducir como volver a pedir su bebida favorita desde una aplicación de pedidos de comida mostrar una lista de compras en una aplicación para tomar notas.

Cómo crear un inventario intercalado

Un inventario intercalado simplifica el desarrollo, ya que brinda al Asistente una forma práctica de hacer lo siguiente: traduce 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. Para Por ejemplo, supongamos que la app ofrece diferentes entrenamientos que los usuarios pueden usar su voz, y tu app espera que los usuarios realicen las siguientes solicitudes para el mismo tipo de ejercicio:

• Hey Google, inicia una carrera en App de Ejemplo.
• Hey Google, inicia un trote en App de Ejemplo.

En el atajo del inventario intercalado, establece shortcutId en "CARDIO_RUN", el identificador de ejercicio que espera tu app. Luego, especificas "ejecutar" y "trotar" como sinónimos asociados a shortcutId. Luego, cuando un usuario activa tu Acción en la app con las consultas anteriores, el Asistente usa el identificador "CARDIO_RUN" para el parámetro de BII cuando se genera 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 cadenas @array/run_names especifica una lista de sinónimos en res/values/arrays.xml que Asistente reconoce y asigna a la ID de elemento de "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 del se inserta un valor coincidente en la URL generada en el directorio marcador de posición para el parámetro. El siguiente código de un ejemplo El archivo app/res/shortcuts.xml 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

Nota: El inventario intercalado admite un máximo de un parameter por elemento intent de entrega de un objeto capability.

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.

El siguiente código de un archivo app/res/shortcuts.xml de muestra implementa 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.

Nota: Cada inventario intercalado <shortcut> está destinado a la entrega de atajos. debe contener un <intent> de entrega. Para evitar errores de entrega, No uses atajos que no contengan elementos de intent para el atajo o entrega de productos.

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. Esta Los BII de uso general permiten que los usuarios establezcan vínculos directos a funciones específicas de la app. con Asistente. El BII de función abierta de una app requiere un inventario intercalado de los nombres de las funciones de la app para verificar que exista una función solicitada por el usuario antes de realizar una vinculación directa con tu app.

En el siguiente código de un archivo app/res/shortcuts.xml de muestra, se implementa lo siguiente: BII con un solo atajo que representa la función de estado de 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 cadenas de res/values/arrays.xml @array/order_status_names, especifica una lista de sinónimos de esta característica:

<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 App de Ejemplo".

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. Una línea de comandos El inventario funciona reemplazando el valor proporcionado por el usuario de un BII vinculado al inventario. con el shortcutId de un atajo de inventario intercalado coincidente.

Para Por ejemplo, una capability de BII START_EXERCISE podría usar un inventario intercalado para traduce el parámetro de BII proporcionado por el usuario "run" a su ejercicio correspondiente ID: "CARDIO_RUN".

El complemento Google Assistant te permite obtener una vista previa de tu app de inventario intercalado. Acciones 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 durante la entrega de Acciones en apps.