Esegui il push delle scorciatoie dinamiche all'assistente

Le scorciatoie Android offrono agli utenti metodi rapidi per eseguire un'azione o accedere ai contenuti in un'app. L'assistente può suggerire in modo proattivo le scorciatoie dinamiche di Android agli utenti nei momenti pertinenti, in modo che gli utenti possano scoprire e riprodurre facilmente le tue funzionalità vocali.

Ad esempio, puoi eseguire il push di una scorciatoia per ogni nota creata da un utente nella tua app per la creazione di note. Per rendere i link dinamici idonei alla visualizzazione sulle piattaforme Google, come l'Assistente Google, aggiungi la libreria Jetpack di integrazione delle scorciatoie Google al tuo progetto. Questa libreria consente all'assistente di accettare le scorciatoie dinamiche di cui esegui il push utilizzando la classe ShortcutManagerCompat, che è un wrapper Jetpack per l'API ShortcutManager.

Quando utilizzi la libreria di integrazione Scorciatoie Google nell'app, le scorciatoie dinamiche inviate a Google sono visibili agli utenti come suggerimenti di scorciatoie vocali nell'app dell'assistente. Puoi inviare all'assistente un numero illimitato di scorciatoie dinamiche utilizzando il metodo pushDynamicShortcut() della raccolta ShortcutManagerCompat.

Configurare il progetto di sviluppo

Per aggiungere la funzionalità di scorciatoie dinamiche alla tua app è necessaria la libreria di integrazione Scorciatoie Google, che è una libreria Android Jetpack. Questa sezione descrive come configurare il tuo progetto di sviluppo di app per includere questa libreria.

Per aggiungere questa libreria Jetpack e configurare il tuo progetto, segui questi passaggi:

  1. Aggiorna il file gradle.properties per gestire le librerie Jetpack:

    gradle.properties

    android.useAndroidX=true
    # Automatically convert third-party libraries to use AndroidX
    android.enableJetifier=true
    
  2. Aggiungi le dipendenze della libreria Jetpack a build.gradle:

    app/build.gradle

    dependencies {
     implementation "androidx.core:core:1.6.0"
     implementation "androidx.core:core-google-shortcuts:1.0.1"
     ...
    }
    

    Nel codice di esempio precedente, elenchi due librerie Jetpack come dipendenze. La libreria androidx.core:core:1.6.0 contiene la classe ShortcutManagerCompat, che puoi utilizzare per inviare le scorciatoie dinamiche a Google.

    androidx.core:core-google-shortcuts:1.0.1 è la libreria di integrazione delle scorciatoie Google. Questa libreria non contiene API per gli sviluppatori. Aggiungendola come dipendenza, consenti all'assistente di accettare le scorciatoie dinamiche che invii utilizzando la classe ShortcutManagerCompat.

Esegui il push delle scorciatoie dinamiche

Per inviare scorciatoie dinamiche idonee alla visualizzazione sull'assistente, devi prima crearle utilizzando la classe ShortcutInfoCompat.Builder().

Successivamente, esegui il push della scorciatoia utilizzando il metodo ShortcutManagerCompat.pushDynamicShortcut(). Le scorciatoie vengono inviate tramite push ogni volta che un utente completa un'azione pertinente nella tua app. Il seguente codice di esempio invia una scorciatoia ogni volta che un utente effettua un ordine in un'app per la consegna di cibo a domicilio:

AttivitàOrdine di esempio

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

L'elemento id a cui viene fatto riferimento nel metodo ShortcutInfoCompat.Builder nel codice campione precedente definisce il valore shortcutId dell'oggetto scorciatoia risultante. id deve essere un valore letterale stringa univoco. Per maggiori dettagli, consulta la documentazione relativa alle scorciatoie Android.

Nell'esempio precedente, il metodo addCapabilityBinding associa la scorciatoia dinamica a un capability dello stesso android:name definito in shortcuts.xml. Questo metodo consente di associare la scorciatoia a un parametro BII (intent-in-integrato) semantico.

A volte le scorciatoie dinamiche vengono inviate tramite push senza una particolare associazione dei parametri BII. Quando richiamato dall'utente, l'assistente attiva il intent definito nella scorciatoia per completare l'azione. L'esempio seguente mostra una scorciatoia dinamica senza associazione di parametri:

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

Testare le scorciatoie dinamiche con l'assistente

Quando l'Assistente Google riconosce correttamente una scorciatoia dinamica dalla tua applicazione, la scorciatoia può essere visualizzata come suggerimento di scorciatoia vocale nell'app per Android dell'assistente. L'app dell'assistente suggerisce le scorciatoie più recenti inviate dalla tua app.

Per testare le scorciatoie dinamiche con l'assistente, procedi nel seguente modo:

  1. Crea un'anteprima delle azioni app e prepara il dispositivo o l'emulatore di test per le azioni di test seguendo gli stessi requisiti di configurazione del plug-in dell'Assistente Google.
  2. Apri l'app e definisci una scorciatoia dinamica da inviare. Quindi, completa un'azione. Ad esempio, se invii una scorciatoia ogni volta che viene creata una nota nell'app per la creazione di note, puoi crearne una nuova.
  3. Apri Scorciatoie nell'app Impostazioni assistente sul tuo dispositivo. La scorciatoia dinamica viene visualizzata nell'elenco della tua app.