Cómo crear shortcuts.xml

Una vez que identifiques las funciones de la app y el intent integrado (BII) correspondiente para implementar, declara los BIIs que admite tu función con la definición de un elemento capability en un archivo de recursos shortcuts.xml. La declaración de un BII como una capability registra la compatibilidad con ese intent semántico en tu app y permite que se realice la entrega de la consulta por voz del intent con Asistente de Google.

Asistente usa el procesamiento de lenguaje natural para extraer los parámetros de una consulta de usuario. En la referencia de los intents integrados, se enumeran los campos que cada BII puede extraer de una consulta del usuario asociada. Por ejemplo, si un usuario invoca la función [actions.intent.GET_FOOD_OBSERVATION][] en tu app cuando dice: "Hey Google, pregúntale a App de Ejemplo qué comí el viernes pasado", Asistente extrae los siguientes parámetros de BII de la solicitud del usuario:

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

Asistente pasa parámetros de BII al intent de entrega definido en la capability. Se pueden definir uno o más elementos de intent en una función para adaptarse a las diferentes formas en que un usuario podría invocar un BII. Por ejemplo, podrías definir un intent de entrega que requiera ambos parámetros de BII en el ejemplo anterior. Luego, puedes definir un segundo intent que requiera un solo parámetro de BII, foodObservation.forMeal, que informe sobre todas las comidas de un día en particular, como "Hey Google, pregúntale a App de Ejemplo qué comí para el almuerzo".

Descripción general

Para configurar Acciones en apps, debes usar un archivo shortcuts.xml ubicado en el directorio res/xml del proyecto de tu app y, luego, crear una referencia a shortcuts.xml en el manifiesto de la app. A fin de agregar una referencia a shortcuts.xml en el manifiesto de tu app, sigue estos pasos:

1. En el archivo de manifiesto de tu app (AndroidManifest.xml), busca una actividad cuyos filtros de intents estén configurados en la acción android.intent.action.MAIN y la categoría android.intent.category.LAUNCHER.

2. Agrega una referencia al archivo shortcuts.xml en AndroidManifest.xml con una etiqueta <meta-data> en la Activity que tenga filtros de intents para MAIN y LAUNCHER de la siguiente manera:

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

En el ejemplo anterior, se declara un recurso XML para el archivo xml/shortcuts.xml en el APK. Si deseas obtener más información sobre la configuración de atajos, consulta el artículo para crear atajos estáticos en la documentación para desarrolladores de Android.

La biblioteca de Jetpack androidx.core:core:1.6.0 (o una posterior) es obligatoria en tu proyecto de Android a fin de evitar errores de compilación a la hora de definir las capacidades de Acciones en apps en shortcuts.xml. Para obtener más información, consulta Cómo comenzar a usar Android Jetpack.

Atajos estáticos

Cuando defines tu capability, puedes declarar elementos shortcut estáticos en shortcuts.xml para extender la funcionalidad de la capacidad. Asistente transfiere los atajos estáticos cuando subes una versión a Google Play Console. Como los atajos estáticos solo se pueden crear y actualizar con la creación de versiones nuevas, resultan más útiles para destacar actividades y contenido comunes en tu app.

Puedes habilitar la siguiente función de Acciones en apps con atajos estáticos:

• Atajos de funciones: Crea atajos que inicien una instancia de tu capability que contenga valores del parámetro intent predefinidos. Por ejemplo, puedes declarar un atajo a la app como "Iniciar una ejecución", que invoca la función de BII START_EXERCISE en tu app de fitness.

  Estos atajos contienen atributos intent, shortLabel y longLabel, lo que los hace aptos para que se sugieran y entreguen como chips en plataformas proactivas, como Asistente o cuando se mantiene presionado el ícono de la app en los selectores de Android. Un atajo de acción también puede funcionar como atajo de entidad, que se detalla a continuación, si lo asocias a un capability con una etiqueta <capability-binding>.

