Sugerir atalhos usando o SDK de promoção no app

Para promover recursos do seu app e facilitar o uso, você pode sugerir atalhos do Google Assistente aos usuários. Os atalhos do Google Assistente são frases concisas que um usuário pode falar para acionar uma funcionalidade no seu app.

Embora esses atalhos possam ser criados de forma manual pelos usuários, o SDK de promoção no app permite que você os sugira e implemente de maneira proativa. Ao sugerir atalhos, você garante que os usuários tenham caminhos claros e simples para voltar às atividades favoritas deles no app sem o esforço extra de configurar atalhos.

Por exemplo, se um usuário pesquisa "heavy metal para malhar" no seu app de música, você pode sugerir um atalho do Google Assistente diretamente para esses resultados no futuro. Quando você sugere um atalho, uma notificação no app mostra a frase proposta para ele e pergunta ao usuário se o atalho deve ser criado. Neste exemplo, você sugere a frase "ouvir heavy metal para malhar". O usuário aceita a sugestão e pode abrir o atalho dizendo: "Ok Google, ouvir heavy metal para malhar".

Para saber mais sobre como aumentar o público do seu app, consulte Melhorar os apps com Ações no app.

O SDK de promoção no app oferece os seguintes métodos:

  • O lookupShortcut confere se o atalho que você quer sugerir já existe. Eles também verifica se há problemas que impedem a criação do atalho. Se não for possível criar o atalho, o LookupShortcut vai informar o motivo.

  • O createShortcutSuggestionIntent retorna uma intent que pode ser usada para solicitar que o usuário crie o atalho sugerido.

  • O createShortcutSettingsIntent retorna uma intent que pode ser usada para levar o usuário às configurações de Atalho do Assistente do app.

Pré-requisitos e limitações

Esta seção descreve os pré-requisitos e requisitos para usar as sugestões, assim como as limitações que você pode encontrar.

Pré-requisitos de desenvolvimento

Para usar sugestões, seu ambiente de desenvolvimento precisa atender aos seguintes pré-requisitos.

  • Amplie o app Android para usar as Ações no app.

  • Inclua com.google.android.googlequicksearchbox nas tags <queries> do manifesto. Exemplo:

    <manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

  • Use os Android App Bundles para publicar seus apps.

Requisitos do dispositivo

Para testar as sugestões em um dispositivo, ele precisa atender aos seguintes requisitos.

  • Ter a versão mais recente do Google app instalada.

  • Usar o Android M (API de nível 23) ou versão mais recente.

Limitações conhecidas

Esta seção descreve limitações para as sugestões.

Só é possível usar as sugestões em inglês. Para que elas sejam mostradas, os usuários precisam definir esse idioma para o Google Assistente no dispositivo.

Implementar sugestões

Para a implementação, você precisa atualizar o arquivo build.gradle, configurar o cliente de sugestões e definir as sugestões que quer oferecer aos usuários.

Faça o seguinte:

  1. Adicione a dependência da biblioteca ao arquivo build.gradle.

    dependencies {
  ...
  implementation "com.google.assistant.appactions:suggestions:1.0.0"
}

  2. Defina uma instância de AssistantShortcutSuggestionsClient.

    Kotlin

    val shortcutsClient =
  AssistantShortcutSuggestionsClient.builder()
    .setContext(CONTEXT: Context)
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
    .build()

    Java

    AssistantShortcutSuggestionsClient shortcutsClient =
  AssistantShortcutSuggestionsClient.builder()
    .setContext(CONTEXT: Context)
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
    .build();

    Em que:

    • CONTEXT (obrigatório) é o contexto do aplicativo;

    • VERIFY_INTENTS (obrigatório) determina se é necessário verificar cada intent criada ao sugerir atalhos para os usuários. Quando true, as intents criadas por AssistantShortcutSuggestionsClient são verificadas. Se uma intent for inválida, uma exceção será retornada;

    • CUSTOM_EXECUTOR (opcional) é um executor personalizado para executar tarefas assíncronas. Se esse elemento não for informado, o SDK vai usar um executor de linha de execução única para a tarefa.

  3. Use o método lookupShortcut para determinar se o atalho que você quer sugerir é válido e se ele já existe. Recomendamos que você implemente o lookupShortcut para verificar se as intents criadas pelas suas sugestões são válidas, mesmo que você não pretenda conferir os atalhos de usuário existentes.

    1. Crie uma intent de atalho de app. Ela representa o atalho que você quer sugerir a um usuário. O exemplo a seguir descreve um atalho para pedir uma bebida.

      Kotlin

      val menuItem = mapOf(
    "@type" to "MenuItem",
    "@context" to "http://schema.googleapis.com",
    "name" to "Fresh Lemon Honey Jasmine Green Tea",
)

