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, oLookupShortcut
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:
Adicione a dependência da biblioteca ao arquivo build.gradle.
dependencies { ... implementation "com.google.assistant.appactions:suggestions:1.0.0" }
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. Quandotrue
, as intents criadas porAssistantShortcutSuggestionsClient
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.
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 olookupShortcut
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.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(); 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));
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, substituaPHRASE
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); );
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.