• Atajos de entidades: Los atajos de entidades proporcionan una lista de valores de parámetros compatibles para la entrega de consultas por voz de una capability. Por ejemplo, un atajo de entidad con una lista de tipos de ejercicio ("caminar", "correr", etc.) vinculada al parámetro de BII exercise.name de la función START_EXERCISE. Si la expresión de un usuario coincide con una entidad, el ID shortcutId se pasa al intent en lugar del valor de la consulta del usuario sin procesar.

  Los atajos de Entity no definen los atributos intent, shortLabel ni longLabel, por lo que te recomendamos que no los uses en superficies proactivas. Si deseas obtener información detallada, consulta Inventario intercalado para Acciones en apps.

Esquema de funciones

En la siguiente tabla, se describe el esquema de Acciones en apps para los elementos de capability en shortcuts.xml. Cuando incluyes una etiqueta, todos sus atributos son obligatorios, a menos que estén marcados como "opcional".

Descripción del esquema de funciones

En esta sección, se describen los elementos del esquema de capability.

<capability>

Es un capability que define el intent de Acción en la app que admite tu app. Cada elemento de <capability> de tu archivo shortcuts.xml debe proporcionar al menos una etiqueta <intent> para controlar la entrega de la acción.

Atributos:

• android:name: Es el ID de acción del intent integrado (por ejemplo, [actions.intent.GET_FOOD_OBSERVATION][]). Si deseas obtener una lista de los intents integrados compatibles, consulta la referencia de intents integrados.
• app:queryPatterns: Es un recurso de arrays de strings de consultas que se esperan del usuario para este intent. Este atributo solo se aplica a intents personalizados, ya que los BIIs ya incluyen modelos de las formas comunes en que los usuarios expresan las tareas que intentan realizar o la información que buscan.

<intent>

Es un elemento intent de Android que define el modo en que se debe entregar una consulta del usuario con la función integrada de la app. Los desarrolladores pueden proporcionar varias etiquetas <intent> en un capability. Asistente intenta entregar una consulta del usuario con la primera etiqueta <intent> en una capability para la que se proporcionan todos los parámetros obligatorios.

Atributos:

• android:action: Es el tipo de Action del intent. El valor predeterminado es ACTION_VIEW.
• android:targetClass: Es la clase de la Actividad de destino (por ejemplo, "com.example.exercise.ExerciseActivity").
• android:targetPackage: Es el paquete que contiene la clase de la Actividad de destino (por ejemplo, "com.example.exercise).
• android:data: <url-template> reemplaza este campo si esa etiqueta se declara en el intent.

<url-template>

Es la plantilla para crear un URI de vínculo directo que se abrirá en el dispositivo. La plantilla se puede expandir con parámetros de intents integrados si todos los parámetros necesarios para ella están disponibles. Si deseas ver ejemplos de la plantilla de URL HTTP, consulta el artículo de Wikipedia sobre plantillas de URL. El formato de la plantilla sigue la especificación de plantillas de URI del RFC6570.

Estos son algunos ejemplos de valores de plantilla de URL:

Si deseas obtener más información sobre la configuración de las plantillas de URL, consulta Plantillas de URL en la entrega.

<extra>

Esta etiqueta define datos adicionales para un intent. En el caso de Acciones en apps, este campo solo se usa para habilitar [invocación de apps en primer plano][] para una capability.

<parameter>

Esta etiqueta asigna un parámetro BII a valores de parámetros de intent. Para obtener más información, consulta el artículo sobre datos de parámetros y coincidencias.

Atributos:

• android:name: Es el nombre del parámetro de BII que se asociará con este parámetro de intent. El nombre debe ser un campo de nivel de hoja del parámetro de BII (por ejemplo, foodObservation.aboutFood.name).
• android:key: Es la clave definida por el desarrollador de un valor del parámetro de BII. Por ejemplo, puedes definir contact_name para el parámetro de BII de message.recipient.name.
• android:mimeType: Es el tipo MIME del parámetro, como text/*. Este campo solo es obligatorio para los parámetros de intents personalizados.
• android:required: Este atributo declara si la consulta del usuario debe incluir este parámetro para que el intent se use en la entrega. Si el parámetro no está disponible, Asistente intenta entregar la consulta del usuario mediante el siguiente intent definido para la capability.

<shortcut-fulfillment>

Esta etiqueta especifica que se usará un intent definido en un atajo de inventario intercalado para un parámetro dado a fin de realizar la entrega. Para obtener más detalles, consulta Entrega con intents de atajo.

<parameter> (para <shortcut-fulfillment>)

Es un atributo opcional que asigna un solo parámetro de BII a la entrega de atajos del inventario intercalado. Para obtener más detalles, consulta Entrega con intents de atajo.

Atributo:

• android:name: Es el nombre del parámetro de BII que se asociará a la entrega de atajos del inventario intercalado. El nombre debe ser un campo de nivel de hoja del parámetro de BII (por ejemplo, menuItem.name).

<slice>

Permite que Asistente incorpore el resultado de una consulta que coincida con esta capability como una Slice de Android. Si deseas obtener más información, consulta el artículo para integrar Acciones en apps con Slices de Android.

Esquema de atajos

En la siguiente tabla, se describen los atributos de los elementos de shortcut que se usan para habilitar la función de Acciones en apps. Cuando incluyes una etiqueta, todos sus atributos son obligatorios, a menos que estén marcados como "opcional".

Descripción del esquema de atajos

En esta sección, se describen los elementos del esquema de shortcut.

<shortcut>

Es un <shortcut> de Android definido en shortcuts.xml con ciertos atributos que resultan relevantes para Acciones en apps. Se puede hacer referencia a los valores de string para los campos shortcutShortLabel y shortcutLongLabel a través de los recursos de strings del APK.

Atributos:

• android:shortcutId: Es el identificador de este atajo.
• android:shortcutShortLabel: Es el recurso de string que representa una frase breve de atajo. Por ejemplo, "@string/callDavidShort", que representa el valor "Llamar a David".
• android:shortcutLongLabel: Es el recurso de strings que representa una frase larga de atajo. Por ejemplo, "@string/callDavidLong", que representa el valor "Realizar una llamada de audio a David".

<intent>

Esta etiqueta indica el intent de Android asociado a este atajo. Este intent se ejecuta cuando un usuario inicia este atajo usando la voz o gestos táctiles.

Los atributos del intent de shortcut son idénticos a aquellos del intent de capability.

<capability-binding>

Esta etiqueta asocia un shortcut con una capability de Acciones en apps. Si agregas este elemento a un shortcut, se habilitará la entrega por voz con Assistant.

Atributos:

• android:key: Es el atributo android:name de la capability a la que está vinculado este shortcut (por ejemplo, actions.intent.START_EXERCISE).

<parameter-binding>

Es un atributo opcional que asocia un shortcut a un único parámetro de una capability de Acciones en apps. Si se define un atributo parameter-binding para un shortcut, el atajo se podrá usar a fin de proporcionar una entidad de inventario intercalado a un parámetro de BII. Si deseas obtener más detalles, consulta Inventario intercalado para Acciones en apps.

Atributos:

• android:key: Es el nombre del parámetro de BII de la capability al que se asociará este atajo (por ejemplo, exercise.name).
• android:value: Es el valor de la entity. Puede ser una única entity o una lista de recursos.

<extra>

Son los datos del paquete extra para el atajo. Los datos sameAs son los únicos relevantes para los elementos de shortcut de Acciones en apps. La URL de sameAs alude a una página web de referencia que identifica la entidad inequívocamente. Se usa para especificar un valor de tipo enum solo si el tipo de parámetro de intent es un subtipo de schema.org/Enumeration. Es obligatorio para los campos de parámetros cuyos tipos son subtipos de schema.org/Enumeration (por ejemplo, MealTypeBreakfast).

Atributos:

• android:key: El valor admitido para Acciones en apps es sameAs.
• android:value: Es el valor de URL de sameAs.

Si deseas obtener más detalles, consulta el artículo para hacer coincidir valores de parámetros enumerados.

Opciones de entrega de intents

Debes definir los elementos de intent dentro de una etiqueta <capability> a fin de declarar la forma en la que Asistente responderá a los comandos por voz del usuario (o los entregará) que coincidan con esa función. Existen varias maneras de configurar el modo en el que un intent inicia un destino de entrega en tu app en función de la estructura de la navegación de la app.

Están disponibles las siguientes opciones de entrega:

• Intents explícitos: Inicia un componente de app específico definiendo los atributos targetClass y targetPackage para el intent. Este es el método recomendado para la entrega de Acciones en apps.

• Vínculos directos: Inicia los destinos de la app con vínculos directos de Android mediante la definición de una etiqueta <url-template> en el elemento del intent. Este método resulta útil si la navegación de tu app ya se basa en vínculos directos.

• Datos de intents: Puedes proporcionar un URI de entrega en el atributo intent del android:data. Este campo se reemplaza por los datos de <url-template> si esa etiqueta también se define dentro del intent.

Coincidencias y datos de parámetros

De forma predeterminada, Asistente envía parámetros de BII extraídos de la consulta del usuario a tu app como datos extra del intent de Android definido en la capability.

De manera alternativa, puedes declarar una etiqueta <url-template> en la capability que contiene marcadores de posición para parámetros dinámicos. Esta plantilla se asigna a una de tus actividades de Android mediante una URL de App Links, un esquema personalizado o una URL basada en intents.

Cómo usar intents adicionales

En el siguiente ejemplo, se muestra un intent explícito definido para la entrega de una capability:

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

Según el ejemplo anterior, para una consulta del usuario como "Hey Google, inicia mi actividad de correr", la app recibe un intent que invoca el componente targetPackage, targetClass. El componente recibe un objeto Extra con key = "exercise", value = "Running".

Cómo usar una plantilla de URL para vínculos directos de Android

Si tu app ya puede controlar URLs vinculadas a ella, con parámetros dinámicos, puedes definir una <url-template> en el intent a fin de generar vínculos directos de Android para la entrega. En el siguiente ejemplo, se define una <url-template>:

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

Según el ejemplo anterior, para una consulta del usuario como "Hey Google, inicia mi actividad de correr", la app recibe la URL generada: "myapp://start?exercise=Running".

Para asignar el parámetro de BII a una posición en la URL, usa el atributo android:name de la etiqueta <parameter>. Este atributo corresponde al valor de android:key en la plantilla de URL que quieres sustituir por la información del usuario. El valor de android:key debe estar presente en tu <url-template> y escribirse entre llaves ({}).

Cómo hacer coincidir los valores de los parámetros enumerados

Algunos parámetros de BII proporcionan valores enumerados a tu intent de entrega, por ejemplo, los valores de texto compatibles del BII RECORD_FOOD_OBSERVATION. Para estos parámetros, Asistente asocia la consulta del usuario ("Desayuno") a una entidad cuyo valor sameAs coincide con la URL del esquema de enumeración (https://schema.googleapis.com/MealTypeBreakfast). A fin de asociar los valores de tipo enum con una entity compatible, debes declarar una asociación de tipo sameAs en tu shortcut. En el siguiente ejemplo, se muestra una asociación sameAs para un atajo de entidad intercalada:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

En el ejemplo anterior, si la función RECORD_FOOD_OBSERVATION activa una coincidencia para el tipo de comida de "desayuno", se envía el siguiente Extra con el intent de entrega:

• key = "for_meal"
• value = "meal_breakfast"

Funciones

Las siguientes funciones de Acciones en apps están disponibles en shortcuts.xml.

Inventario intercalado para Acciones en apps

Para algunos parámetros de BII, los atajos se pueden usar a fin de guiar la extracción de entidades en un conjunto de entidades compatibles especificadas en el archivo shortcuts.xml, que se conocen como inventario intercalado. Para obtener más detalles, consulta Inventario intercalado.

Intents personalizados

Se pueden declarar intents personalizados en shortcuts.xml para habilitar por voz las funciones de tu app que no coincidan con los BII disponibles. Si bien, en términos funcionales, son similares a una definición de BII, los intents personalizados requieren dos atributos adicionales en shortcuts.xml:

• app:queryPatterns: Es el recurso de arrays que declara los diferentes patrones de consulta de un intent personalizado.

• android:mimeType: Es el tipo de parámetro de un intent personalizado. Este campo no es obligatorio para los BII, en los que el tipo de parámetro es un dato conocido. Para los parámetros de intents personalizados, se debe declarar un tipo semántico compatible.

Para obtener más detalles, consulta Intents personalizados.