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ê oferece ao usuário um caminho claro e simples para voltar às atividades mais utilizadas no app sem que ele precise configurar um atalho manualmente.

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 e pergunta se o atalho pode 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 seu app com Ações no app.

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

  • 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, lookupShortcut vai informar o motivo.

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

  • 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 na tag <queries> no 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.

  • Usar a versão mais recente do Google app.

  • Ter o Android 6.0 (API de nível 23) ou versões mais recentes

Limitações conhecidas

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 implementar as sugestões, é necessário atualizar o arquivo build.gradle, configurar o cliente de sugestões e definir as sugestões a serem oferecidas aos usuários.

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

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

    Neste exemplo:

    • 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 a ser sugerido é válido e, opcionalmente, se ele já existe.

    1. Crie uma intent de atalho de app. Ela representa o atalho que você quer sugerir a um usuário. O exemplo a seguir cria uma intent para um atalho para iniciar um exercício.

      Kotlin

      val exercise = mapOf(
    "@type" to "Exercise",
    "@context" to "http://schema.googleapis.com",
    "name" to "Running",
)

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

      Java

        Map exercise = new HashMap<>();
  exercise.put("@type", "Exercise");
  menuItem.put("@context", "http://schema.googleapis.com");
  menuItem.put("name", "Running");

  AppShortcutIntent appShortcutIntent =
      AppShortcutIntent.builder()
          .setIntentName("actions.intent.START_EXERCISE")
          .setPackageName("my.app.package")
          .setIntentParamName("exercise")
          .setIntentParamValue(exercise)
          .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 creating a shortcut
} else {
    // App can remind the user that they have a shortcut for this app action
}

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
  .addOnSuccessListener(shortcutLookupResult -> {
    if (!shortcutLookupResult.isShortcutPresent()) {
      // App can suggest creating a shortcut
    } else {
      // App can remind the user that they have 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. Existem dois métodos que podem ser usados para criar uma sugestão:

    • createShortcutSuggestionIntent: retorna uma intent do Android usada para iniciar a atividade de sugestão de atalho no contexto do seu app.

      Kotlin

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

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

      Java

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

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

      Nesse exemplo, PHRASE é a fala que você sugere ao usuário como um atalho. Por exemplo, se você quer que o usuário para dizer "Ok Google, começar uma corrida" como atalho, substitua PHRASE com "start a run".

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand("start a run")
    .build()

      Java

      AppShortcutSuggestion exerciseShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("start a run")
        .build();

    • createShortcutSettingsIntent: retorna uma intent do Android que direciona o usuário à 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.

Solução de problemas com sugestões

Esta seção lista problemas e exceções que podem ser encontrados ao sugerir atalhos.

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

Devido à filtragem de visibilidade de pacotes, o erro "GoogleInstallationUnsupportedException: não é possível se vincular ao serviço" pode ocorrer 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 os dados de atalho dela 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.