Criar Ações no app

As Ações no app permitem que os usuários iniciem recursos do seu app Android pedindo ao Google Assistente ou usando atalhos do Android sugeridos pelo Assistente. Estas são as principais etapas para ampliar seu app Android com as Ações no app:

1. Identifique o recurso do app a ser acionado e a intent integrada (BII) correspondente.
2. Forneça detalhes de fulfillment para a BII.
3. Envie atalhos da Ação do app ao Google Assistente.
4. Teste uma prévia das Ações no app em um dispositivo.
5. Crie uma versão de teste do app.
6. Solicite a análise e implantação das Ações no app.

Como opção, você pode definir atalhos dinâmicos que são fornecidos ao Google Assistente e os sugerir aos usuários. Crie uma Ação no app usando um app de exemplo seguindo o codelab de Ações no app.

Atenção: devido a restrições regulatórias, os apps participantes do programa Feito para Família (DFF, na sigla em inglês) não podem ter Ações no app. Se você enviar uma ação para análise de um app incluído no programa DFF, ela não vai ser aprovada.

Requisitos

Antes de começar a desenvolver Ações no app, confira se você e seu app atendem aos seguintes requisitos:

• Ter uma Conta do Google com acesso ao Google Play Console.
• Seu app precisa ser publicado na Google Play Store, porque as Ações no app só estão disponíveis para apps publicados nela. Além disso, o app não pode ser destinado ao uso em um perfil de trabalho, porque o Google Play gerenciado não oferece suporte às Ações no app.
• Você precisa de um dispositivo físico ou virtual para testar as Ações no app.
• Instale a versão compatível mais recente do Android Studio com suporte do Plug-in do Google Assistente.
• Use a mesma Conta do Google para fazer login no Android Studio, no Google app do dispositivo de teste e no Google Play Console.
• Você precisa configurar o Google Assistente no dispositivo de teste e testá-lo tocando e pressionando o botão home.

Combinar intents integradas com a funcionalidade do app

Identifique a funcionalidade do app Android que os usuários podem querer acessar com uma solicitação falada e consulte a referência de intents integradas para encontrar BIIs adequadas para seus casos de uso. As BIIs modelam consultas de usuários para tarefas que eles querem realizar. Portanto, procure BIIs que correspondam às principais funções e fluxos de usuários no app.

Existem BIIs comuns que quase todos os apps Android podem usar, como estender a pesquisa no app ao Google Assistente com a BII actions.intent.GET_THING ou permitir que os usuários iniciem recursos específicos do app por voz, implementando a BII do actions.intent.OPEN_APP_FEATURE.

Importante: como parte dos requisitos de implantação das Ações no app, os apps que têm uma função de pesquisa precisam implementar a BII actions.intent.GET_THING para que os usuários possam pesquisar conteúdo no app com comandos de voz usados com frequência, como "Ok Google, pesquisar tênis de corrida no App Exemplo"

.

Há também BIIs que permitem casos de uso verticais ou específicos de uma categoria. Por exemplo, um app de exercícios pode usar a BII actions.intent.START_EXERCISE.

Observação: nos casos em que não há uma BII para o recurso do app, é possível usar uma intent personalizada para implementar Ações no app.

Para garantir uma ótima experiência do usuário e evitar possíveis atrasos na aprovação, verifique se cada BII implementada é relevante para a funcionalidade do app.

As Ações no app funcionam iniciando intents do Android no app Google Assistente para levar os usuários diretamente a um conteúdo específico no seu app. Você pode definir intents para iniciar uma atividade explicitamente, especificando os campos targetClass e targetPackage. Se o app já implementa URLs de link direto do Android, você pode configurar a intent para usar um link direto para o fulfillment. Para mais detalhes, consulte a seção Testar os links diretos da atividade.

Fornecer detalhes de fulfillment para intents integradas

A maior parte do desenvolvimento de uma Ação no app é declarar um recurso no arquivo de recursos shortcuts.xml do app Android, em que você especifica a BII selecionada e o fulfillment correspondente. Uma BII modela a consulta do usuário para uma tarefa e uma intent de fulfillment fornece ao Google Assistente informações sobre como executar a tarefa.

No arquivo shortcuts.xml, as BIIs integradas são representadas como elementos <capability>, e cada fulfillment é representado como um elemento <intent>:

<shortcuts>
    <capability android:name="actions.intent.START_EXERCISE">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.browse">
            <parameter
                android:name="exercise.name"
                android:key="exercise_name">
            </parameter>
        </intent>
    </capability>

Observação: é necessário usar a biblioteca Jetpack androidx.core:core:1.6.0 (ou mais recente) no seu projeto Android para evitar erros de compilação ao definir os recursos de Ações no app em shortcuts.xml. Para mais detalhes, consulte Primeiros passos com o Android Jetpack.

