Cómo agregar funciones

Las funciones de shortcuts.xml te permiten declarar los tipos de acciones que los usuarios pueden realizar para iniciar tu app y pasar directamente a una tarea específica. Por ejemplo, las Acciones en apps de Asistente de Google usan funciones para permitir que los desarrolladores extiendan funcionalidades dentro de la app a intents integrados (BII, por su sigla en inglés), lo que permite a los usuarios activar y controlar esas funcionalidades mediante comandos por voz. Una función está compuesta por el nombre de la acción y un intent orientado al destino en tu app, que resuelve el intent del usuario.

Cómo definir funciones en shortcuts.xml

Define elementos capability en un archivo de recursos shortcuts.xml en tu proyecto de desarrollo de apps para Android. Para definir un elemento capability, haz lo siguiente:

  1. Para crear un recurso shortcuts.xml, sigue las instrucciones de Cómo crear accesos directos estáticos.

  2. Luego, incluye en tu función la siguiente información obligatoria:

    • Nombre de la función: Es la acción que quieres que admita tu app. Consulta la documentación de los componentes de la funcionalidad que requiere definiciones de función. Los comandos habilitados por voz de Acciones en apps usan el BII Action ID para los nombres de las funciones, que se encuentran en la referencia de intents integrados. Por ejemplo, el BII GET_THING indica que su Action ID es actions.intent.GET_THING.

    • Destino de la app: Es el destino de tu app que se inicia para cumplir con la solicitud del usuario. Define los destinos de la app con los elementos intent anidados en capability.

    • Mapeos de parámetros: Cada intent puede contener parámetros que se pasarán como datos extra del intent. Por ejemplo, cada BII de Acciones en apps incluye campos que representan la información que los usuarios suelen proporcionar en las consultas que activan el BII.

En el siguiente ejemplo, se muestra una definición de función en shortcuts.xml para actions.intent.START_EXERCISE, un BII que permite a los usuarios utilizar comandos por voz con Asistente para iniciar un entrenamiento en una app de fitness:

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.START_EXERCISE">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.sampleApp"
      android:targetClass="com.example.sampleApp.ExerciseActivity">
      <parameter
        android:name="exercise.name"
        android:key="exerciseType"/>
    </intent>
  </capability>
</shortcuts>

En el ejemplo anterior, el atributo <capability> android:name hace referencia al BII START_EXERCISE. Si un usuario invoca este BII y le pregunta al Asistente: "Hey Google, inicia una caminata en AppDeEjemplo", Asistente completará la solicitud del usuario con la información proporcionada en el elemento intent anidado. El intent de este ejemplo define los siguientes detalles:

  • El android:targetPackage establece el paquete de la aplicación de destino para este intent.
  • El campo android:targetClass especifica la actividad de destino: com.example.sampleApp.ExerciseActivity.
  • El intent parameter declara la compatibilidad con un parámetro de intent integrado exercise.name y cómo pasar el valor del parámetro, recopilado del usuario, como datos adicionales en intent.

Cómo asociar accesos directos con una función

Una vez que hayas definido una función, podrás extender su funcionalidad asociando accesos directos estáticos o dinámicos. La forma en que los accesos directos se vinculan a una capability depende de la función que se implemente y de las palabras reales incluidas en la solicitud de un usuario. Por ejemplo, supongamos que un usuario inicia una caminata en tu app de fitness preguntándole al Asistente: "Hey Google, inicia una caminata en AppDeEjemplo". Asistente podría usar un acceso directo a fin de iniciar una instancia de una capability que defina una entidad de ejercicio válida "caminata" para el parámetro exercise.name.

Para obtener más información sobre cómo asociar accesos directos a las Acciones en apps, consulta Descripción general de las Acciones en apps.