val appShortcutIntent = AppShortcutIntent.builder()
    .setIntentName("actions.intent.ORDER_MENU_ITEM")
    .setPackageName("my.app.package")
    .setIntentParamName("menuItem")
    .setIntentParamValue(menuItem)
    .build()

      Java

        Map menuItem = new HashMap<>();
  menuItem.put("@type", "MenuItem");
  menuItem.put("@context", "http://schema.googleapis.com");
  menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea");

  AppShortcutIntent appShortcutIntent =
      AppShortcutIntent.builder()
          .setIntentName("actions.intent.ORDER_MENU_ITEM")
          .setPackageName("my.app.package")
          .setIntentParamName("menuItem")
          .setIntentParamValue(menuItem)
          .build();

    2. Transmita a intent de atalho para o método lookupShortcut.

      Kotlin

      val result = shortcutsClient.lookupShortcut(appShortcutIntent).await()
if (!result.isShortcutPresent) {
    // app can suggest to create a shortcut
} else {
    // app can remind that the user has a shortcut for this app action
}

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
  .addOnSuccessListener(shortcutLookupResult -> {
    if (!shortcutLookupResult.isShortcutPresent()) {
      // app can suggest to create a shortcut
    } else {
      // app can remind that the user has a shortcut for this app action
    }
  })
  .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));

  4. Crie a sugestão usando a intent de atalho.

    Há dois métodos que você pode usar para criar uma sugestão:

    • createShortcutSuggestionIntent retorna uma intent do Android que você usa para iniciar a atividade de sugestão de atalhos no contexto do seu app.

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand(PHRASE: String)
    .build()

val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

      Java

        AppShortcutSuggestion orderShortcut =
      AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build();

  shortcutsClient.createShortcutSuggestionIntent(orderShortcut)
      .addOnSuccessListener(intent ->
          getApplication().startActivity(
              intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
      )
      .addOnFailureListener(e ->
          Log.e(TAG, "Failed to get shortcut suggestion intent", e);
      );

      Em que PHRASE é a fala que você quer sugerir ao usuário como um atalho. Por exemplo, se você quiser que o usuário diga "Ok Google, peça meu bubble tea" como um atalho, substitua PHRASE por "order my bubble tea".

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand("order my bubble tea")
    .build()

      Java

      AppShortcutSuggestion orderShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("order my bubble tea")
        .build();

    • createShortcutSettingsIntent retorna uma intent do Android que leva o usuário para a interface de configurações de atalho no app Google Assistente.

      Kotlin

      val intent = shortcutsClient.createShortcutSettingsIntent().await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

      Java

        shortcutsClient.createShortcutSettingsIntent()
    .addOnSuccessListener(intent ->
        getApplication().startActivity(
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
    )
    .addOnFailureListener(e ->
        Log.e(TAG, "Failed to get shortcut settings intent", e);
    );

  5. Chame startActivity usando a intent do Android retornada durante a etapa anterior.

Sugestões para solução de problemas

Esta seção lista problemas e exceções que você pode encontrar ao sugerir atalhos.

GoogleInstallationUnsupportedException: não é possível se vincular ao serviço

Devido à filtragem de visibilidade de pacotes, a GoogleInstallationUnsupportedException: Cannot bind to service pode acontecer no Android 11 e em versões mais recentes. Não deixe de incluir com.google.android.googlequicksearchbox na tag <queries> no seu manifesto:

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

"Falha ao verificar a assinatura do APK"

O seguinte erro pode ocorrer se você não enviar o app de produção como um pacote de app:

Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.

Não se esqueça de enviar seu app como um Android App Bundle.

"Falha ao acessar os atalhos do usuário"

A mensagem de erro "Falha ao acessar os atalhos do usuário" pode aparecer caso você tenha adicionado uma conta ao dispositivo recentemente e se os dados de atalho da nova conta ainda não estiverem armazenados em cache no dispositivo.

Para sincronizar os dados de atalhos no dispositivo, adicione ou exclua um atalho usando a interface do app Google Assistente.

A atividade de criação de atalhos é fechada imediatamente sem mostrar nenhum conteúdo

A atividade de criação de atalhos poderá ser fechada sem mostrar conteúdo se você não tiver criado uma prévia usando a Ferramenta de teste das Ações no app ou se ela tiver expirado. Atualize a prévia e tente novamente.