Para a maioria das BIIs, extraia parâmetros de intent da consulta do usuário com base em entidades do schema.org (link em inglês). O app usa esses parâmetros de BII para direcionar os usuários ao capability selecionado. Por exemplo, o código anterior mapeia o parâmetro BII exercise.name para o parâmetro exercise_name do Android intent.

Se você estiver executando ações usando links diretos, use o campo urlTemplate para definir o URL do link direto gerado pelo Google Assistente:

<shortcuts>
    <capability android:name="actions.intent.START_EXERCISE">
        <intent android:action="android.intent.action.VIEW">
            <url-template android:value="myexerciseapp://start{?exercise_name}" />
            <parameter android:name="exercise.name"
                android:key="exercise_name"
                android:mimeType="text/*">
            </parameter>
        </intent>
    </capability>
</shortcuts>

Dica:quando o app fornece várias intents para uma única BII, o Google Assistente tenta resolvê-las na ordem em que aparecem no elemento capability.

Para detalhes importantes sobre como adicionar Ações no app ao arquivo shortcuts.xml, consulte Criar shortcuts.xml. Essa página também descreve como especificar os valores de parâmetro esperados pelo app.

Implementar a intent integrada GET_THING

Se o app tiver uma função de pesquisa, será necessário implementar a BII actions.intent.GET_THING. O Google Assistente vai poder encaminhar os usuários ao recurso de pesquisa do app para mostrar resultados no app quando fizerem consultas como "Ok Google, pesquisar por AlgumaCoisa no AppDeExemplo".

No arquivo shortcuts.xml, implemente um <capability> para a BII actions.intent.GET_THING da mesma forma que você implementaria qualquer outra BII. É possível usar vários fulfillments para GET_THING, desde que você forneça pelo menos um fulfillment que transmita a consulta do usuário ao recurso de pesquisa do app.

Confira um exemplo de como adicionar a BII actions.intent.GET_THING em shortcuts.xml:

  <capability android:name="actions.intent.GET_THING">
    <intent
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.MySearchActivity">
      <parameter android:name="thing.name" android:key="query" />
    </intent>
  </capability>

Na Activity de pesquisa, extraia a consulta de pesquisa dos dados extras da intent e transmita-a à função de pesquisa do app. No código anterior, a consulta de pesquisa, transmitida como a chave query, é mapeada para o parâmetro "thing.name" da BII. Em seguida, faça uma pesquisa com a consulta e mostre os resultados na interface do usuário.

Opcional: enviar atalhos da Ação no app ao Google Assistente

Depois de definir um recurso para a ação, ela pode ser iniciada pelos usuários quando eles disserem algo como Ok Google, peça uma pizza no AppDeExemplo. O Google Assistente pode sugerir atalhos do Android para suas ações em momentos relevantes, permitindo que os usuários descubram e usem suas ações. O Google Assistente pode sugerir atalhos dinâmicos e estáticos.

Para enviar atalhos dinâmicos ao Google Assistente, use a biblioteca Google Shortcuts Integration. Essa biblioteca do Jetpack permite que o Google Assistente processe seus atalhos e os sugira para os usuários no momento adequado.

Confira mais detalhes em Enviar atalhos dinâmicos ao Google Assistente.

Ver uma prévia das Ações no app

Durante o desenvolvimento e os testes, use o plug-in do Google Assistente para o Android Studio para testar se as Ações no app funcionam. O plug-in cria uma prévia das suas Ações no app no Google Assistente para sua Conta do Google. Com a ferramenta de teste, é possível testar os fulfillments em um dispositivo de teste físico ou um emulador, fornecendo BIIs com os parâmetros de entrada que você espera receber dos usuários.

Observação: também é possível adicionar outros testadores à integração das Ações no app, mesmo que eles não compartilhem a mesma conta do Play Console. Para saber mais, consulte Adicionar mais testadores.

Ao conferir uma prévia das Ações no app, você pode acionar consultas por voz no dispositivo. Essa função está disponível apenas para consultas listadas na referência de BIIs das Ações no app. Use o acionamento por voz apenas para demonstração, não para testes regulares.

Observação: a ferramenta de teste de Ações no app oferece suporte apenas a testes de BIIs na localidade en-US, a menos que consultas de exemplo para outras localidades sejam fornecidas na referência de intent integrada correspondente.

Teste o app no modo rascunho usando as ferramentas para desenvolvedores do Google Play Console antes de enviá-lo para análise. Para mais informações sobre como usar o Google Play Console para implantar um rascunho do app, consulte Preparar e lançar uma versão.

Criar uma versão de teste

Quando estiver tudo pronto para testar as Ações no app com mais testadores, crie uma versão de teste interna ou fechada do app. Por padrão, os testadores de versões internas e fechadas podem acessar Ações no app que já foram analisadas e aprovadas.

