Integrar um aplicativo Android ao Google Assistente com as Ações no app

1. Visão geral

Com as Ações no app, é possível utilizar o Google Assistente para acessar recursos do aplicativo e realizar tarefas usando comandos de voz. Como desenvolvedor Android, você implementa elementos "capability" para adicionar Ações no app. Assim, o Google Assistente fica sabendo quais funções do aplicativo aceitam comandos de voz e como você quer entregar o que os usuários esperam.

Este codelab envolve conceitos básicos de desenvolvimento com as Ações no app. Por isso, é recomendável já ter trabalhado com o desenvolvimento de apps Android e intents do Android. Se você não tem experiência com Android, uma boa opção é iniciar pelos codelabs do curso Conceitos básicos para desenvolvedores Android.

O que você vai criar

Neste codelab, você vai adicionar duas intents integradas (BIIs, na sigla em inglês) das Ações no app a um aplicativo fitness para Android, permitindo que os usuários iniciem e pausem o timer de exercício usando comandos de voz.

O que você vai aprender

Você vai saber como usar BIIs da categoria Saúde e fitness para integrar o Assistente a um app Android e como utilizar o plug-in do Google Assistente no Android Studio para testar as BIIs.

Pré-requisitos

Antes de continuar, confirme que você tem as seguintes ferramentas no seu ambiente:

• Um terminal para executar comandos do shell com git instalado (link em inglês).
• A versão mais recente do Android Studio.
• Uma Conta do Google com acesso ao [Google Play Console][].
• Um dispositivo Android físico ou virtual com acesso à Internet e à Play Store.

Antes de continuar, verifique se a mesma Conta do Google está conectada ao Android Studio e ao Google app no dispositivo de teste.

2. Como funciona

As Ações no app conectam usuários do Google Assistente ao seu aplicativo Android. Mas como elas funcionam?

Quando um usuário pede para o Assistente realizar uma tarefa no seu app, o Google Assistente associa a consulta a um capability de Ações no app definido no recurso XML shortcuts.xml do aplicativo.

Termo importante: elementos "capability" são modelos que você define em 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 capabilities do Android.

Figura 1. Um diagrama mostrando como o Assistente processa uma consulta por voz de Ações no app.

Cada elemento "capability" define:

• Uma intent: a intent por voz de Ações no app que vai acionar o capability.
• Um ou mais fulfillments: intents do Android ou links diretos que o Google Assistente gera para iniciar o app e atender ao comando de voz do usuário. As definições de fulfillment especificam quais parâmetros são esperados na consulta do usuário e como eles precisam ser codificados nas instruções de inicialização.

Intents

No processamento de linguagem natural (PLN), uma intent é um grupo de frases do usuário com significados semelhantes. O Google gerou dezenas de intents "integradas" (BIIs) que abrangem vários tipos de pedidos disponíveis com as Ações no app. Por exemplo, o Google Assistente é treinado para associar as frases Pedir uma pizza ou Mostrar o cardápio de sobremesas à BII ORDER_MENU_ITEM. Com as Ações no app, você pode usar essas BIIs para associar comandos de voz comuns às funcionalidades do aplicativo.

Fulfillments

Quando um pedido do usuário é associado a Ação no app em shortcuts.xml, sua atividade no Android precisa detectar e processar a intent ou o link direto recebido e oferecer a funcionalidade buscada. Essa experiência usa a voz, e o Google Assistente invoca o app depois da consulta de um usuário.

3. Preparar seu ambiente de desenvolvimento

Este codelab usa um app fitness para Android como exemplo. Esse aplicativo permite que os usuários iniciem e pausem um timer e confiram estatísticas sobre as rotinas de exercícios.

Fazer o download dos arquivos de base

Se quiser usar os arquivos de base deste codelab, execute o comando abaixo para clonar o repositório do GitHub (link em inglês):

git clone --branch codelab-start https://github.com/actions-on-google/appactions-fitness-kotlin.git

Depois, 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.

Observação: o comando git clone acima verifica a ramificação de codelab-start do repositório, que é o ponto de partida deste codelab. Para saber como ficou o app depois de seguir as instruções do codelab, confira a ramificação principal do repositório.

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 aplicativo for enviado ao 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, este aviso vai aparecer no Android Studio: "Gradle files have changed since last project sync…". Clique em Sync Now para não ter problemas com o upload do app.

Testar o app no seu dispositivo

Antes de fazer outras mudanças no código do app, siga as etapas abaixo para testar o aplicativo de exemplo no ambiente de desenvolvimento e saber o que ele consegue fazer:

