Estender um app Android para o Google Assistente com as Ações no app

As Ações no app ajudam a expandir o alcance do seu app Android. Elas permitem iniciar recursos específicos diretamente do Google Assistente. Essas Ações são baseadas nos links diretos do app para oferecer aos usuários mais formas de acessar os recursos que eles querem usar.

Os desenvolvedores Android como você podem implementar uma das intents integradas disponíveis para ajudar os usuários a realizar tarefas de maneira mais rápida e fácil.

Este codelab aborda conceitos intermediários de desenvolvimento com o Actions on Google. Para acompanhar, é necessário ter experiência com o desenvolvimento de apps Android e saber manusear links diretos. Desenvolvedores iniciantes no Android podem começar com um dos codelabs de Fundamentos para desenvolvedores Android.

O que você criará

Neste codelab, você adicionará esses recursos a um exemplo de app Android fitness:

  • Os usuários podem iniciar um timer de exercício no app usando o Google Assistente.
  • Também é possível parar esse timer no app usando o Google Assistente.

Quatro telas progressivas em que o Google Assistente inicia o acompanhamento de uma corrida em um app.

O que você aprenderá

  • Como identificar se as Ações no app são adequadas ao seu app Android.
  • Como conectar uma intent integrada a uma atividade do Android.
  • Como encontrar parâmetros de URL de link direto para um app Android no Google Assistente.
  • Como usar o inventário in-line para mapear identificadores da funcionalidade do app.
  • Como testar Ações no app no Android Studio.

Pré-requisitos

Antes de continuar, verifique se você tem as seguintes ferramentas no seu ambiente:

  • Um terminal para executar comandos de shell com git instalado
  • A versão mais recente do Android Studio
  • Uma Conta do Google com acesso ao Google Play Console
  • Um dispositivo Android físico para testar as Ações no app

É recomendável ter familiaridade com Kotlin e XML, embora não seja obrigatório para entender o código usado neste codelab.

As Ações no app deste codelab só serão acionadas nos idiomas do Google Assistente (neste caso, inglês) nas seguintes localidades: en-US, en-GB, en-CA, en-IN, en-BE, en-SG, and en-AU. Outros idiomas e localidades não estão disponíveis para intents integradas do app Android neste codelab.

Neste codelab, você usará um dispositivo Android para testar as Ações no app. Antes de testar em um dispositivo Android físico, verifique se ele está conectado à sua máquina de desenvolvimento local. É necessário fazer login no Google app no dispositivo e no Android Studio com a mesma Conta do Google.

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

Quando um usuário indica que quer usar seu app, o Google Assistente procura Ações no app registradas em um arquivo actions.xml. As Ações no app são identificadas nesse arquivo usando uma combinação de intents integradas (que descrevem semanticamente um recurso do app) e instruções de fulfillment (como um modelo de link direto).

O arquivo actions.xml contém as seguintes informações para cada Ação no app:

  • Qual intent integrada a Ação no app usa.
  • Como a Ação no app pode ser atendida (por exemplo, usando um link direto).
  • Como os parâmetros da intent correspondem às informações fornecidas ao Google Assistente pelo usuário.

Com base nas informações que o usuário fornecer ao Google Assistente, as Ações no app criarão um link direto para atender à intent. A atividade do Android filtra e processa o link direto fornecido para entregar ao usuário a funcionalidade desejada.

O resultado é uma experiência do usuário em que o Google Assistente invoca a funcionalidade do app em resposta a uma consulta.

O ponto de partida deste codelab é um exemplo de app Android fitness. No app, os usuários podem iniciar e parar timers de exercício, além de ver informações sobre os treinos.

Fazer o download dos arquivos de base

Para ver os arquivos de base deste codelab, execute o seguinte comando para clonar o repositório do GitHub:

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

A opção --branch codelab-start abre a ramificação em que o codelab inicia.

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

  1. Na caixa de diálogo Boas-vindas ao Android Studio, clique em Abrir um projeto do Android Studio. Se for o caso, feche seu projeto aberto primeiro.
  2. Para começar a trabalhar no app fitness, selecione a pasta em que você clonou o repositório.

Alterar o ID do app Android

