As Ações no app permitem que os usuários iniciem funcionalidades no seu app Android pedindo ao Google Assistente ou usando atalhos do Android sugeridos pelo Assistente. Estas são as principais etapas para estender seu app Android com Ações no app:
- Identifique o recurso do app a ser acionado e a intent integrada (BII) correspondente.
- Forneça detalhes de fulfillment para a BII.
- Envie atalhos da Ação do app ao Google Assistente.
- Teste uma prévia das Ações no app em um dispositivo.
- Crie uma versão de teste do app.
- Solicite a análise e implantação das Ações no app.
Você também pode definir atalhos dinâmicos que são fornecidos ao Google Assistente para que ele possa sugeri-los aos usuários. Crie uma Ação no app de exemplo seguindo o codelab de Ações no app.
Requisitos
Antes de começar a desenvolver Ações no app, verifique se você e seu app atendem aos seguintes requisitos:
- Você precisa ter uma Conta do Google com acesso ao Google Play Console.
- Seu app precisa ser publicado na Google Play Store, porque as Ações no app só estão disponíveis para apps publicados nela. Além disso, confira se o app não se destina ao uso em um perfil de trabalho, já que as Ações no app não têm suporte do Google Play gerenciado.
- Você precisa de um dispositivo físico ou virtual para testar as Ações no app.
- Você precisa da versão mais recente do Android Studio.
- Você precisa usar a mesma Conta do Google para fazer login no Android Studio, no Google app no seu dispositivo de teste e no Google Play Console.
- É necessário configurar o Google Assistente no dispositivo de teste e tocar no botão home e mantê-lo pressionado.
Combinar intents integradas com a funcionalidade do app
Identifique a funcionalidade do app Android que os usuários podem acessar com uma solicitação falada e consulte a referência de intents integradas para encontrar BIIs adequadas para seus casos de uso. As BIIs modelam as consultas dos usuários para as tarefas que eles querem realizar. Portanto, procure BIIs que correspondam às principais funcionalidades e fluxos de usuários do app.
Existem BIIs comuns que quase todos os apps Android podem usar, como estender
a pesquisa no app ao Google Assistente com a BII actions.intent.GET_THING
ou permitir que os usuários iniciem recursos específicos com a voz,
implementando a BII actions.intent.OPEN_APP_FEATURE
.
Há também BIIs que permitem casos de uso vertical ou específicos de uma categoria. Por
exemplo, um app de pedidos de comida pode usar a BII
actions.intent.ORDER_MENU_ITEM
.
Para garantir uma ótima experiência do usuário e evitar possíveis atrasos na aprovação, verifique se cada BII implementada é relevante para a funcionalidade no app.
As Ações no app funcionam iniciando intents do Android no app Google Assistente para levar
os usuários diretamente a um conteúdo específico no app. Você pode definir intents para
iniciar uma atividade explicitamente especificando os campos
targetClass
e targetPackage
. Se o app já implementa URLs de link direto do Android,
você pode configurar a intent para usar um link direto para o
fulfillment. Para saber mais, consulte a seção Testar os links diretos da
atividade.
Fornecer detalhes de fulfillment para intents integradas
A maior parte do desenvolvimento de uma Ação no app é declarar um recurso no
arquivo de recursos shortcuts.xml
do app Android, em que você
especifica a BII selecionada e o fulfillment correspondente. Uma BII modela a
consulta do usuário para uma tarefa e uma intent de fulfillment fornece ao Google Assistente
informações sobre como executar a tarefa.
No arquivo shortcuts.xml
, as BIIs são representadas como elementos <capability>
, e cada fulfillment é representado como um elemento <intent>
:
<shortcuts>
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.app"
android:targetClass="com.example.app.browse">
<parameter
android:name="menuItem.name"
android:key="query">
</parameter>
</intent>
</capability>
Para a maioria das BIIs, extraia parâmetros de intent da consulta do usuário
com base em entidades do schema.org (link em inglês). Em seguida, o app usa esses parâmetros
de BII para direcionar os usuários ao recurso selecionado. Por exemplo, o
código
anterior mapeia o parâmetro de BII menuItem.name
para o parâmetro query
do
Android intent
.
Se você estiver executando ações usando links diretos, use o campo urlTemplate
para definir o URL do link direto gerado pelo Google Assistente:
<shortcuts>
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent android:action="android.intent.action.VIEW">
<url-template android:value="myfoodapp://browse{?query}" />
<parameter android:name="menuItem.name"
android:key="query"
android:mimeType="text/*">
</parameter>
</intent>
</capability>
</shortcuts>
Para detalhes importantes sobre como adicionar Ações no app ao arquivo shortcuts.xml
,
consulte Criar shortcuts.xml
. Essa página também
descreve como especificar os valores de parâmetro esperados pelo app.
Implementar a intent integrada GET_THING
Caso seu app tenha uma função de pesquisa, implemente a
BII actions.intent.GET_THING
para essa função. O Google Assistente poderá encaminhar
os usuários para a função de pesquisa do app que vai receber resultados no app quando eles fizerem consultas
como "Ok Google, pesquise algo de exemplo no app de exemplo".
No arquivo shortcuts.xml
, implemente um <capability>
para
a BII actions.intent.GET_THING
ao
implementar qualquer outra BII. É possível usar vários fulfillments para
GET_THING
, desde que forneça pelo menos um fulfillment que transmita a consulta
do usuário para a função de pesquisa do app.
Confira um exemplo de como adicionar a BII actions.intent.GET_THING
em
shortcuts.xml
:
<capability android:name="actions.intent.GET_THING">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.MySearchActivity">
<parameter android:name="thing.name" android:key="query" />
</intent>
</capability>
Na Activity
de pesquisa, extraia a consulta de pesquisa dos dados extras da
intent
e a transmita para a função de pesquisa do app. No código anterior, a
consulta de pesquisa, transmitida como a chave query
, é mapeada para o parâmetro de BI
"thing.name"
. Em seguida, faça uma pesquisa com a consulta e mostre os resultados na
interface do usuário.
Opcional: enviar atalhos da Ação no app ao Google Assistente
Depois de definir um capability para a ação, os usuários podem iniciá-la dizendo algo como "Ok Google, peça uma pizza no app de exemplo". O Google Assistente pode sugerir atalhos do Android para suas ações aos usuários em momentos relevantes, permitindo que eles descubram e reproduzam suas ações. O Google Assistente pode sugerir atalhos dinâmicos e estáticos.
Para enviar atalhos dinâmicos ao Google Assistente, use a biblioteca de integração Google Shortcuts. Essa biblioteca do Jetpack permite que o Google Assistente use e sugira os atalhos aos usuários no momento adequado.
Confira mais detalhes em Enviar atalhos dinâmicos ao Google Assistente.
Ver uma prévia das Ações no app
Durante o desenvolvimento e os testes, use o plug-in do Google Assistente para Android Studio para testar se as Ações no app funcionam. O plug-in cria uma prévia dessas Ações no Google Assistente para sua Conta do Google. Com a ferramenta de teste, é possível testar os fulfillments em um dispositivo de teste físico ou um emulador, fornecendo BIIs com os parâmetros de entrada que você espera receber dos usuários.
Ao visualizar as Ações no app, você pode acionar consultas por voz no dispositivo. Essa função está disponível apenas para consultas listadas na referência de BIIs das Ações no app. Use o acionamento por voz apenas para demonstração, não para testes regulares.
Teste seu app no modo rascunho usando as ferramentas para desenvolvedores do Google Play Console antes de enviá-lo para revisão. Para mais informações sobre como usar o Google Play Console para implantar um rascunho do app, consulte Preparar e lançar uma versão.
Criar uma versão de teste
Quando estiver tudo pronto para testar as Ações no app com outros testadores, crie uma versão de teste interna ou fechada do app. Por padrão, os testadores da versão interna e fechada podem acessar as Ações no app que já foram analisadas e aprovadas.
Para conceder acesso de teste a todas as Ações no app, incluindo ações não aprovadas, instrua os testadores a participar do Grupo do Google do Programa de desenvolvimento de Ações no app. Os membros desse grupo têm acesso a todas as Ações no app em versões de teste fechado e interno, sem precisar criar prévias usando a ferramenta de teste de Ações no app. Pode levar até três horas depois de entrar no grupo para que o acesso seja disponibilizado.
Solicitar a análise e implantação das Ações no app
As Ações no app não ficam disponíveis para os usuários dos seus apps publicados ou versões de teste
abertos até que sejam revisadas e aprovadas. A análise das Ações no app não
afeta a análise e o status da implantação do app Android no Google Play. Mesmo que
o envio do app seja aprovado e publicado na Play Store, o
shortcuts.xml
pode estar sendo analisado pelo Google. As Ações no app não vão funcionar para seus
usuários finais até que essa análise também seja aprovada.
Quando você implanta seu app, as Ações no app ficam ativadas. No entanto, as versões reimplantadas estão sujeitas a análise pelo Google. Se a nova versão não funcionar corretamente ou incluir violações da política, o Google se reserva o direito de desativar as Ações no app.
Para enviar suas Ações no app para análise, faça o seguinte:
Aceite os Termos de Serviço das Ações no app no Google Play Console (Configurações avançadas > Ações no app):
Faça upload do seu app, contendo
shortcuts.xml
, no Google Play Console para publicação normalmente.Depois de fazer upload do app, o Google entra em contato por e-mail na sua conta do Play Console com mais informações sobre o status da análise das Ações no app. Você também pode entrar em contato com o suporte ao desenvolvedor do Google Assistente se tiver dúvidas sobre o status da análise das Ações no app. No formulário de contato, insira o ID do pacote do app e escolha Análise de Ações no app na caixa de seleção Como podemos ajudar?.
Opcional: teste os links diretos da atividade
Para usar um link direto para iniciar uma Activity
com uma Ação no app, o Activity
precisa ser configurado com URLs de link direto e ter um filtro de intent correspondente no
manifesto do app Android.
Para testar se as atividades podem ser acessadas e acionadas usando
Ações no app com links diretos, execute o seguinte comando adb
:
$ adb shell am start -a android.intent.action.VIEW -d "AppLinksURL"
Por exemplo:
$ adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/deeplink"
Se a atividade não for iniciada corretamente com o comando adb
,
confira o seguinte:
- No arquivo de manifesto do app, a atividade tem
android:exported=true
para que ela possa ser iniciada usando intents do Google Assistente. - Se você usa URLs de links do app, siga todas as etapas em Como processar Links do app Android.
Políticas de Ações no app
As Ações no app precisam obedecer a políticas específicas para garantir que os usuários que as acionam recebam a experiência esperada. Consulte essas políticas antes de enviar seus apps para proporcionar a melhor experiência do usuário e evitar atrasos ou rejeições nas avaliações da Play Store.
Direcionar usuários para conteúdo pretendido
Os parâmetros e/ou as intents integradas (BIIs) das Ações no app só podem direcionar os usuários à ação relevante e esperada. Isso pode incluir conteúdo no app, de sites ou informações mostradas em frações ou widgets, desde que a experiência seja pretendida pelo usuário.
Por exemplo, implementações da BII
ORDER_MENU_ITEM
ajudam os usuários a iniciar um pedido para o item de menu ou tipo de culinária especificado. A única exceção a essa política é quando a BIIOPEN_APP_FEATURE
direciona os usuários para a tela inicial do app.Direcionar usuários a conteúdo relevante na Web
Se os usuários forem redirecionados para o conteúdo de uma página da Web, o site precisará ser relevante para a ação pretendida pelo usuário e ser de propriedade da marca.
Por exemplo, redirecionar os usuários que acionam a BII
GET_RESERVATION
paragoogle.com/travel
, que não pertence à marcaexampledomain.com
do app, é uma violação. Outro exemplo de violação é redirecionar os usuários que acionam sua BIIGET_CALL_HISTORY
paraexampledomain.com/payment
e exigir que eles façam uma compra.Implementar BIIs relevantes de Ações no app
As BIIs implementadas precisam estar diretamente relacionadas ao conteúdo e à funcionalidade do app.
Por exemplo, se o app estiver na categoria da Play Store de comunicações, não implemente a BII
ORDER_MENU_ITEM
, que é recomendada para apps na categoria "Comidas e bebidas".Implementar intents personalizadas relevantes
As consultas definidas para intents personalizadas estão relacionadas ao conteúdo e à funcionalidade do app. Um exemplo de possível violação dessa política é criar a intent
custom.action.intent.GET_RECIPE
com o padrão de consulta associado "Mostrar receitas de burrito" para um app na categoria "Transporte" da Play Store.