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

No primeiro codelab das Ações no app, você aprendeu a estender o Google Assistente para um exemplo de app fitness implementando intents integradas (BII, na sigla em inglês) da categoria BII de saúde e condicionamento físico. As BIIs são organizadas em categorias que representam os tipos de tarefas que os usuários costumam pedir para o Google Assistente fazer.

Neste codelab, você aprenderá a adicionar Ações no app usando BIIs da [categoria de BII comum], que representa tarefas comuns que quase todos os apps Android podem realizar.

Este codelab aborda conceitos de nível intermediário para desenvolvimento com Ações no app. É necessário ter experiência com desenvolvimento de apps Android, tratamento de links diretos, criação de um recurso actions.xml e uso do plug-in da Ferramenta de teste de Ações no app. Os desenvolvedores que ainda não usam o Ações no app podem começar com o codelab anterior.

O que você criará

Neste codelab, você adicionará duas BII comuns a um exemplo de app de lista de tarefas. Isso permite que os usuários peçam ao Google Assistente para:

Navegar até os recursos no app com a BII actions.intent.OPEN_APP_FEATURE.
Pesquisar conteúdo usando a pesquisa no app, com a BII actions.intent.GET_THING.

Três telas progressivas em que o Google Assistente exibe tarefas ativas em um app.

O que você aprenderá

Como a BII de categoria comum pode ser usada para estender o Google Assistente à maioria dos apps Android.
Como testar a BII comum com o plug-in da Ferramenta de teste de Ações no app.

Pré-requisitos

Um terminal para executar comandos de shell com git instalado.
A versão estável mais recente do Android Studio.
Uma Conta do Google com acesso ao Google Play Console.
Um emulador ou dispositivo Android com acesso à Google Play Store pela Internet para testar suas ações.

Neste codelab, você vai usar um dispositivo Android (físico ou emulador) para testar suas ações. Se estiver usando um dispositivo físico, verifique se ele está conectado à máquina de desenvolvimento local. É necessário também fazer login no Google app no dispositivo (ou emulador) e no Android Studio usando a mesma Conta do Google. O app Google Assistente também precisa estar instalado no dispositivo.

Este codelab inicia com o exemplo de app de lista de tarefas para Android. Os usuários deste app de exemplo podem adicionar itens às listas de tarefas, pesquisar itens por categoria e ver informações sobre tarefas concluídas.

Fazer o download dos arquivos de base

Execute o seguinte comando 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

Clone o repositório e depois abra no Android Studio:

Na caixa de diálogo Boas-vindas ao Android Studio, clique em Importar projeto.
Selecione a pasta em que você clonou o repositório.

Para ver uma versão do app Todo, que representa o codelab concluído, clone o repositório do app de exemplo usando a sinalização --branch master.

Alterar o ID do app Android para ativar os testes

Ainda neste codelab, você usará a ferramenta de testes das Ações no app para testar suas ações em um dispositivo ou emulador Android. Para executar a ferramenta de teste, primeiro é preciso fazer o upload do app para um projeto no Google Play Console. Para evitar o erro "Nome do pacote duplicado" nessa etapa, troque o applicationId do app de exemplo por algo exclusivo.

Em app/build.gradle, atualize o valor de applicationId "com.example.myapp" para um ID exclusivo, como "com.codelabs.myname". Se precisar de ajuda para determinar o ID do aplicativo, acesse a página de referência do Android.

build.gradle

android {
...
    defaultConfig {
        // This ID uniquely identifies your app on the device and in Google Play Store
        applicationId "com.example.myapp"
    ...
    }
}

Depois de atualizar applicationId, você verá uma caixa de aviso amarela no ambiente de desenvolvimento integrado chamada "Os arquivos do Gradle foram alterados desde a última sincronização do projeto…" Quando isso acontecer, clique em Sincronizar agora na caixa para evitar problemas durante o upload do app no Play Console.

Testar o app no seu dispositivo

Antes de fazer mais alterações, é recomendável ver o que o app de exemplo pode fazer. Para isso, basta executar em um emulador:

No Android Studio, selecione Exibir > Exibir app ou clique em Exibir na barra de ferramentas.
Na caixa de diálogo "Selecionar alvo da implantação", selecione um dispositivo virtual e clique em Ok. A versão recomendada do SO é o Android 10 (nível da API: 30) ou uma versão mais recente. No entanto, as ações funcionam nos dispositivos a partir da versão 5 (nível da API: 21).

