Inventario web

Con las Acciones en apps, los usuarios pueden saltar directamente al contenido de tu app con solo decir algo como "Hey Google, muéstrame el menú de Three Dot Cafe en AppDeEjemplo". Esta función se llama vínculos directos y ayuda a los usuarios a completar tareas con tu app.

Para cumplir con este tipo de solicitud, Asistente de Google genera un vínculo directo con contenido coincidente en tu app. Si mantienes tu sitio web de forma activa con contenido o información de productos, y los vínculos directos dentro de la app están organizados en torno a ese contenido, puedes configurar Asistente para que recupere URLs de entrega de acciones de tu sitio web con un inventario web.

Un inventario web es la ubicación en el sitio web de las URLs de elementos compatibles con tu app. Cuando un usuario invoca tu Acción en la app, Asistente hace coincidir la consulta del usuario, como "Three Dot Cafe", con las URLs correspondientes en el índice de la Búsqueda de Google del sitio web que especificaste en el archivo shortcuts.xml de tu app para Android.

Ventajas

El inventario web ofrece ventajas para las apps con grandes listas de elementos, que se actualizan periódicamente y que los usuarios ven u ordenan en la app:

  • Los datos del inventario web se encuentran en tu sitio web, a diferencia de los correspondientes al inventario intercalado, que almacena listas de elementos en la app. Si permites que Asistente acceda a los datos web, se evita el riesgo de obsolescencia de los datos de inventario intercalado, que solo se pueden actualizar con la publicación de una versión nueva de la app.

  • Los inventarios intercalados tienen un límite de 1,000 elementos. En cambio, un inventario web no tiene límite de elementos y puede crecer en función de tus necesidades.

  • Un inventario web puede simplificar la lógica de la app, ya que permite que tu entrega solo maneje las URLs de contenido predecible recuperadas de tu sitio web. Por el contrario, si un inventario no está configurado, Asistente genera vínculos directos para la entrega con la asignación de los parámetros de intent a variables en una plantilla de URL. La entrega deberá analizar esta URL generada de forma dinámica para determinar si un usuario solicitó una entidad compatible con tu app.

Cómo funciona

Durante una Acción en la app, Asistente genera vínculos directos al contenido de la app a través de los intents integrados (BII) que defines en shortcuts.xml. Asistente usa el procesamiento de lenguaje natural para identificar los elementos relevantes en la solicitud de un usuario y los extrae en parámetros de BII. Luego, Asistente genera un vínculo directo con los parámetros en función de tu configuración de entrega en shortcuts.xml..

Existen tres métodos disponibles para generar vínculos directos para la entrega:

  • Asignación de parámetros: Se asignan los parámetros de los intents a los marcadores de posición en una plantilla de URL de entrega.
  • Inventario intercalado: Se hacen coincidir los parámetros de los intents con una lista de entities compatibles definidas en la app.
  • Inventario web: Se hacen coincidir los parámetros de los intents con el contenido que se encuentra en el índice de la Búsqueda de Google de un sitio web.

Un inventario web es un patrón de URL del sitio web definido por el desarrollador, como https://www.exampleapp.com/restaurants/.*, que representa un conjunto de entidades compatibles con una app.

Si se configura un parámetro de BII para un inventario web, Asistente consultará el sitio web a fin de establecer una coincidencia de entidad con la consulta del usuario. Luego, Asistente pasará los resultados de las URLs que coincidan con el patrón de URL configurado, como https://www.exampleapp.com/restaurants/three-dot-cafe, a tu entrega.

Figura 1: Ejemplo de una consulta al Asistente que usa inventario web para recuperar un elemento de entidad de restaurante.

Intents integrados compatibles

Para ciertos parámetros de intents, se admite el inventario web con los siguientes BII:

Cómo agregar inventario web

