Enviar atalhos dinâmicos ao Google Assistente

Os atalhos do Android oferecem aos usuários métodos rápidos para executar uma ação ou acessar conteúdo em um app. O Google Assistente pode sugerir proativamente seus atalhos dinâmicos do Android para os usuários em momentos relevantes, permitindo que os usuários descubram e reproduzam facilmente a funcionalidade ativada por voz.

Por exemplo, você pode enviar um atalho para cada nota que um usuário cria no seu app de anotações. Para tornar os links dinâmicos qualificados para exibição nas plataformas do Google, como o Google Assistente, adicione a biblioteca Google Shortcuts Integration Jetpack ao seu projeto. Essa biblioteca permite que o Google Assistente use atalhos dinâmicos enviados por você usando a classe ShortcutManagerCompat, que é um wrapper do Jetpack da API ShortcutManager.

Quando você usa a biblioteca Google Shortcuts Integration no seu app, os atalhos dinâmicos que você envia ao Google ficam visíveis para os usuários como sugestões de atalhos de voz no app Google Assistente. Você pode enviar um número ilimitado de atalhos dinâmicos ao Google Assistente usando o método pushDynamicShortcut() da biblioteca ShortcutManagerCompat.

Configurar seu projeto de desenvolvimento

Para adicionar a funcionalidade de atalhos dinâmicos ao app, é necessário ter a biblioteca Google Shortcuts Integration, que é uma biblioteca do Android Jetpack. Esta seção descreve como configurar seu projeto de desenvolvimento de apps para incluir essa biblioteca.

Para adicionar essa biblioteca do Jetpack e configurar seu projeto, siga estas etapas:

  1. Atualize o arquivo gradle.properties para processar bibliotecas do Jetpack:

    gradle.properties

    android.useAndroidX=true
    # Automatically convert third-party libraries to use AndroidX
    android.enableJetifier=true
    
  2. Adicione as dependências da biblioteca do Jetpack ao build.gradle:

    app/build.gradle

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

    No exemplo de código anterior, você lista duas bibliotecas do Jetpack como dependências. A biblioteca androidx.core:core:1.6.0 contém a classe ShortcutManagerCompat, que você usa para enviar atalhos dinâmicos ao Google.

    A androidx.core:core-google-shortcuts:1.0.1 é a biblioteca Google Shortcuts Integration. Essa biblioteca não contém APIs voltadas para o desenvolvedor. Ao adicioná-la como uma dependência, você permite que o Google Assistente use os atalhos dinâmicos enviados usando a classe ShortcutManagerCompat.

Enviar atalhos dinâmicos

Para enviar atalhos dinâmicos qualificados para exibição no Google Assistente, primeiro crie o atalho usando a classe ShortcutInfoCompat.Builder().

Em seguida, envie o atalho usando o método ShortcutManagerCompat.pushDynamicShortcut(). Os atalhos são enviados sempre que um usuário conclui uma ação relevante no app. O exemplo de código abaixo envia um atalho sempre que um usuário faz um pedido em um 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);

O id mencionado no método ShortcutInfoCompat.Builder no exemplo de código anterior define o shortcutId do objeto de atalho resultante. Esse id precisa ser um literal de string exclusivo. Para ver mais detalhes, consulte a documentação da Android Shortcuts.

No exemplo anterior, o método addCapabilityBinding vincula o atalho dinâmico a um elemento capability do mesmo android:name definido em shortcuts.xml. Esse método permite associar o atalho a um parâmetro de intent integrada (BII, na sigla em inglês) semântico.

Às vezes, os atalhos dinâmicos são enviados sem nenhuma associação específica de parâmetros de BII. Quando invocado pelo usuário, o Google Assistente aciona o elemento intent definido no atalho para realizar a ação. O exemplo abaixo mostra um atalho dinâmico sem associação de parâmetro:

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

Testar atalhos dinâmicos com o Google Assistente

Quando o Google Assistente recebe um atalho dinâmico do seu aplicativo, ele pode aparecer como uma sugestão de atalho de voz no app Google Assistente para Android. O app Google Assistente sugere os atalhos mais recentes enviados pelo seu app.

Para testar os atalhos dinâmicos com o Google Assistente, siga estas etapas:

  1. Crie uma prévia das Ações no app e prepare o dispositivo ou emulador de teste para testar ações seguindo os mesmos requisitos de configuração do plug-in do Google Assistente.
  2. Abra seu app e defina um atalho dinâmico para enviar. Em seguida, conclua uma ação. Por exemplo, se você enviar um atalho sempre que uma nota for criada no app de anotações, crie uma nova.
  3. Abra Atalhos no app Configurações do Google Assistente no seu dispositivo. O atalho dinâmico é mostrado na lista do app.