1. Abra o dispositivo de teste Android virtual ou físico.
2. Verifique se o app Google Assistente está funcionando.
3. Use o Android Studio para implantar e executar o app de exemplo no seu dispositivo.

Siga estas etapas para testar o app:

1. No Android Studio, selecione Run > Run app ou clique em Run na barra de ferramentas.
2. No dispositivo virtual, escolha um dispositivo na caixa de diálogo Select Deployment Target e clique em OK. O SO recomendado é o Android 8 (nível da API – 26) ou uma versão mais recente, mas as Ações no app funcionam em dispositivos a partir do Android 5 (nível da API – 21).
3. Depois de abrir o app, toque e mantenha pressionado o botão home para configurar o Google Assistente e verificar se ele está funcionando. Faça login no Assistente.
4. Abra o app de novo.

Observação: para mais informações sobre dispositivos virtuais, consulte Criar e gerenciar dispositivos virtuais.

Figura 2. O app de exemplo Fit Actions mostrando estatísticas de exercícios.

Use um pouco o app para saber o que ele oferece. Toque no ícone de corrida para iniciar um timer ou no X para fechar o cronômetro. Estas são as tarefas em que você vai ativar o controle de voz com as Ações no app.

Instalar o plug-in do Google Assistente

Com o plug-in do Google Assistente, você pode testar as Ações no app em um dispositivo. Siga estas etapas para adicionar o plug-in ao Android Studio:

1. Acesse File > Settings (Android Studio > Preferences no MacOS).
2. Na seção "Plugins", acesse "Marketplace" e pesquise "Google Assistant".
3. Instale a ferramenta e reinicie o Android Studio.

Observação: o plug-in de teste envia informações ao Assistente pelo Google app no seu dispositivo Android. O dispositivo de teste precisa ter acesso à Play Store para atualizar o Google app. Só assim as Ações no app vão funcionar.

4. Adicionar o capability de BII "Começar exercício"

Com a BII actions.intent.START_EXERCISE, os usuários podem abrir um app e iniciar um treino usando a voz. Nesta etapa, você vai implementar um capability para a BII em questão. Assim, os usuários conseguem pedir para o Google Assistente iniciar uma corrida no app fitness.

Definir o capability

O Google Assistente usa elementos capability definidos em shortcuts.xml para processar o som dos comandos de voz seguindo estas etapas:

1. O Google Assistente associa a consulta de voz do usuário a uma BII definida nos capabilities do app.
2. O Google Assistente extrai valores da consulta para parâmetros de BII. Cada parâmetro é adicionado a um Bundle anexado a uma Intent gerada.
3. O Google Assistente usa a Intent para iniciar o app e dar a ele acesso aos parâmetros agrupados.

A BII START_EXERCISE funciona com o parâmetro exercise.name, usado para que as pessoas consigam especificar o tipo de exercício que será monitorado no app.

Inclua a BII START_EXERCISE no seu app adicionando o capability em questão ao arquivo shortcuts.xml, disponível no exemplo de diretório do projeto app/src/main/res/xml:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <parameter
      android:name="exercise.name"
      android:key="exerciseType"/>
  </intent>
</capability>

Substitua PUT_YOUR_APPLICATION_ID_HERE pelo applicationId exclusivo que você definiu na etapa anterior.

O XML de exemplo anterior:

• Declara um capability para a BII START_EXERCISE.
• Especifica a intent do Android que o Google Assistente gera para iniciar o app:
  • Os atributos targetPackage e targetClass especificam a atividade de recebimento.
  • O atributo parameter mapeia o parâmetro de BII exercise.name para exerciseType nos extras Bundle recebidos pela atividade.

Processar parâmetros de BII com um inventário inline

Os parâmetros de BII representam os elementos extraídos de uma consulta do usuário no Google Assistente. Por exemplo, quando um usuário diz Ok Google, comece uma corrida no AppDeExemplo, o Google Assistente extrai "corrida" para o parâmetro de BII exercise.name do schema.org. Em algumas BIIs, é possível configurar o Google Assistente para associar os parâmetros de BII a um conjunto de identificadores esperados pelo app.

Se quiser fazer isso, vincule elementos do inventário inline ao parâmetro de BII. Um inventário inline é um conjunto de valores de parâmetros de BII aceitos, como "correr", "caminhar" e "correr de leve", e o ID de atalho correspondente, como EXERCISE_RUN. Com essa vinculação, o Google Assistente pode transmitir o ID do atalho de parâmetros associados (em vez do valor bruto da consulta) à atividade de fulfillment.

Alguns parâmetros de BII, como exercise.name, precisam de um inventário inline para funcionar. Se quiser processar o parâmetro em questão, adicione os seguintes elementos shortcut do inventário ao arquivo shortcuts.xml:

