Cómo enviar accesos directos dinámicos al Asistente

Los atajos de Android proporcionan a los usuarios métodos rápidos para realizar una acción o acceder a contenido en una app. Asistente puede sugerir proactivamente tus atajos dinámicos de Android a los usuarios en momentos relevantes, lo que les permite descubrir y volver a reproducir tu funcionalidad compatible con voz.

Por ejemplo, puedes enviar un acceso directo para cada nota que crea un usuario en tu app de notas. Para que tus vínculos dinámicos puedan mostrarse en las plataformas de Google, como Asistente, agrega la Biblioteca de Google Shortcuts Integration Jetpack a tu proyecto. Esta biblioteca permite a Asistente tomar los atajos dinámicos que envías con la clase ShortcutManagerCompat, que es un wrapper de Jetpack para la API ShortcutManager.

Cuando usas la biblioteca de integración de atajos de Google en tu app, los atajos dinámicos que envías a Google están visibles para los usuarios como sugerencias de atajos de voz en la app de Asistente. Puedes enviar una cantidad ilimitada de atajos dinámicos a Asistente con el método pushDynamicShortcut() de la biblioteca ShortcutManagerCompat.

Cómo configurar tu proyecto de desarrollo

Para agregar la funcionalidad de accesos directos dinámicos a tu app, necesitas la Biblioteca de Google Shortcuts Integration, que es una biblioteca de Android Jetpack. En esta sección, se describe cómo configurar tu proyecto de desarrollo de apps para que incluya esta biblioteca.

Para agregar esta biblioteca de Jetpack y configurar tu proyecto, sigue estos pasos:

Actualiza el archivo gradle.properties de modo que sea compatible con las bibliotecas de Jetpack:

gradle.properties

android.useAndroidX=true
# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true

Agrega las dependencias de la biblioteca de Jetpack a tu build.gradle:

app/build.gradle
```
dependencies {
 implementation "androidx.core:core:1.6.0"
 implementation "androidx.core:core-google-shortcuts:1.0.1"
 ...
}
```
En el código de muestra anterior, enumeras dos bibliotecas de Jetpack como dependencias. La biblioteca androidx.core:core:1.6.0 contiene la clase ShortcutManagerCompat que usas para enviar atajos dinámicos a Google.

androidx.core:core-google-shortcuts:1.0.1 es la Biblioteca de Google Shortcuts Integration. Esta biblioteca no contiene una API para desarrolladores. Si la agregas como dependencia, permites que Asistente transfiera los atajos dinámicos que envías con la clase ShortcutManagerCompat.

Nota: Visita el explorador de bibliotecas de Jetpack para encontrar las versiones más recientes de las Bibliotecas de Core and Google Shortcuts Integration.

Cómo enviar atajos dinámicos

Si quieres enviar atajos dinámicos aptos para mostrarse en Asistente, primero debes crearlos con la clase ShortcutInfoCompat.Builder().

Luego, envía el atajo con el método ShortcutManagerCompat.pushDynamicShortcut(). Los atajos se envían cada vez que un usuario completa una acción relevante en tu app. El siguiente código de muestra envía un atajo cada vez que un usuario realiza un pedido en una app de entrega de comida:

ExampleOrderActivity

Kotlin

// Define the dynamic shortcut for a menu item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
        "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino")
    )
    .setIntent(intent) // Push the shortcut
    .build()

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo)

Java

// Define the dynamic shortcut for a menu item
Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
      "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino"))
    .setIntent(intent)
    .build();

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

El id al que se hace referencia en el método ShortcutInfoCompat.Builder en el código de muestra anterior define el shortcutId del objeto de acceso directo resultante. Este id debe ser de un literal de cadena único. Para obtener información detallada, consulta la documentación sobre atajos de Android.

En el ejemplo anterior, el método addCapabilityBinding vincula el acceso directo dinámico a un elemento capability del mismo android:name definido en shortcuts.xml. Este método te permite asociar el atajo a un parámetro de intent integrado (BII) semántico.

A veces, los atajos dinámicos se envían sin una asociación con un parámetro BII en particular. Cuando el usuario lo invoca, Asistente activa el intent definido en el atajo para completar la acción. En el siguiente ejemplo, se muestra un atajo dinámico sin asociación de parámetros:

Kotlin

var intent: Intent = Intent(context, DisplayOrderActivity::class.java)
intent.setPackage(this, "com.sample.app")
intent.setAction(Intent.ACTION_VIEW)

var shortcutInfo: ShortcutInfoCompat = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Order coffee")
    .setLongLabel("Order a cup of coffee")
    .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
    .setIntent(intent)
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Java

Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setPackage(this, "com.sample.app");
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
  .setShortLabel("Order coffee")
  .setLongLabel("Order a cup of coffee")
  .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Cómo probar atajos dinámicos con Asistente

Cuando Asistente de Google toma un atajo dinámico correctamente de tu aplicación, el atajo puede aparecer como sugerencia de atajo de voz en la app para Android de Asistente. La app de Asistente sugiere los atajos más recientes enviados por tu app.

Para probar tus atajos dinámicos con Asistente, sigue estos pasos:

Para crear una vista previa de tus Acciones en apps y asegurarte de que tu dispositivo o emulador de prueba esté preparado para las pruebas de acciones, sigue los mismos requisitos de configuración que el complemento de Asistente de Google.
Abre tu app y define un atajo dinámico para enviar. Luego, completa una acción. Por ejemplo, si envías un atajo cada vez que se crea una nota en tu app para tomar notas, crea una nota nueva.
Abre la opción de atajos en la app de Configuración de Asistente en tu dispositivo. Tu atajo dinámico aparece en la lista correspondiente a tu app.