Para verificar se o Google Assistente está funcionando no dispositivo, toque e mantenha pressionado o botão home. Faça login no Google Assistente no seu dispositivo, caso ainda não tenha feito isso.

Para mais informações sobre dispositivos virtuais Android, consulte Criar e gerenciar dispositivos virtuais.

Animação demonstrando o app de exemplo de lista de tarefas Todo

Explore o app rapidamente para ver o que ele pode fazer. É possível criar uma tarefa ao tocar no ícone de adição e pesquisar e filtrar tarefas por status de conclusão nos itens de menu no canto superior direito.

Fazer upload para o Play Console

É preciso fazer upload do app para um projeto no Google Play Console para usar a Ferramenta de teste de Ações no app no Android Studio. Crie o app no Android Studio e faça upload no Play Console como rascunho de versão interna.

Para criar seu app no Android Studio, faça o seguinte:

Acesse Criar > Gerar pacote assinado/APK.
Selecione "Android App Bundle" e clique em Próximo.
Insira as informações para assinar seu app e clique em Próximo.
Selecione a variante de build "prodRelease" e clique em Finish.

No Google Play Console, faça upload do pacote de apps criado como um novo app:

Na página Todos os apps, clique em Criar app.
Dê o nome que quiser e clique em Criar app. Neste codelab, não será necessário preencher as informações no app depois que ele for criado.
No menu da barra lateral, acesse Testes e localize a página Teste interno.
Clique em Criar versão na página Teste interno.
Clique em Continuar para concordar com a Assinatura de apps do Google Play.
No painel Pacotes de apps e APKs, faça upload do arquivo AAB gerado (provavelmente no diretório app/prod/release). Clique em Salvar.

Instalar o plug-in de teste

O plug-in Ferramenta de teste de Ações no app permite que você teste as ações de um único usuário em um dispositivo de teste. Se ainda não tiver essa ferramenta, siga as etapas para instalar:

Acesse Arquivo > Configurações (Android Studio > Preferências no MacOS).
Na seção "Plug-ins", acesse o Marketplace e procure "Ferramenta de teste de Ações no app". Também é possível fazer o download manualmente e instalar a ferramenta de teste.
Instale a ferramenta e reinicie o Android Studio.

Nesta etapa, você vai implementar a BII de recurso de abrir app. Isso permite que os usuários vejam tarefas ativas e concluídas usando o Google Assistente. Para fazer isso, estenda os links diretos do recurso de filtragem de tarefas para o Google Assistente e defina a BII em actions.xml. O teste da ação no dispositivo é a última etapa desta seção.

Testar links diretos

Antes de implementar a BII, verifique se os links diretos do seu app atendem ao comportamento identificado do Ações no app.

Para testar links diretos com a ferramenta de linha de comando Android Debug Bridge (adb), siga estas etapas:

Atualize o app no seu dispositivo.
Para preencher a lista de tarefas com itens de amostra, na barra de apps flutuante, toque no botão de atualização:

Menu flutuante da barra de ferramentas do app de lista de tarefas Todo

Se aparecer a opção de abrir com o Google, selecione "Sempre" para permitir que o app Todo abra os links compatíveis. Depois, você pode mudar essa preferência quando quiser nas configurações no app.

No terminal, insira os seguintes comandos adb para testar os links diretos de filtragem de tarefas do app:

Ver tarefas ativas

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/active-tasks"

Ver tarefas concluídas

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/completed-tasks"

Ver todas as tarefas

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/all-tasks"

Os comandos acima abrem o recurso de visualização em lista do app e exibe as tarefas filtradas pelo status de conclusão especificado no caminho de rastreamento de cada link direto.

Adicionar a BII

Para estender a tarefa, filtre links diretos para o Google Assistente e defina uma BII de recurso de abrir app configurada para abrir esses links em actions.xml.

Defina a BII ao atualizar o actions.xml, no diretório de exemplo de projeto app/src/main/res/xml, com o seguinte código:

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        //TODO: Handle intent parameters

        //TODO: Handle action fulfillment

    </action>
</actions>

Processar parâmetros de intent usando inventário in-line

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 de ExampleApp", o Google Assistente vai extrair "pizza" em um parâmetro de intent food.item schema.org e transmitir à sua ação para processar esses elementos.