<!-- shortcuts.xml -->

<shortcuts>
  <shortcut
    android:shortcutId="running"
    android:shortcutShortLabel="@string/activity_running">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/runningSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="walking"
    android:shortcutShortLabel="@string/activity_walking">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/walkingSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="cycling"
    android:shortcutShortLabel="@string/activity_cycling">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/cyclingSynonyms"/>
    </capability-binding>
  </shortcut>

  <capability> ... </capability>
</shortcuts>

No código anterior, você definiu três atalhos que representam um inventário inline para os tipos de exercícios aceitos pelo app: corrida, caminhada e ciclismo. Cada atalho fica vinculado ao capability das seguintes maneiras:

• O atributo android:key de cada elemento capability-binding se refere à mesma BII START_EXCERCISE definida para o capability.
• O elemento parameter-binding de cada tecla de atalho para o parâmetro de BII exercise.name.

Observação: após concluir essa etapa, talvez o Android Studio avise que não conseguiu resolver os símbolos dos valores de sinônimos. Para solucionar isso, conclua a próxima etapa.

Adicionar sinônimos do inventário inline

Os atributos android:value do elemento parameter-binding nos atalhos de inventário anteriores se referem a um recurso de matriz dos sinônimos para cada elemento de inventário. Os sinônimos permitem variações de um tipo de elemento, como "correr", "correr de leve" e "correr rápido" para se referir ao mesmo shortcutId. Adicione as seguintes entradas de sinônimos ao recurso array.xml do projeto:

<!-- array.xml -->
<array name="runningSynonyms">
  <item>Run</item>
  <item>Jog</item>
  <item>Jogging</item>
  <item>Sprint</item>
</array>

<array name="walkingSynonyms">
  <item>Walk</item>
  <item>Hike</item>
  <item>Hiking</item>
</array>

<array name="cyclingSynonyms">
  <item>Biking</item>
  <item>Riding</item>
  <item>Pedaling</item>
</array>

Atender às intents do Android

Intents do Android são objetos de mensagens que o Android usa para solicitar uma ação de outro app. O Google Assistente atende às consultas de voz gerando uma intent com base nos detalhes de configuração no capability acionado. Para atender a intents do capability START_EXERCISE, atualize a classe de destino FitMainActivity para processar a intent e os parâmetros de BII recebidos.

Primeiro, substitua a função Intent.handleIntent pelo seguinte código:

//FitMainActivity.kt

private fun Intent.handleIntent() {
  when (action) {
    // When the BII is matched, Intent.Action_VIEW will be used
    Intent.ACTION_VIEW -> handleIntent(data)
    // Otherwise start the app as you would normally do.
    else -> showDefaultView()
  }
}

Em seguida, adicione uma nova função handleIntent à classe com o seguinte código:

//FitMainActivity.kt

/**
 * Use extras provided by the intent to handle the different BIIs
 */

private fun handleIntent(data: Uri?) {
  // path is normally used to indicate which view should be displayed
  // i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
  var actionHandled = true

  val startExercise = intent?.extras?.getString(START_EXERCISE)
  // Add stopExercise variable here

  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  else{
   // path is not supported or invalid, start normal flow.
   showDefaultView()

   // Unknown or invalid action
   actionHandled = false
  }
  notifyActionSuccess(actionHandled)
}

Na função Intent.handleIntent anterior, quando ACTION_VIEW é acionado, os dados da intent referentes à Ação no app são transmitidos à função handleIntent. Os parâmetros de BII agrupados na intent START_EXERCISE ficam disponíveis em intent?.extras?.getString(START_EXERCISE). O restante da função vai atualizar FitTrackingFragment para mostrar o tipo de exercício escolhido para startExercise.

Testar uma Ação no app

Durante o desenvolvimento das Ações no app, você usa o plug-in do Google Assistente para conferir as ações em um dispositivo de teste. Uma alternativa é utilizar o plug-in para ajustar os valores de parâmetro da intent em uma ação e testar como o aplicativo processa as diversas formas de alguém fazer um pedido ao Google Assistente no seu app.

Para testar a Ação no app com o plug-in:

1. Para executar o app no Android Studio, escolha Run > Run App ou clique no ícone Run na barra de ferramentas em cima.
2. Acesse Tools > App Actions > Google Assistant > App Actions Test Tool.
3. Clique em Create preview. Confira e aceite as políticas e os Termos de Serviço das Ações no app, se for o caso.
4. Selecione a intent integrada actions.intent.START_EXERCISE.
5. Na caixa exercise, não mude o valor padrão running.
6. Clique em Run App Action. Verifique se o Google Assistente tem um link direto para o timer de exercício do app e se o cronômetro iniciou uma corrida.

