1. Visão geral
Com as Ações no app, as pessoas podem abrir recursos específicos de apps no Google Assistente para expandir o alcance do seu app Android. Desenvolvedores Android podem implementar recursos para que o Google Assistente saiba o tipo de funcionalidade disponível aos usuários e como você quer atender a essas solicitações.
No primeiro codelab das Ações no app, você aprendeu a estender o Google Assistente a um exemplo de app fitness implementando intents integradas (BII, na sigla em inglês) da categoria Saúde e fitness. As BIIs estão organizadas em categorias que representam os tipos de tarefas que os usuários costumam pedir para o Google Assistente.
Neste codelab, você vai aprender a adicionar Ações no app usando BIIs da categoria "comum" de BIIs, que representa tarefas corriqueiras que quase todos os apps Android podem realizar.
Este codelab envolve conceitos de nível intermediário para desenvolvimento de Ações no app. Por isso, convém ter experiência prévia em desenvolvimento de apps Android e em implementação de intents do Android.
O que você criará
Neste codelab, você vai adicionar duas BIIs comuns a um exemplo de app de lista de tarefas para que os usuários possam pedir que o Google Assistente:
- Acesse os recursos no app com a BII do
actions.intent.OPEN_APP_FEATURE
. - Pesquise conteúdo usando a pesquisa no app com a BII do
actions.intent.GET_THING
.
Figura 1. Três telas progressivas do Google Assistente mostrando tarefas ativas em um app.
O que você aprenderá
Você vai aprender a usar as BIIs comuns para estender o Google Assistente à maioria dos apps Android e a testar BIIs comuns com o plug-in do Google Assistente para o Android Studio.
Pré-requisitos
- Um terminal com git instalado para executar comandos do shell.
- A versão estável mais recente do Android Studio.
- Um dispositivo Android físico ou virtual com acesso à Internet e à Google Play Store para testar suas ações.
- Login no Android Studio, no Google app e no Google Assistente do dispositivo de teste com a mesma Conta do Google.
Neste codelab, você vai usar um dispositivo Android (físico ou virtual) para testar ações. Dispositivos físicos precisam estar conectados à sua máquina de desenvolvimento local. É preciso fazer login no Google app no dispositivo e no Android Studio usando a mesma Conta do Google. O app Google Assistente também precisa estar instalado no dispositivo.
2. Entender como funciona
As Ações no app conectam usuários do Google Assistente ao seu app Android. Mas como elas funcionam?
Quando um usuário indica ao Google Assistente que gostaria de usar seu app, o Assistente procura Ações no app registradas em um arquivo shortcuts.xml
. Nele estão os recursos do app, que vinculam uma intent integrada ou personalizada do Google Assistente a uma intent ou link direto do Android.
O Google Assistente analisa o que uma pessoa informa quando pesquisa algo e faz a correspondência a uma intent de Ações no app. Neste codelab, será uma BII. Com o arquivo shortcuts.xml
no seu app Android, o Google Assistente fica sabendo quais recursos você pode usar, e a correspondência à intent aponta ao recurso com essa BII como você quer atender a essa solicitação. Neste codelab, o fulfillment é uma intent do Android que inicia uma atividade no app.
O diagrama a seguir mostra esse fluxo do Google Assistente:
Figura 2. Um fluxo de como o Google Assistente processa uma consulta por voz.
O arquivo de projeto shortcuts.xml
contém as seguintes informações para cada Ação no app:
- Qual intent integrada ou personalizada a Ação no app usa
- Qual atividade do Android ou link direto o usuário vai receber
- Como os parâmetros da intent integrada fazem o mapeamento das informações que o usuário transmite ao Google Assistente
Em seguida, suas atividades no Android são filtradas e processam a intent ou o link direto do Android para fornecer ao usuário a funcionalidade que ele procura. O resultado é uma experiência do usuário em que o Google Assistente invoca a funcionalidade do app como resposta à consulta do usuário.
3. Preparar seu ambiente de desenvolvimento
Este codelab usa um app de exemplo de lista de tarefas para Android que adiciona itens a listas, pesquisa itens por categoria e verifica informações sobre tarefas concluídas.
Fazer o download dos arquivos de base
Execute o comando a seguir para clonar o repositório do GitHub do app de exemplo:
git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git
Depois, siga estas etapas para abrir o conteúdo clonado no Android Studio:
- Na caixa de diálogo Welcome to Android Studio, clique em Import project.
- Encontre e selecione a pasta em que você clonou o repositório.
Para ter uma versão do app que represente o codelab concluído, clone o repositório do app de exemplo usando a sinalização --branch master
.
Atualizar o ID do app Android
Atualize o ID para identificar seu app de forma exclusiva no dispositivo de teste, evitando o erro "Duplicate package name" se o upload for feito para o Play Console. Para atualizar o ID do aplicativo, abra app/build.gradle
:
android {
...
defaultConfig {
applicationId "com.MYUNIQUENAME.android.fitactions"
...
}
}
Substitua "MYUNIQUENAME" no campo applicationId
por algo exclusivo.
Testar o app no seu dispositivo
Antes de alterar outros elementos, teste o app de exemplo no emulador para saber o que ele consegue fazer. Para isso, siga estas etapas:
- No Android Studio, selecione Run > Run app ou clique em Run na barra de ferramentas.
- Na caixa de diálogo Select Deployment Target, selecione um dispositivo e clique em OK. O SO recomendado é o Android 10 (nível da API 30) ou versão mais recente. No entanto, as Ações no app funcionam a partir do Android 5 (nível da API 21).
- Toque e mantenha pressionado o botão Home para configurar o Google Assistente e verificar se está funcionando. Faça login no Google Assistente usando seu dispositivo.
Para mais informações sobre dispositivos virtuais Android, consulte Criar e gerenciar dispositivos virtuais.
Figura 3. Uma animação demonstrando o app de exemplo da lista de tarefas.
Use um pouco o app para saber o que ele pode fazer. Toque no ícone de adição para criar uma tarefa ou use os itens de menu no canto superior direito para pesquisar e filtrar as tarefas por status de conclusão.
Instalar o plug-in de teste
O plug-in do Google Assistente permite que você execute as Ações no app em um dispositivo de testes. Para instalar a ferramenta de testes, siga estas etapas:
- Acesse File > Settings (Android Studio > Preferences no MacOS).
- Na seção "Plug-ins", acesse Marketplace e pesquise "Google Assistente". Você também pode fazer o download manual e instalar a ferramenta de teste.
- Se você não encontrar o plug-in no Marketplace, faça o download dele e siga as instruções em Instalar o plug-in do disco.
- Instale a ferramenta e reinicie o Android Studio.
4. Adicionar o recurso Get Thing BII
A BII actions.intent.GET_THING
estende a funcionalidade de pesquisa no app ao Google Assistente. Nesta etapa, você vai implementar e testar a BII GET_THING
, permitindo que os usuários pesquisem tarefas específicas no app de exemplo.
Definir o recurso Get Thing
Durante uma Ação no app relacionada à pesquisa, o Google Assistente extrai termos de pesquisa da consulta do usuário para o parâmetro da BII thing.name
e transmite esse valor ao app Android.
Para adicionar a BII GET_THING
ao app, atualize o shortcuts.xml
, localizado no diretório do projeto de exemplo app/src/main/res/xml
, com um elemento <capability>
na tag <shortcuts>
de nível superior:
shortcuts.xml
<shortcuts ....>
<capability android:name="actions.intent.GET_THING">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.yourApplicationId.appaction"
android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
<parameter
android:name="thing.name"
android:key="q"/>
</intent>
</capability>
</shortcuts>
A configuração acima:
- Declara que o app responde à BII
GET_THING
. - Especifica como criar uma intent do Android que inicia o app em resposta a essa BII.
- A atividade é identificada usando
targetPackage
etargetClass
. - O parâmetro da BII
thing.name
é mapeado para a intent Extra, chamadaq
.
- A atividade é identificada usando
A atividade nomeada precisa estar no manifesto do app e ser exportada.
O app Android fornecido contém metadados, permitindo que o AndroidManifest tome conhecimento do arquivo shortcuts.xml
:
<meta-data
android:name="android.app.shortcuts"
android:resource="@xml/shortcuts" />
Testar uma Ação no app
Para testar a pesquisa no app no Google Assistente, siga estas etapas:
- Confira se o dispositivo Android está conectado.
- Acesse Tools > Google Assistant > App Actions Test Tool.
- Clique em Create Preview para aceitar os valores padrão de nome do app e localidade. Leia e aceite as políticas e os Termos de Serviço das Ações no app, se solicitado.
- Na primeira etapa, a ferramenta pede para você selecionar e configurar uma BII. Selecione
actions.intent.GET_THING
. Altere o valorname
derunning shoes
paramilk
. - Clique em Run App Action.
Nesse teste, a BII GET_THING
usa o atributo name
para pesquisar, no app, tarefas com a palavra "leite". Assim como na Ação no app anterior, é possível testar a ação usando a ferramenta de testes ou apenas dizer "Ok Google, pesquisar mistura para bolo na lista de tarefas" ou outras frases de pesquisa no seu dispositivo de teste.
5. Adicionar a BII do recurso "Abrir o app"
Nesta etapa, você vai implementar a BII do recurso "Abrir o app". Com isso, os usuários vão saber quais são as tarefas concluídas e ativas usando o Google Assistente. Para fazer isso, conclua o recurso em shortcuts.xml
, que contém informações sobre como ele é acionado, como os parâmetros são transmitidos e quais intents do Android precisam ser invocadas. Neste codelab, você vai usar a BII OPEN_APP_FEATURE
. Depois de implementar essa BII, teste a ação no seu dispositivo.
Adicionar o recurso "Abrir o app"
Adicione um segundo recurso a "Abrir o app" no arquivo shortcuts.xml
, abaixo do elemento do recurso Get Thing:
shortcuts.xml
<capability android:name="actions.intent.OPEN_APP_FEATURE">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="yourApplicationId"
android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
<parameter
android:name="feature"
android:key="feature"/>
</intent>
</capability>
Esse recurso mapeia a BII do recurso "Abrir o app" e a intent do Android juntas. Portanto, quando o recurso "Abrir o app" é acionado, a intent do Android também é.
Antes de acionar a intent do Android, os parâmetros compatíveis são extraídos da entrada do usuário. A BII OPEN_APP_FEATURE
oferece suporte a um parâmetro, feature
, representando o recurso do app extraído da consulta do usuário. Há dois tipos de recursos compatíveis com o app: "Tarefa ativa" e "Tarefa concluída". Esses recursos permitem que os usuários abram o app com uma visualização filtrada da lista de tarefas. Você precisa usar o inventário inline para ter compatibilidade com esses recursos.
Processar parâmetros de intent usando inventário inline
Os parâmetros de intent representam os elementos extraídos de uma consulta do usuário. Por exemplo, se um usuário disser algo como "Ok Google, peça uma pizza no AppDeExemplo", o Google Assistente vai extrair "pizza" para um parâmetro de intent food.item
schema.org e transmitir esse parâmetro para sua ação a ser processada.
A BII do recurso "Abrir o app" é compatível com um parâmetro, feature
, representando o recurso do app extraído da consulta do usuário. É necessário ter um inventário inline para esse parâmetro, fornecendo ao Google Assistente um conjunto dos nomes de recursos de apps compatíveis para corresponder ao valor do parâmetro.
Para processar o parâmetro de intent feature
, adicione um atalho a shortcuts.xml
com o seguinte código acima do recurso "Abrir o app":
shortcuts.xml
<shortcut
android:shortcutId="active_tasks"
android:shortcutShortLabel="@string/label_active"
android:enabled="false">
<capability-binding
android:key="actions.intent.OPEN_APP_FEATURE">
<parameter-binding
android:key="feature"
android:value="@array/active_tasks_synonyms" />
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="completed_tasks"
android:shortcutShortLabel="@string/label_completed"
android:enabled="false">
<capability-binding
android:key="actions.intent.OPEN_APP_FEATURE">
<parameter-binding
android:key="feature"
android:value="@array/completed_tasks_synonyms" />
</capability-binding>
</shortcut>
No código acima, você definiu um inventário inline, representado como elementos shortcut
com vinculações de recursos e parâmetros. É possível usar os Atalhos como inventário para os parâmetros de BII. O Google Assistente faz a correspondência da consulta do usuário aos valores na vinculação de parâmetros dos Atalhos. Se o valor de parâmetro for correspondente, o shortcutId
será adicionado à intent de fulfillment. Quando um usuário ativa a BII OPEN_APP_FEATURE
com uma solicitação, o Google Assistente faz a correspondência do valor de parâmetro do recurso ao atributo de valor de um atalho, transmitindo o valor para targetClass
como um parameter
em Extra
.
Por exemplo, se um usuário disser algo como "Ok Google, mostre minhas tarefas concluídas no AppDeExemplo", o Google Assistente vai associar o valor de parâmetro da intent de recurso, "tarefas concluídas" ao atalho de inventário correspondente, que vai transmitir esse valor ao recurso OPEN_APP_FEATURE
. Em seguida, o Google Assistente aciona a intent do Android.
Testar uma Ação no app
Durante o desenvolvimento e os testes, você pode usar o plug-in do Google Assistente para visualizar a Ação no app com o Google Assistente em um dispositivo de teste. Outra opção é usar a ferramenta para ajustar os parâmetros de intent de uma Ação no app e testar como ela processa as várias formas que as pessoas pedem algo ao Google Assistente.
Para testar a Ação no app com a ferramenta de testes, siga estas etapas:
- Conecte o dispositivo físico de teste Android ou inicie o Android Emulator.
- Abra ferramenta de teste em Tools > Google Assistant > App Actions Test Tool se ela não estiver visível.
- Clique no botão Update para atualizar a visualização.
- Na primeira etapa, a ferramenta pede para você selecionar e configurar uma BII. Selecione
actions.intent.OPEN_APP_FEATURE
. - Na caixa feature, atualize o valor padrão de
History
comCompleted tasks
. - Clique em Run App Action.
Como alternativa, você pode usar o nome da invocação direto no app Google Assistente do seu dispositivo para testar as Ações no app. Por exemplo, você pode dizer "Ok Google, mostrar tarefas concluídas na lista de tarefas".
6. Próximas etapas
Parabéns!
Agora você sabe como fazer quase todos os apps Android funcionarem com o Google Assistente usando BIIs comuns.
O que aprendemos
Neste codelab, você aprendeu como:
- Permitir que os usuários acessem recursos específicos dos apps usando o Google Assistente.
- Permitir que os usuários acessem a pesquisa no app pelo Google Assistente.
- Testar BIIs comuns usando o plug-in do Google Assistente.
Próxima etapa
Você pode tentar melhorar ainda mais o app de lista de tarefas. Para fazer referência ao projeto finalizado, consulte o repositório –master branch no GitHub.
Confira algumas sugestões sobre como estender esse app com as Ações no app:
- Consulte o exemplo de listas de tarefas com o Google Analytics para Firebase e aprenda a acompanhar a performance das suas Ações no app.
- Acesse a referência de intents integradas das Ações no app para descobrir mais maneiras de estender seus apps com o Google Assistente.
Para continuar sua jornada no Actions on Google, aproveite estes recursos:
- developers.google.com/assistant: site da documentação oficial do Actions on Google.
- Índice de exemplos de Ações no app: códigos e apps de exemplo para conhecer os recursos das Ações no app.
- Repositório no GitHub do Actions on Google: exemplos de código e bibliotecas.
- r/GoogleAssistantDev: comunidade oficial do Reddit para desenvolvedores que trabalham com o Google Assistente (link em inglês).
Siga nosso perfil no Twitter @ActionsOnGoogle, fique por dentro dos nossos comunicados mais recentes e envie um tweet para #AoGDevs sobre o que você criou.
Pesquisa de feedback
Para terminar, responda a esta pesquisa e dê seu feedback sobre o que achou deste codelab.