Ao implementar Ações no app fitness, você receberá tarefas de teste com entradas usando um plug-in do Android Studio. Você instalará o plug-in ainda neste codelab, mas só poderá usar a ferramenta de teste depois de fazer o upload do app em um projeto do Google Play Console.

Para que sua versão do app fitness seja a única amostra no console, altere o ID do aplicativo nas configurações padrão do Android do seu arquivo app/build.gradle:

build.gradle

android {
...
    defaultConfig {
        applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
    }
}

Substitua "MYUNIQUENAME" no arquivo applicationId por algo que identifique sua versão. Isso modifica o nome do pacote e impede problemas de "Nome do pacote duplicado" ao fazer upload para o Play Console.

Testar o app

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

  1. No Android Studio, selecione Exibir > Exibir app ou clique em Exibiracabcb8f8634af20.png na barra de ferramentas.
  2. 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 8 (nível da API: 26) 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).

Como o emulador é iniciado e processado como um dispositivo físico, ele pode demorar um pouco, dependendo da velocidade do seu computador. Quando o app for criado e o emulador estiver pronto, o Android Studio executa o app depois de fazer o upload para o emulador.

Smartphone com o app de ações do Fit aberto, mostrando estatísticas de exercícios.

Explore o app rapidamente para ver o que ele pode fazer. O ícone de corrida inicia um timer de exercício e o ícone X para esse timer. Estas são as duas tarefas que você ativará com as Ações no app.

Repita as etapas acima no dispositivo de teste para ver se o app funciona da mesma forma nas duas plataformas. Antes de continuar, configure e verifique se o Google Assistente está funcionando no dispositivo físico. Basta tocar e manter pressionado o botão home. Você precisará fazer login no Google Assistente no seu dispositivo de teste, caso ainda não tenha feito isso.

Fazer upload para o Play Console

Crie o app no Android Studio e faça o upload no Play Console como uma versão interna. O upload do app é um pré-requisito para usar a ferramenta de teste de Ações no app no Android Studio.

No Android Studio, siga estas etapas:

  1. Acesse Criar > Gerar pacote assinado/APK.
  2. Selecione "Android App Bundle" e clique em Próxima.
  3. Insira as informações para fazer a assinatura digital no seu app e clique em Próxima.
  4. Selecione a variante de build "versão" e clique em Concluir.

No Google Play Console, encontre o pacote de apps que você acabou de criar e faça upload como um novo app:

  1. Na página Todos os apps, clique em Criar app.
  2. 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.
  3. No menu da barra lateral, acesse Versão e encontre a página Teste interno.
  4. Clique em Criar versão na página Teste interno.
  5. No painel Pacotes de apps e APKs, faça upload do arquivo AAB gerado (provavelmente no diretório app/release).
  6. Clique em Salvar.

Agora que você fez upload do app no Play Console, é hora de voltar para o Android Studio.

Instalar o plug-in de teste

O Google Assistente precisa estar ciente das Ações no app registradas. Portanto, é necessário comunicar essas informações de alguma forma. Durante o desenvolvimento, isso é feito pelo plug-in do Android Studio "Ferramenta de teste de Ações no app".

Instale o plug-in, se ainda não tiver feito isso:

  1. Acesse Arquivo > Configurações (Android Studio > Preferências no MacOS).
  2. Na seção "Plug-ins", acesse o Marketplace e procure "Ferramenta de teste de Ações no app".
  3. Instale a ferramenta e reinicie o Android Studio.

Para configurar uma Ação no app, você precisa encontrar uma intent integrada que mapeie uma função executada pelo app Android. Você pode ver as intents integradas disponíveis para o Google Assistente na página de referência. Essas intents mostram algumas formas de expressar as tarefas que os usuários estão tentando fazer.

Nessa referência, as intents integradas que podem ser realizadas usando Ações no app são agrupadas por categoria e funcionalidade.

Neste codelab, você vai implementar duas intents integradas para ajudar o usuário:

Esse processo envolve a configuração de um link direto, a definição da ação no app usando recursos XML e a conexão dos dois.