Una vez que identifiques un BII compatible, puedes habilitarlo para el inventario web actualizando shortcuts.xml con los detalles de tu sitio web. El archivo shortcuts.xml es un recurso de tu proyecto de Android en el que defines los BIIs que se asignan a la función de tu app y la forma en la que cada BII debe generar vínculos directos de modo que esta los entregue. Si quieres obtener más información sobre shortcuts.xml, consulta el archivo para crear el archivo shortcuts.xml.

Si deseas usar el inventario web de un BII compatible, sigue estos pasos:

  1. En el archivo shortcuts.xml de tu app, agrega una etiqueta <capability> con un atributo android:name configurado como el nombre de un BII que controles con el inventario web (por ejemplo, actions.intent.ORDER_MENU_ITEM).

  2. En la etiqueta <capability>, agrega una etiqueta <intent> con un atributo android:action configurado como el nombre de la vista que activará este intent.

  3. En la misma etiqueta <intent>, agrega una etiqueta <parameter> y establece su atributo android:name al parámetro de BII que más se corresponda con la entidad descrita por tus páginas web. Por ejemplo, cuando se proporciona un inventario web para ORDER_MENU_ITEM, debes vincular las páginas del menú a menuItem.name.

  4. En la nueva etiqueta <parameter>, agrega una etiqueta <data> y establece su atributo android:pathPattern en el patrón de URL de la ruta de acceso que quieres usar para el inventario web.

Cuando configuras shortcuts.xml con estos pasos, Asistente puede recuperar contenido web del índice de la Búsqueda de Google del patrón de URL que proporcionaste en el atributo android:pathPattern. Luego, Asistente le proporcionará un valor de URL a tu entrega mediante los resultados que coinciden con el patrón de ruta de URL que definiste. Por último, la app dirigirá al usuario a un lugar específico de tu app en función de los datos de URL que proporcionó Asistente.

Por ejemplo, supongamos que tu sitio web contiene fichas de productos que usan una ruta de URL que comienza con https://www.examplecafe.com/items/. Usarás el valor https://www.examplecafe.com/items/.* de pathPattern, y Asistente usará este patrón de URL en una búsqueda web para encontrar una URL de entrega, como https://www.examplecafe.com/items/item123.

Si Asistente encuentra una URL de inventario web coincidente, la proporcionará en el campo <data> del intent de entrega, como si fuera un vínculo directo. Usa el método getData() del intent a fin de obtener la URL como un objeto Uri. La actividad en la app que recibe el intent es responsable de interpretar la URL y activar la interfaz de usuario de la app adecuada.

Ejemplo de shortcuts.xml

En el siguiente ejemplo, se define un BII ORDER_MENU_ITEM que proporciona un inventario web para mostrar resultados de URL de solicitudes que contienen el parámetro menuItem.name de BII:

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.ORDER_MENU_ITEM">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.OrderMenuItemActivity">
      <!-- Define URL match pattern in the pathPattern data field -->
      <parameter android:name="menuItem.name">
        <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
      </parameter>
    </intent>
  </capability>
</shortcuts>

En el ejemplo anterior, se especificó un pathPattern para menuItem.name y se le indicó al Asistente que solo muestre las URLs que coincidan con el patrón de URL https://www.examplecafe.com/items/.*.

Puedes encontrar más ejemplos de shortcuts.xml disponibles en la documentación de referencia de BII que admiten el inventario web.

Cómo administrar el resguardo de los resultados faltantes

En situaciones en las que no se muestran los resultados del inventario web en tu entrega, la app debe implementar la lógica de resguardo a fin de completar la acción con la mejor experiencia del usuario posible. Entre las situaciones que causan resultados faltantes, se incluyen las siguientes:

  • Falta el parámetro del intent: El usuario omitió un parámetro esperado en su consulta, o bien Asistente no pudo comprender el parámetro de la solicitud del usuario.
  • Falta el resultado de la URL: Asistente no pudo encontrar una entidad en tu sitio web que coincida con la consulta del usuario.