O recurso de abrir app da BII é compatível com o parâmetro feature, que representa o recurso do app extraído da consulta do usuário. Um inventário in-line é necessário para esse parâmetro. Ele fornece ao Google Assistente um conjunto de nomes de recursos do app compatíveis para corresponder ao valor do parâmetro.

Para processar o parâmetro de intent feature, atualize actions.xml com o seguinte código:

actions.xml

<?xml version="1.0" encoding="utf-8"?>

<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        <parameter name="feature">
            <entity-set-reference entitySetId="FeatureEntitySet" />
        </parameter>

        //TODO: Handle action fulfillment

    </action>
</actions>

Com o exemplo de código acima, você instruiu o Google Assistente a fazer a correspondência entre os valores de parâmetro do recurso e o inventário in-line FeatureEntitySet, definido como entity-set-reference na tag de parâmetro.

Para definir o inventário in-line da sua BII, adicione entity-set a actions.xml, abaixo do elemento action:

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action>
       ...
    </action>

    <entity-set entitySetId="FeatureEntitySet">
        <entity  url="https://todo.androidappactions.com/completed-tasks"
            name="completed tasks" alternateName="@array/completed_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/active-tasks"
            name="active tasks" alternateName="@array/active_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/all-tasks"
            name="all tasks" alternateName="@array/all_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/statistics"
            name="statistics" alternateName="@array/statistics_synonyms"/>
    </entity-set>
</actions>

No código acima, você definiu um inventário in-line, representado como um elemento entity-set que contém quatro elementos entity. Quando um usuário ativa a BII com uma solicitação, o Google Assistente faz a correspondência do valor do parâmetro feature com o atributo name de um entity e transmite o url de um entity correspondente ao fulfillment.

Por exemplo, se um usuário disser algo como "Ok Google, mostre minhas tarefas concluídas no ExampleApp", o Google Assistente fará a correspondência do valor de parâmetro da intent feature, "tarefas concluídas", com o inventário correspondente entity. Em seguida, o Google Assistente transmite o URL associado https://todo.androidappactions.com/completed-tasks para o fulfillment.

Definir o fulfillment da ação

Para realizar a ação, é preciso definir um elemento fulfillment em actions.xml para gerenciar o URL transmitido pelo Google Assistente. Adicione um fulfillment ao action usando o seguinte código:

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        ... //Parameter definition

        <fulfillment urlTemplate="{@url}"/>
        <fulfillment urlTemplate="https://todo.androidappactions.com/all-tasks"/>

    </action>
   ...
</actions>

Com a amostra acima, você definiu dois elementos fulfillment. O primeiro aciona o Google Assistente de link direto gerado pelo parâmetro feature, representado como um marcador {@url} no atributo urlTemplate. O segundo fulfillment é um substituto que abre uma visualização de tarefas e exibe uma lista de tarefas não filtradas para situações em que o parâmetro feature está ausente ou não é possível encontrar um inventário in-line correspondente element.

Testar a ação do seu app

Durante o desenvolvimento e os testes, você pode usar a Ferramenta de teste de Ações no app para visualizar sua ação com o Google Assistente em um dispositivo de teste. Também é possível usar a ferramenta para ajustar os parâmetros de intent de uma ação e testar como ela processa as várias formas como um usuário pode pedir para o Google Assistente executar.

Para testar a ação do seu app com a ferramenta de teste, siga estas etapas:

Conecte seu dispositivo físico Android de teste ou inicie o Android Emulator
Acesse Ferramentas > Ações no app > Ferramenta de teste de Ações no app. Talvez seja necessário fazer login no Android Studio. Use a mesma conta do login no Google Play Console.
No campo Nome de invocação, digite "Lista de tarefas".
Se não for "Inglês (EUA)", digite a localidade correspondente ao idioma do seu Google Assistente no campo "Localidade".
Clique em Criar visualização.
Na lista suspensa Configurar, selecione a intent actions.intent.OPEN_APP_FEATURE.
Na caixa Recurso, atualize o valor padrão "Histórico" com "Tarefas concluídas".
Clique em "Executar".

Como alternativa, você pode usar o nome da invocação diretamente no app Google Assistente no seu dispositivo para testar a ação do app. Por exemplo, você pode dizer "Ok Google, mostre tarefas concluídas na lista de tarefas".