Links diretos levam os usuários diretamente ao conteúdo. No processo, as informações da intent são transmitidas para o app. Por padrão, o Google Assistente usa links diretos para atender à intent e transmitir parâmetros ao app. Neste codelab, os links diretos de entrada usam o host "fit-actions.firebaseapp.com" e o esquema "https".

No arquivo de manifesto do Android, adicione um filtro de intent da atividade principal para definir os links diretos compatíveis:

AndroidManifest.xml

<activity android:name="com.devrel.android.fitactions.FitMainActivity" ...>
    ... // Other intent filters

    <!-- Define your supported deeplinks -->
    <intent-filter
        android:autoVerify="true"
        tools:targetApi="m">

        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:host="fit-actions.firebaseapp.com"
            android:scheme="https" />
    </intent-filter>
</activity>

Na atividade principal, adicione a seguinte função para definir o comportamento dos links diretos de entrada:

FitMainActivity.kt

private fun handleDeepLink(data: Uri?) {
    when (data?.path) {
        DeepLink.START -> {
            // Get the parameter defined as "exerciseType" and add it to the fragment arguments
            val exerciseType = data.getQueryParameter(DeepLink.Params.ACTIVITY_TYPE).orEmpty()
            val type = FitActivity.Type.find(exerciseType)
            val arguments = Bundle().apply {
                putSerializable(FitTrackingFragment.PARAM_TYPE, type)
            }

            updateView(FitTrackingFragment::class.java, arguments)
        }
        DeepLink.STOP -> {
            // Stop the tracking service if any and return to home screen.
            stopService(Intent(this, FitTrackingService::class.java))
            updateView(FitStatsFragment::class.java)
        }
        else -> {
            // Path is not supported or invalid, start normal flow.
            showDefaultView()
        }
    }
}

DeepLink.START e DeepLink.STOP são definidos como constantes no app de exemplo e mostram os caminhos correspondentes dos links diretos de entrada. No caso do DeepLink.START, o gerenciador também recebe argumentos por meio de parâmetros de URL de link direto.

Agora, atualize a função handleIntent do mesmo arquivo para usar o gerenciador de links diretos:

FitMainActivity.kt

private fun Intent.handleIntent() {
    when (action) {
        // When the action is triggered by a deep-link, Intent.ACTION_VIEW will be used
        Intent.ACTION_VIEW -> handleDeepLink(data)
        // Otherwise start the app as you would normally do.
        else -> showDefaultView()
    }
}

Agora, quando o app filtrar uma intent com o formato "https://fit-actions.firebaseapp.com/start", ele iniciará um timer de exercício.

Se você conhece o Android Debug Bridge (adb), é possível testar o gerenciador de links diretos em um dispositivo em execução. Para fazer isso, atualize o app no dispositivo e use o seguinte comando shell:

adb shell am start -a android.intent.action.VIEW -d "https://fit-actions.firebaseapp.com/start"

Para as Ações funcionarem, o Google Assistente precisa saber quais delas estão registradas no seu app. Para passar essas informações, basta fazer upload de um arquivo actions.xml para o Play Console como parte do pacote Android.

Você só precisa de algumas etapas para criar e referenciar o novo recurso:

  1. Crie actions.xml para definir quais intents integradas serão conectadas e quais parâmetros são necessários.
  2. Mapeie os parâmetros de intents integradas para criar links diretos para os parâmetros nas suas atividades.
  3. Adicione uma referência ao seu arquivo actions.xml em AndroidManifest.xml.

Criar actions.xml

Para descrever as Ações compatíveis com o app, crie um arquivo XML chamado actions.xml em app/src/main/res/xml.

No Android Studio, siga estas etapas:

  1. Acesse Arquivo > Novo > XML > Arquivo XML das Ações no app.
  2. Insira "ações" no nome do arquivo de ações.
  3. Clique em Concluir para criar o arquivo actions.xml e adicionar uma referência a ele em AndroidManifest.xml.

Depois que o arquivo for criado, substitua o conteúdo de actions.xml pelo seguinte código:

actions.xml

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

