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.

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:

Três telas progressivas do Google Assistente mostrando tarefas ativas em um 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.

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:

Um fluxo de como o Google Assistente processa uma consulta por voz do usuário.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.

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.

Animação demostrando o app de exemplo da lista de tarefas

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.
  3. 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:

  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.

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:

  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.

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:

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

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.