A ferramenta BII Get thing estende a funcionalidade de pesquisa no app para o Google Assistente. Nesta etapa, você implementa e testa a BII Get thing. Isso permite que os usuários pesquisem tarefas específicas no app de exemplo.

Testar links diretos

O app de exemplo tem um link direto existente para o recurso de pesquisa no app. Antes de implementar a BII, use adb para verificar se esse link direto atende ao comportamento identificado do Ações no app.

Teste o link direto de pesquisa com o seguinte comando adb:

# GET_THING deep link: in-app search
adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/search?q=milk"

O comando acima aciona um link direto que carrega a atividade da lista de itens filtrada para os que contenham a consulta de pesquisa "home".

Adicionar a BII

Durante uma ação de pesquisa, o Google Assistente extrai termos de pesquisa da consulta do usuário em um parâmetro de intent thing.name. Em seguida, ele gera um URL para o fulfillment ao mapear o parâmetro para um modelo de URL definido em um elemento fulfillment.

Para definir a BII em Get thing no seu app, atualize actions.xml com esta nova ação:

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
   <action intentName="actions.intent.OPEN_APP_FEATURE">...</action>

   <action intentName="actions.intent.GET_THING">

        <parameter-mapping
                intentParameter="thing.name"
                urlParameter="q"/>

        <fulfillment urlTemplate="https://todo.androidappactions.com/search?q={q}">
        </fulfillment>

   </action>

   ...
</actions>

Na amostra acima, o elemento parameter-mapping atribui o parâmetro de intent thing.name ao valor "q" do atributo urlParameter do elemento fulfillment. O Google Assistente gera o link direto ao mapear o valor urlParameter para o marcador "{q}" no urlTemplate fulfillment.

Testar a ação do seu app

Para testar a pesquisa do seu app pelo Google Assistente, siga estas etapas:

Conecte seu dispositivo físico Android de teste ou inicie o Android Emulator
Acesse Ferramentas > Ações no app > Ferramenta de teste de Ações no app.
Clique em Atualizar visualização.
Na lista suspensa "Configurar", selecione a intent actions.intent.GET_THING. Troque o valor "nome" de "tênis de corrida" por "leite".
Clique em Executar.

Neste teste, a BII Get thing usa o atributo name para pesquisar no app tarefas que contenham "home". Assim como na ação anterior, é possível testar sua ação usando a ferramenta de teste. Você também pode apenas dizer "Ok Google, pesquisar 'mistura para bolo' na lista de tarefas" ou outras frases de pesquisa no seu dispositivo de teste.

Parabéns!

Agora você pode fazer quase qualquer app Android funcionar com o Google Assistente, usando BIIs comuns.

O que vimos

Neste codelab, você aprendeu:

Como permitir que os usuários acessem recursos específicos do app usando o Google Assistente.
Como os usuários podem acessar a pesquisa no app usando o Google Assistente.
Como testar BIIs comuns usando a Ferramenta de teste de Ações no app.

Próxima etapa

Agora, tente refinar ainda mais o app Lista de tarefas. Para fazer referência ao projeto concluído, consulte o repositório –master branch no GitHub.

Veja algumas sugestões para saber mais sobre como estender o app com o Ações no app:

Confira o exemplo de lista de tarefas com o Google Analytics para Firebase para saber como acompanhar o desempenho do Ações no app.
Use frações para exibir itens de lista incorporados em cartões visuais que os usuários podem usar para interagir no Google Assistente.
Acesse a referência de intents integradas do Ações no app para descobrir mais maneiras de estender seus apps ao Google Assistente.

Para continuar sua jornada no Actions on Google, veja estes recursos:

actions.google.com: site oficial da documentação do Actions on Google.
Índice de exemplos de Ações no app: apps de exemplo e códigos para explorar os recursos das Ações no app.
Repositório do Actions on Google do GitHub: exemplos de códigos e bibliotecas.
r/GoogleAssistantDev: comunidade oficial do Reddit para desenvolvedores que trabalham com o Google Assistente.

Siga nosso perfil do Twitter @ActionsOnGoogle para ficar por dentro dos nossos comunicados mais recentes e envie um tuíte para #AoGDevs contando o que você criou.

Pesquisa de feedback

Por fim, preencha esta pesquisa para dar feedback sobre sua experiência com este codelab.