<actions>
    <action intentName="actions.intent.START_EXERCISE">
        <fulfillment urlTemplate="https://fit-actions.firebaseapp.com/start{?exerciseType}">
            <parameter-mapping
                intentParameter="exercise.name"
                urlParameter="exerciseType" />
        </fulfillment>
    </action>

    <action intentName="actions.intent.STOP_EXERCISE">
        <fulfillment urlTemplate="https://fit-actions.firebaseapp.com/stop" />
    </action>
</actions>

No código acima, você usa elementos para definir Ações no app que podem iniciar e parar timers de exercício no app. Os atributos intentName correspondem às duas intents integradas que você está atendendo com o Ações no app, e os elementos informam ao Google Assistente como usar seu app para realizar a ação.

Aqui, para executar qualquer uma das ações, é preciso criar links diretos usando o atributo urlTemplate. Os modelos de URL usam o host e o esquema definidos para links diretos no arquivo AndroidManifest.xml. Os caminhos de cada modelo de URL correspondem ao que a função handleDeepLink (adicionada à atividade principal) espera.

Observe que, para iniciar o timer, também é preciso mapear o parâmetro exercise.name da intent integrada ao parâmetro de URL exerciseType. Isso permite que o gerenciador de links diretos receba argumentos para sua lógica de negócios do Google Assistente.

Confirmar se o manifesto do Android se refere a actions.xml

Na etapa anterior, o Android Studio adicionou uma referência ao arquivo actions.xml em AndroidManifest.xml. Para verificar, confira o seguinte elemento no manifesto do Android:

AndroidManifest.xml

<application>
    ...

    <meta-data
        android:name="com.google.android.actions"
        android:resource="@xml/actions" />
</application>

Se o elemento acima aparecer no arquivo de manifesto, passe para a etapa de testes da Ação no app.

Caso contrário, adicione o elemento nesse arquivo.

Testar Ações no app

Agora, vamos testar as Ações no app no dispositivo de teste.

Conecte o dispositivo de teste e use a ferramenta para testar a Ação no app:

  1. 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.
  2. No campo Nome de invocação, digite "Ações fitness".
  3. Se não for "Inglês (EUA)", digite a localidade correspondente ao idioma do seu Google Assistente no campo Localidade.
  4. Clique em Criar visualização.
  5. Na lista suspensa Configurar, selecione a intent integrada que você quer testar.
  6. Clique em Executar. Se aparecer a opção de abrir com o Google, selecione "Sempre" para permitir que o Google Assistente abra os links compatíveis. Depois, você pode mudar essa preferência quando quiser nas configurações no app.

A ferramenta de teste de Ações no app cria ou atualiza as visualizações para uma só Conta do Google. Ela faz um registro temporário das Ações no app definidas. Essa visualização permite que o Google Assistente reconheça as Ações no app antes de implantar a versão de produção do app no Google Play Console.

Quando a ferramenta de teste buscar as intents integradas do seu app, você poderá fornecer diretamente usando valores de parâmetro e acionar a Ação no Android Studio.

Como alternativa, você pode usar o nome da invocação diretamente no app Google Assistente no seu dispositivo para testar a Ação no app. Por exemplo, você pode dizer "Ok Google, começar a correr com as ações fitness" para iniciar um timer de exercício usando a Ação no app.

Agora, você já pode iniciar e parar timers de exercício no app fitness usando o Google Assistente. No entanto, apenas alguns exercícios são reconhecidos. Solicitações como "Iniciar natação nas ações fitness" ou "Iniciar caminhada nas ações fitness" levam a um timer que começa com o texto "Iniciar desconhecido em…".

Isso acontece porque os únicos tipos de exercício compatíveis com o app de exemplo são "Correr", "Pedalar" e "Caminhar". Como você pode atender melhor aos usuários que querem monitorar outros exercícios com o app?

Neste app, há algumas formas de aumentar o número de exercícios disponíveis:

  • Aumente a compatibilidade do app para mais tipos de exercícios, como natação e escalada. Isso depende dos valores de campo de texto compatíveis com a intent integrada actions.intent.START_EXERCISE.
  • Mapeie outro tipo de exercício, como "Fazer trilha", para um que já seja compatível com o app, como "Caminhar".

Se adicionar compatibilidade para mais tipos de exercício, você poderá se conectar a mais caminhos no seu app com base no exercício que o usuário quer fazer e, assim, ajudar o usuário. Essa é a escolha correta se seu app puder executar tarefas diferentes para cada tipo de exercício.

