Intents personalizados

Cada app es diferente y no todas sus funciones coinciden con un intent integrado de Acciones en apps (BII) disponible. En los casos en que no hay un BII para las funciones de tu app, puedes usar un intent personalizado y extender la app con Acciones en apps.

Al igual que los BII, los intents personalizados siguen el esquema de shortcuts.xml y actúan como puntos de conexión entre Asistente y tus entregas definidas. Los intents personalizados también tienen parámetros de intent que puedes asignar a aquellos en tu entrega correspondiente.

A diferencia de los BII, los intents personalizados requieren patrones de consulta para describir consultas de ejemplo que podría decir un usuario. Este enfoque difiere de los intents integrados, que modelan formas comunes en las que los usuarios expresan ese intent.

Limitaciones

Los intents personalizados tienen las siguientes limitaciones:

• El nombre de un intent personalizado no puede comenzar con actions.intent.
• El nombre de un intent personalizado debe ser único entre los nombres de intents personalizados de tu app.
• Solo ciertos tipos de datos están disponibles para la extracción de parámetros por parte de Asistente de Google (consulta Tipos compatibles).
• Los intents personalizados deben contener ejemplos de patrones de consulta utilizables (consulta Patrones de consulta).
• Cada consulta admite un máximo de dos parámetros de texto. Este límite no se aplica a otros tipos de datos.
• Los intents personalizados solo admiten la configuración regional en-US. Además, la configuración de idioma del dispositivo y de Asistente deben coincidir.

Tipos admitidos

Los intents personalizados admiten los siguientes tipos de schema.org para la extracción de parámetros:

• https://schema.org/Text
• https://schema.org/Date
• https://schema.org/Time
• https://schema.org/Number

Cómo definir Acciones en apps con intents personalizados

Al igual que con otras Acciones en apps que usan BII, defines un intent personalizado en el elemento <capability> en shortcuts.xml.

Las funciones se definen en el elemento raíz <shortcuts>. Cuando definas el elemento <shortcuts>, incluye los espacios de nombres de los atributos a los que deseas acceder, como se muestra en el siguiente ejemplo:

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

Proporciona el nombre del intent personalizado en el atributo android:name y haz referencia a un archivo de recursos de patrones de consulta en el atributo queryPatterns.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

Los nombres de los intents personalizados no pueden comenzar con actions.intent, ya que ese espacio de nombres está reservado para los BIIs. En su lugar, cuando asignes un nombre a tus intents personalizados, usa el prefijo custom.actions.intent para distinguirlos de los BIIs y los intents de Android, que funcionan de manera diferente.

Para cada parámetro, proporciona el tipo de schema.org compatible que mejor describa el significado del parámetro. Por ejemplo, puedes usar https://schema.org/Date para describir una fecha que esperas recibir:

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

Define atajos para intents personalizados en shortcuts.xml con el mismo formato que los atajos de BII.

En el siguiente código, se describe una Acción en la app que usa los patrones de consulta a los que se hace referencia para activar el intent personalizado SCHEDULE_APPOINTMENT y un conjunto definido de valores, DRIVERS_LICENSE y VEHICLE_REGISTRATION, para el parámetro apptType.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

Puedes configurar los parámetros de intents personalizados con el inventario intercalado, que puedes usar a los efectos de guiar la extracción de entidades a un conjunto de entidades compatibles especificadas en shortcuts.xml.

Nota: El inventario web no es compatible con los parámetros de intents personalizados.

Patrones de consulta

Cada intent personalizado que usas requiere un conjunto de consultas que el usuario espera para ese intent. Este enfoque difiere de los BIIs, en los que las consultas ya están modeladas para formas comunes en las que los usuarios expresan las tareas que intentan realizar o la información que buscan.

En un archivo de recursos de Android (por lo general, /res/values/strings.xml), especifica los patrones de consulta como elementos en un array de cadenas. Cuando se invoca tu Acción en la app, Asistente de Google compara la consulta del usuario con tus patrones de consulta como parte de la coincidencia del intent del usuario con respecto a la entrega. Cada patrón de consulta que proporcionas representa una frase que consideras válida para el intent personalizado correspondiente.

Nota: Cada intent personalizado puede estar asociado con hasta 100 patrones de consulta.

Cuando proporciones patrones de consulta para intents personalizados, espera que cada patrón siga una invocación explícita, como "abrir AppDeEjemplo" o "iniciar AppDeEjemplo y". Por ejemplo, considera las siguientes consultas de los usuarios:

• "Hey Google, abre AppDeJuegosDeEjemplo y comienza a preparar un pastel".
• "Hey Google, abre AppDeJuegosDeEjemplo y comienza a preparar un pastel de manzana".
• "Hey Google, inicia AppDeJuegosDeEjemplo y crea 5 elementos de pastel".
• "Hey Google, usa AppDeJuegosDeEjemplo para producir pasteles 5 veces".

Para hacer coincidir las consultas de los usuarios, proporciona patrones de consulta que contengan la parte de la consulta después de la frase de invocación. Si quieres extraer información de la consulta (como texto o un número proporcionado por el usuario), asigna valores al parámetro del intent correspondiente con marcadores de posición en el patrón de consulta.

Nota: Asistente genera concordancias exactas en función de los patrones de consulta que proporcionas para intents personalizados. La coincidencia de patrones de consulta no incluye frases de invocación y usa la configuración de idioma de Asistente.

Para hacer referencia a un parámetro en un patrón de consulta, agrega $ al nombre del parámetro en el patrón. Por ejemplo, para crear un valor de marcador de posición para un parámetro como <parameter name="date1" ... (en actions.xml) o <parameter android:name="date1" ... (en shortcuts.xml), usa $date1.

En el siguiente código, se describen los patrones de consulta que coinciden con las consultas de usuario anteriores y se extraen los valores para los nombres de elementos y la cantidad de elementos que se crearán:

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

Los patrones de consulta admiten condicionales. Por ejemplo, set (an)? appointment $date $time. En este caso, las opciones "programar cita hoy a las doce" y "programar una cita hoy a las doce" son consultas válidas.