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.
Adicione a dependência da biblioteca
build.gradle
ao projeto.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();
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. 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 a ser sugerido é válido e, opcionalmente, se ele já existe.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 de 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<String, Object> 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 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));
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 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); );
Nesse exemplo, PHRASE é a fala que você sugere ao usuário como um atalho. Por exemplo, se você quiser que o usuário diga "Ok Google, peça meu chá" 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 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); );
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.