Estender um app Android para o Google Assistente com as Ações no app (nível 2)

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.

Termo importante: uma intent integrada do Google Assistente funciona como um acionador predefinido para um tipo específico de funcionalidade que o usuário está buscando. O Google cria e mantém os modelos de linguagem das BIIs para entender uma grande variedade de consultas relacionadas a essa intent específica.

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.

Observação: para implementar a BII do actions.intent.GET_THING, é necessário ter apps com funcionalidade de pesquisa. Saiba mais sobre os requisitos de implantação das Ações no app.

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.

Observação: você pode testar as Ações no app descritas neste codelab com o Google Assistente em apenas algumas localidades. Consulte os documentos de referência de BII comum para saber quais intents estão disponíveis com base na localidade.

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.

Termo importante: recursos são modelos que você define no arquivo shortcuts.xml para declarar os tipos de ações que as pessoas podem realizar para iniciar o app e acessar uma tarefa específica. Consulte a documentação sobre recursos do Android para mais detalhes.

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:

1. Na caixa de diálogo Welcome to Android Studio, clique em Import project.
2. 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.

Observação: depois de atualizar applicationId, você vai receber um aviso "Gradle files have changed since last project sync..." no Android Studio. Clique em Sync Now para não ter problemas com o upload do app.

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:

1. No Android Studio, selecione Run > Run app ou clique em Run na barra de ferramentas.
2. 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).
3. 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:

1. Acesse File > Settings (Android Studio > Preferences no MacOS).
2. 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.
3. Instale a ferramenta e reinicie o Android Studio.

Observação: o plug-in de testes envia informações ao Assistente pelo Google app no seu dispositivo Android.

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.

Dica: a BII GET_THING é usada para pesquisar conteúdo ou entidades usando o recurso padrão de pesquisa no app. Preencha os critérios de pesquisa com o conteúdo ou o nome da entidade usando o parâmetro da intent thing.name e apresente ao usuário os resultados mais relevantes da pesquisa.

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:

1. Declara que o app responde à BII GET_THING.
2. Especifica como criar uma intent do Android que inicia o app em resposta a essa BII.
   • A atividade é identificada usando targetPackage e targetClass.
   • O parâmetro da BII thing.name é mapeado para a intent Extra, chamada q.

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:

1. Confira se o dispositivo Android está conectado.
2. Acesse Tools > Google Assistant > App Actions Test Tool.
3. 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.
4. Na primeira etapa, a ferramenta pede para você selecionar e configurar uma BII. Selecione actions.intent.GET_THING. Altere o valor name de running shoes para milk.
5. 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.

Dica: consulte o guia de solução de problemas caso você tenha dificuldades ao executar a ferramenta de testes.

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.

Observação: essa BII inicia um recurso do app. A intent é especialmente útil para ajudar os usuários a navegar até recursos do app que, de outra forma, seriam difíceis de encontrar ou que exigiriam vários toques para chegar a eles. É necessário especificar o inventário inline do parâmetro do recurso.

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.

Termo importante: um inventário inline orienta a extração de entidades das BIIs fornecendo um conjunto de entidades que um app entende para um parâmetro de BII compatível com o inventário inline. Para saber mais, consulte a seção Inventário inline para Ações no app.

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:

1. Conecte o dispositivo físico de teste Android ou inicie o Android Emulator.
2. Abra ferramenta de teste em Tools > Google Assistant > App Actions Test Tool se ela não estiver visível.
3. Clique no botão Update para atualizar a visualização.
4. Na primeira etapa, a ferramenta pede para você selecionar e configurar uma BII. Selecione actions.intent.OPEN_APP_FEATURE.
5. Na caixa feature, atualize o valor padrão de History com Completed tasks.
6. Clique em Run App Action.

Dica: consulte o guia de solução de problemas caso você tenha dificuldades ao executar a ferramenta de testes.

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.