Puedes controlar los valores de parámetros faltantes definiendo varios elementos intent de una función. Cuando Asistente no pueda satisfacer el primer intent, recurrirá al siguiente y así sucesivamente.

Los intents de resguardo no deben requerir parámetros. En cambio, deben entregar la función con un vínculo directo más genérico, como mostrar resultados de la búsqueda para la consulta del usuario.

En el siguiente archivo shortcuts.xml de ejemplo, un BII ORDER_MENU_ITEM define dos entregas: la primera espera una URL del parámetro menuItem.name. La segunda no requiere parámetros y enruta al usuario a una página en la que se muestran todos los elementos del menú.

Archivo shortcuts.xml con intent de resguardo

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
    </parameter>
  </intent>
  <!-- Fallback intent with no required parameters -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ViewMenuActivity">
    <url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
  </intent>
</capability>

Cuando no se muestra la URL de un inventario web, es posible que el contenido de la consulta del usuario se siga usando en intents de resguardo, por ejemplo, para mostrar resultados de la búsqueda.

En el siguiente ejemplo de shortcuts.xml, se definen dos elementos de intent:

  1. El primero requiere un vínculo directo al inventario web del parámetro menuItem.name.
  2. Si no se muestra un vínculo directo, el segundo intent mostrará los resultados de la búsqueda en función de la consulta del usuario a partir de menuItem.name, si está presente.

Archivo shortcuts.xml con resguardo de búsqueda

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- Fallback intent displaying search results, using "menuItem.name" -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.SearchMenuActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Cómo agregar búsquedas integradas en la app con un inventario web

Puedes permitir que los usuarios busquen contenido web en tu app si combinas el inventario web con una implementación del BII actions.intent.GET_THING.

Este BII busca contenido o entidades con la función predeterminada de búsqueda integrada en la app, lo que habilita consultas como: "Hey Google, muéstrame caminatas con cascadas en AppDeEjemplo". Cuando configuras el inventario web del parámetro de función thing.name que pasa el BII GET_THING, los resultados de la entidad coincidente de tu sitio web se pasan para la entrega.

A fin de ver muestras del inventario web del archivo shortcuts.xml, consulta la referencia del BII GET_THING.

Cómo probar el inventario web

Cuando defines un inventario web para una entrega de BII, Asistente genera un vínculo directo mediante los resultados web que coinciden con el patrón urlTemplate que definiste para el parámetro de BII especificado. Si no se puede encontrar un resultado de inventario web, Asistente generará una URL que coincida con el patrón urlTemplate del intent de resguardo. Puedes probar la implementación de tu inventario web verificando que los vínculos que brinda Asistente contengan URL que coincidan con los patrones urlTemplate de tu inventario web.

En el siguiente BII ORDER_MENU_ITEM de muestra, Asistente genera vínculos de entrega de inventario web que coinciden con el patrón urlFilter especificado en el parámetro menuItem.name (por ejemplo, https://www.examplecafe.com/items/nuggets). El segundo intent toma el valor de menuItem.name y realiza una búsqueda si el primer intent no coincide con el patrón de URL.

Archivo shortcuts.xml con intent de búsqueda

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <!-- web inventory fulfillment -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- search intent -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MenuSearchActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Usa la herramienta de pruebas de Acciones en apps a fin de probar el inventario web en un dispositivo físico o virtual.

Para usar esa herramienta, sigue estos pasos:

  1. Conecta el dispositivo de prueba a la app en ejecución.
  2. En Android Studio, ve a Tools > App Actions > App Actions Test Tool.
  3. Haz clic en Create Preview.
  4. En Android Studio, ejecuta la app en tu dispositivo de prueba.
  5. Usa la app de Asistente en tu dispositivo de prueba para probar la Acción en la app. Por ejemplo, puedes decir algo como "Hey Google, pide nuggets en CaféDeEjemplo".
  6. Observa el comportamiento de tu app o usa el depurador de Android Studio a fin de verificar el resultado de la acción que deseas.