Dica: consulte o guia de solução de problemas se não conseguir usar a ferramenta de teste.

Você implementou suas primeiras Ações no app com a BII START_EXERCISE. Parabéns! Em seguida, vamos permitir que os usuários parem um treino no app.

5. Adicionar o capability de BII "Parar exercício"

A BII actions.intent.STOP_EXERCISE permite que os usuários parem um treino dizendo, por exemplo, Ok Google, pare minha corrida no AppDeExemplo. Implemente essa BII no app fitness adicionando um segundo capability ao arquivo shortcuts.xml:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.STOP_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <!-- Eg. name = "Running" -->
    <parameter
        android:name="exercise.name"
        android:key="stopExercise"/>
  </intent>
</capability>

Substitua PUT_YOUR_APPLICATION_ID_HERE pelo applicationId exclusivo.

Processar parâmetros de BII com um inventário inline

Essa BII aceita o mesmo parâmetro exercise.name que a BII START_EXERCISE, permitindo que os usuários especifiquem qual treino querem encerrar. Para ativar esse recurso, adicione um segundo conjunto de elementos de atalho do inventário ao arquivo shortcuts.xml:

<!-- shortcuts.xml -->

<shortcut
  android:shortcutId="running"
  android:shortcutShortLabel="@string/activity_running">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/runningSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="walking"
  android:shortcutShortLabel="@string/activity_walking">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/walkingSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="cycling"
  android:shortcutShortLabel="@string/activity_cycling">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/cyclingSynonyms"/>
  </capability-binding>
</shortcut>

Atender às intents do Android

Atualize a classe FitMainActivity para permitir que o app processe intents STOP_EXERCISE do Android. Primeiro, adicione uma variável à função handleIntent para armazenar os dados da intent STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
  //...
}

Em seguida, atualize a lógica condicional da função handleIntent para processar intents STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  //...
  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  <strong>
  } else if(stopExercise != null){
    // Stop the tracking service if any and return to home screen.
    stopService(Intent(this, FitTrackingService::class.java))
    updateView(FitStatsFragment::class.java)
  }
  </strong>
  //...
}

No código anterior, você atualizou a função handleIntent para buscar a BII STOP_EXERCISE na intent recebida do Android. Se ela for encontrada, a função vai pausar o timer ativo e levar o usuário à tela inicial.

Testar uma Ação no app

Para fazer isso usando o plug-in do Google Assistente:

1. Para executar o app no Android Studio, escolha Run > Run App ou clique no ícone Run na barra de ferramentas em cima.
2. No app, inicie um novo exercício de "corrida".
3. Abra o plug-in no Android Studio: acesse Tools > App Actions > Google Assistant > App Actions Test Tool.
4. Clique em Create preview.
5. Selecione a intent integrada actions.intent.STOP_EXERCISE.
6. Na caixa exercise, não mude o valor padrão running.
7. Clique em Run App Action. Verifique se o Google Assistente interrompe o treino e leva você à tela inicial.

Dica: consulte o guia de solução de problemas se não conseguir usar a ferramenta de teste.

6. Próximas etapas

Parabéns!

Agora você já sabe como ativar por voz um app Android usando as intents integradas do Google Assistente. Neste codelab, você aprendeu como:

• Permitir que os usuários acessem recursos específicos dos apps com o Google Assistente.
• Usar o inventário inline.
• Testar BIIs com o plug-in do Google Assistente.

O que vem a seguir

Você pode melhorar ainda mais o app fitness. Para fazer referência ao projeto finalizado, consulte a ramificação principal no GitHub (link em inglês).

Confira algumas sugestões para integrar esse aplicativo usando as Ações no app:

• Confira outros codelabs sobre Ações no app.
• Acesse a referência de intents integradas das Ações no app para descobrir mais BIIs que permitem a integração dos seus apps ao Google Assistente.

Para continuar sua jornada na plataforma Actions on Google, confira estes recursos:

• developers.google.com/assistant: site da documentação oficial da plataforma Actions on Google
• Índice de exemplos de Ações no app: códigos e aplicativos de exemplo para conhecer os capabilities das Ações no app
• Repositório do GitHub da plataforma Actions on Google (link em inglês): exemplo de código e bibliotecas
• r/GoogleAssistantDev: comunidade oficial do Reddit em inglês para desenvolvedores que trabalham com o Google Assistente

Siga nosso perfil @ActionsOnGoogle no Twitter, fique por dentro das novidades e envie um tweet com #appactions para mostrar o que você criou.

Pesquisa de feedback

Para terminar, responda a esta pesquisa e dê seu feedback sobre o que achou do codelab.