Intents personalizados

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

Al igual que los BIIs, 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 BIIs, los intents personalizados requieren patrones de búsqueda para describir consultas de ejemplo que podría hacer un usuario. Este enfoque difiere de los intents integrados y cada uno de ellos modela formas comunes en que los usuarios expresan ese intent.

Limitaciones

Los intents personalizados tienen las siguientes limitaciones:

  • El nombre de un intent personalizado no debe 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 admitidos a fin de ver la lista de tipos compatibles.
  • Se admite un máximo de dos parámetros de texto por consulta. Este límite no se aplica a otros tipos de datos.
  • Solo se admite la configuración regional en-US para los intents personalizados (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 intents integrados, puedes definir un intent personalizado en el elemento <capability> en shortcuts.xml.

Las funciones se definen en el elemento raíz <shortcuts>. Cuando defines el elemento <shortcuts>, debes incluir los espacios de nombres de los atributos a los que quieres acceder.

<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>

Cuando asignes un nombre a tus intents personalizados, te recomendamos que uses el prefijo custom.actions.intent para distinguirlos de los intents integrados y de los de Android (que funcionan de manera diferente). Los nombres de los intents personalizados no deben comenzar con actions.intent, ya que ese espacio de nombres está reservado para intents integrados.

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>
...

La definición de atajo en shortcuts.xml usa el mismo formato para los intents personalizados que para los intents integrados. 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 a fin de 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>
    ...

La definición de atajo en shortcuts.xml usa el mismo formato para los intents personalizados que para los intents integrados. 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 a fin de 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.

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 intents integrados, en los que las consultas ya están modeladas para formas comunes en 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 strings. 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 búsqueda que proporcionas representa una frase que consideras válida para el intent personalizado correspondiente.

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.

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, a fin de crear un valor de marcador de posición para un parámetro como <parameter name="date1" ... (actions.xml) o <parameter android:name="date1" ... (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, "programar (una)? cita el $date a las $time". En este caso, las opciones "programar cita hoy a las doce" y "programar una cita hoy a las doce" son consultas válidas.