No app fitness, a segunda opção pode ser adaptar ainda mais o Google Assistente. Assim, os usuários poderão iniciar um timer usando consultas que contêm outro valor de campo de texto compatível. Neste codelab, você usará o inventário in-line para mapear "Começar caminhada" para a funcionalidade do app para "Começar a caminhar".

Inventário in-line

O inventário in-line define entidades específicas que o app espera que os usuários incluam ao acionar Ações no app com o Google Assistente. Adicione inventário in-line ao arquivo actions.xml para criar uma lista de opções compatíveis para os usuários. Os itens do inventário são agrupados em um elemento , e as definições de ação podem se referir a grupos de entidades que podem ser usados nos parâmetros de mapeamento.

Como mencionamos, o app de exemplo tem funcionalidades compatíveis com "Correr", "Pedalar" e "Caminhar". Crie um grupo de entidades e refira-se a elas em actions.intent.START_EXERCISE para que seu app só precise usar identificadores de entidades para links diretos:

actions.xml

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

        <!-- Map a parameter to an entity set reference -->
        <parameter name="exercise.name">
            <entity-set-reference entitySetId="ExerciseEntitySet" />
        </parameter>
    </action>
    ...

    <!-- Define an inline inventory -->
    <!-- This sample maps supported entities with the class FitActivity.Type -->
    <entity-set entitySetId="ExerciseEntitySet">
        <entity
            name="@string/activity_running"
            identifier="RUNNING" />
        <entity
            name="@string/activity_walking"
            identifier="WALKING" />
        <entity
            name="@string/activity_hiking"
            identifier="WALKING" />
        <entity
            name="@string/activity_cycling"
            identifier="CYCLING" />
    </entity-set>
</actions>

Cada elemento no inventário in-line representa uma correspondência exclusiva para a consulta do usuário. As entidades permitem que o Google Assistente diferencie entradas compatíveis, como corrida, caminhada e ciclismo. Elas são úteis principalmente para que o Google Assistente reconheça certas informações específicas do seu app, como itens de menu ou serviços.

Quando você adiciona uma entidade para a string "Fazer trilha", outras pessoas podem aproveitar a funcionalidade que você já criou para caminhada.

Testar o inventário

Na ferramenta de teste, ao criar ou atualizar uma visualização, você busca as intents registradas no seu app. Assim, é possível fornecer valores de parâmetro diretamente às intents e acionar a Ação no Android Studio.

Teste seu inventário na ferramenta de teste de Ações no app:

  1. Clique em Atualizar visualização.
  2. Na lista suspensa Configurar, selecione "actions.intent.START_EXERCISE".
  3. Digite "Fazer trilha" no campo exercise.name.
  4. Selecione seu dispositivo na lista suspensa Selecionar dispositivo de destino.
  5. Clique em Executar.

A ferramenta de teste de Ações no app usa a entrada &quot;Fazer trilha&quot; para iniciar um timer de exercício para caminhada (em um dispositivo de teste).

Parabéns!

Você aprendeu sobre as habilidades necessárias para adicionar Ações ao app Android.

O que vimos

  • Como identificar atividades do Android com uma intent integrada correspondente que os usuários podem acionar usando as Ações no app.
  • Como transmitir parâmetros de uma intent integrada para um app Android.
  • Como usar o inventário in-line para mapear valores compatíveis com identificadores de funcionalidade do app.
  • Como testar Ações no app no Android Studio.

Próxima etapa

Agora, tente refinar ainda mais o app fitness. Como inspiração, disponibilizamos uma versão estendida do app na ramificação master do repositório no GitHub. Essa versão usa o Android Slices para incluir as informações do exercício no Google Assistente. Ela também incorpora os requisitos de implantação das Ações no app para apps Android de produção.

Para saber mais sobre o Actions on Google, veja estes recursos:

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

Antes de sair, preencha este formulário para nos ajudar a melhorar o codelab. Entre em contato com nossa equipe se tiver algum problema, precisar de mais informações para concluir as etapas ou apenas quiser contar que deu tudo certo.