Para conceder acesso de teste a todas as Ações no app, incluindo ações não aprovadas, instrua os testadores a participar do Grupo do Google do Programa de desenvolvimento de Ações no app. Os membros desse grupo têm acesso a todas as Ações no app nas versões de teste fechadas e internas sem precisar criar prévias usando a Ferramenta de teste de Ações no app. Pode levar até três horas para que o acesso seja disponibilizado no grupo.

Observação: as Ações no app nas versões de faixa de teste aberto não ficam disponíveis para os usuários até que as ações sejam analisadas e aprovadas. Para saber mais, consulte a próxima seção.

Solicitar a análise e implantação das Ações no app

As Ações no app não ficam disponíveis para os usuários dos seus apps publicados ou das versões de teste abertas até que sejam analisadas e aprovadas. A análise de Ações no app não afeta a análise e o status de implantação do app Android no Google Play. Mesmo que o envio do app seja aprovado e ele seja publicado na Play Store, o shortcuts.xml ainda pode estar em análise pelo Google. As Ações no app não vão funcionar para seus usuários finais até que essa análise também seja aprovada.

Quando você implanta seu app, as Ações no app ficam ativadas. No entanto, as versões reimplantadas estão sujeitas a análise pelo Google. Se a nova versão não funcionar corretamente ou incluir violações da política, o Google se reserva o direito de desativar as Ações no app.

Para enviar suas Ações no app para análise, faça o seguinte:

1. Aceite os Termos de Serviço das Ações no Google no Google Play Console (Configurações avançadas > Ações no Google):

   

2. Faça upload do seu app (contendo o arquivo shortcuts.xml) no Google Play Console normalmente para publicação.

3. Depois de fazer upload do app, o Google entra em contato por e-mail na sua conta do Play Console com mais informações sobre o status da análise das suas Ações no app. Também é possível entrar em contato com o suporte ao desenvolvedor do Google Assistente em caso de dúvidas sobre o status da análise das Ações no app. No formulário de contato, informe o ID do pacote do app e escolha Análise de Ações no app na caixa de seleção Como podemos ajudar?.

Observação: se o app for restrito com base em credenciais de login, forneça um login de teste ao enviar o app. Para fornecer credenciais de teste, selecione seu app no Play Console, navegue até Política > Conteúdo do app e siga as instruções listadas para Acesso de apps.

Opcional: testar os links diretos da atividade

Para usar um link direto para iniciar uma Activity usando uma Ação no app, a Activity precisa ser configurada com URLs de links diretos e ter um filtro de intent correspondente no manifesto do app Android.

Observação: o link direto pode ser baseado em URLs de links de apps, URLs com base na intent ou esquemas personalizados, como myapp://do.thing/param=value.

Para testar se as atividades podem ser acessadas e acionadas com Ações no app usando links diretos, execute este comando adb:

$ adb shell am start -a android.intent.action.VIEW -d "AppLinksURL"

Exemplo:

$ adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/deeplink"

Se a atividade não for iniciada corretamente com o comando adb, confira o seguinte:

• No arquivo de manifesto do app, verifique se a atividade tem android:exported=true para que ela possa ser iniciada usando intents do Google Assistente.
• Se você usa URLs de links do app, siga todas as etapas em Como processar Links do app Android.

Políticas das Ações no app

As Ações no app precisam obedecer a políticas específicas para garantir que os usuários que as acionam recebam a experiência pretendida. Revise essas políticas antes de enviar seus apps para oferecer a melhor experiência do usuário e evitar atrasos ou rejeições da Play Store.

• Direcionar os usuários ao conteúdo pretendido

  As intents integradas (BIIs) e/ou os parâmetros da Ação no app precisam direcionar os usuários apenas à ação relevante e pretendida pelo usuário. Isso pode incluir conteúdo no app, conteúdo do site ou informações mostradas em fatias ou widgets, desde que a experiência tenha sido planejada pelo usuário.

  Por exemplo, as implementações da BII START_EXERCISE ajudam os usuários a iniciar um exercício de determinado tipo, por exemplo, corrida ou natação. A única exceção a essa política é quando a BII do OPEN_APP_FEATURE direciona os usuários para a tela inicial do app.

• Implementar BIIs relevantes para Ações no app

  As BIIs implementadas precisam estar diretamente relacionadas ao conteúdo e à funcionalidade do app.

  Por exemplo, se o app estiver na categoria "Comunicação" da Play Store, não implemente o BII START_EXERCISE, que é recomendado para apps na categoria "Saúde e fitness".

• Implementar intents personalizadas relevantes

  As consultas definidas para intents personalizadas se relacionam ao conteúdo e à funcionalidade do app. Um exemplo de possível violação dessa política é a criação da intent custom.action.intent.GET_RECIPE com o padrão de consulta associado "Mostre receitas de burrito" para um app na categoria "Transporte" da Play Store.

---