Como otimizar o conteúdo contextual para o Google Assistente

O Android 6.0 Marshmallow apresenta uma nova maneira para os usuários interagirem com apps por meio de apps de assistente, como o Google Assistente. O Assistente é uma janela de nível superior que o usuário pode acessar para receber ações contextualmente relevantes para a atividade atual. Essas ações podem incluir links diretos para outros apps no dispositivo.

O usuário ativa o Google Assistente tocando no botão home e mantendo-o pressionado ou dizendo uma frase-chave. Em resposta, o sistema abre uma janela de nível superior que exibe ações contextualmente relevantes.

Um app de assistente, como o Google Assistente, implementa a janela sobreposta do assistente por meio de um recurso chamado "Now a um toque", que é compatível com a funcionalidade na plataforma do Android. O sistema permite que o usuário selecione um app assistente, que recebe informações contextuais do seu app usando a API Assist do Android.

Este guia explica como os apps Android usam a API Assist para melhorar a experiência do usuário com o assistente. Para saber como criar um app de mídia que o Google Assistente possa iniciar e controlar, consulte Google Assistente e apps de mídia.

Como usar o Assistente

A Figura 1 ilustra uma interação comum do usuário com o Assistente. Quando o usuário mantém o botão home pressionado, os callbacks da API Assist são invocados no app de origem (etapa 1). O Assistente renderiza a janela sobreposta (etapas 2 e 3) e, em seguida, o usuário seleciona a ação a ser realizada. O Assistente executa a ação selecionada, como disparar uma intent com um link direto para o app de restaurante (de destino) (etapa 4).

Figura 1. Exemplo de interação do Google Assistente com o recurso Now a um toque do Google app

O usuário pode configurar o Assistente selecionando Configurações > Apps > Apps padrão > Assistente e entrada por voz. Os usuários podem mudar as opções do sistema, como acessar o conteúdo da tela como texto e acessar uma captura de tela, conforme mostrado na Figura 2.

Figura 2. Configurações de "Assistente e entrada por voz"

App de origem

Para garantir que seu app funcione com o assistente como uma fonte de informações para o usuário, siga as práticas recomendadas de acessibilidade. Esta seção descreve como oferecer mais informações para ajudar a melhorar a experiência do usuário com o Assistente, bem como cenários que precisam de tratamento especial, como visualizações personalizadas.

Compartilhar outras informações com o assistente

Além de texto e a captura de tela, seu app pode compartilhar outras informações com o assistente. Por exemplo, seu app de música pode transmitir as informações do álbum atual para que o Assistente sugira ações mais inteligentes e personalizadas para a atividade em andamento. As APIs Assist não oferecem controles de mídia. Para adicionar controles de mídia, consulte Google Assistente e apps de mídia.

Para oferecer mais informações ao Assistente, seu app oferece o contexto de aplicativo global registrando um listener de app e fornece informações específicas com callbacks da atividade, conforme mostrado na Figura 3:

Figura 3. Diagrama de sequência do ciclo de vida da API Assist

Para oferecer o contexto de aplicativo global, o app cria uma implementação de Application.OnProvideAssistDataListener e a registra usando registerOnProvideAssistDataListener(). Para fornecer informações contextuais específicas da atividade, a atividade substitui onProvideAssistData() e onProvideAssistContent(). Os dois métodos de atividade são chamados depois que o callback global opcional é invocado. Como os callbacks são executados na linha de execução principal, eles precisam ser concluídos imediatamente. Os callbacks são invocados apenas quando a atividade está em execução.

Fornecer contexto

Quando o usuário ativa o assistente, onProvideAssistData() é chamado para criar uma intent ACTION_ASSIST completa com todo o contexto do aplicativo atual representado como uma instância do AssistStructure. Você pode modificar esse método e colocar o que quiser no pacote para ser exibido na parte EXTRA_ASSIST_CONTEXT da intent de assistência.

Descrever conteúdo

Seu app pode implementar onProvideAssistContent() para melhorar a experiência do usuário no Google Assistente, fornecendo referências de conteúdo relacionadas à atividade atual. Você pode descrever o conteúdo do app usando o vocabulário comum definido pelo Schema.org por meio de um objeto JSON-LD. No exemplo abaixo, um app de música oferece dados estruturados para descrever o álbum que o usuário está visualizando no momento:

Kotlin

override fun onProvideAssistContent(assistContent: AssistContent) {
    super.onProvideAssistContent(assistContent)

    val structuredJson: String = JSONObject()
            .put("@type", "MusicRecording")
            .put("@id", "https://example.com/music/recording")
            .put("name", "Album Title")
            .toString()

    assistContent.structuredData = structuredJson
}

Java

@Override
public void onProvideAssistContent(AssistContent assistContent) {
  super.onProvideAssistContent(assistContent);

  String structuredJson = new JSONObject()
       .put("@type", "MusicRecording")
       .put("@id", "https://example.com/music/recording")
       .put("name", "Album Title")
       .toString();

  assistContent.setStructuredData(structuredJson);
}

Você também pode melhorar a experiência do usuário com implementações personalizadas de onProvideAssistContent(), que podem oferecer os seguintes benefícios:

Observação: os apps que usam uma implementação de seleção de texto personalizada provavelmente precisam implementar onProvideAssistContent() e chamar setClipData().

Implementação padrão

Se nem o callback onProvideAssistData() nem o onProvideAssistContent() forem implementados, o sistema ainda vai prosseguir e transmitir as informações coletadas automaticamente para o assistente, a menos que a janela atual seja sinalizada como segura. Conforme mostrado na Figura 3, o sistema usa as implementações padrão de onProvideStructure() e onProvideVirtualStructure() para coletar texto e visualizar informações de hierarquia. Se a visualização implementar um desenho de texto personalizado, substitua onProvideStructure() para fornecer ao assistente o texto mostrado ao usuário chamando setText(CharSequence).

Na maioria dos casos, a implementação da compatibilidade com acessibilidade permite que o Assistente receba as informações necessárias. Para implementar a compatibilidade com acessibilidade, observe as práticas recomendadas descritas em Como tornar aplicativos acessíveis, incluindo as seguintes:

Excluir visualizações de assistentes

Para lidar com informações sensíveis, seu app pode excluir a visualização atual do assistente configurando o parâmetro de layout FLAG_SECURE do WindowManager. Defina FLAG_SECURE explicitamente para cada janela criada pela atividade, incluindo caixas de diálogo. Seu app também pode usar setSecure() para excluir uma superfície do assistente. Não existe um mecanismo global (no app) para excluir todas as visualizações do assistente. Observe que FLAG_SECURE não faz com que os callbacks da API Assist parem de disparar. A atividade que usa FLAG_SECURE ainda pode fornecer informações de forma explícita a um app de assistente usando os callbacks descritos anteriormente neste guia.

Observação: para contas corporativas (Android for Work), o administrador pode desativar a coleta de dados do assistente para o perfil de trabalho usando o método setScreenCaptureDisabled() da API DevicePolicyManager.

Interações por voz

Os callbacks da API Assist também são invocados após a detecção da frase-chave. Para ver mais informações, consulte a documentação Comandos de voz.

Considerações sobre a ordem Z

Um assistente usa uma janela sobreposta leve, exibida na parte de cima da atividade atual. Como o usuário pode ativar o Assistente a qualquer momento, não crie janelas permanentes de alerta do sistema que interfiram na janela sobreposta, como mostrado na Figura 4.

Figura 4. Ordem Z da camada de assistência

Se o app usa janelas de alerta do sistema, remova-as imediatamente. Se deixá-las na tela, a experiência do usuário será prejudicada.

App de destino

Os apps do Assistente costumam usar os links diretos para encontrar apps de destino. Para tornar seu app um possível app de destino, adicione compatibilidade com links diretos. A correspondência entre o contexto atual do usuário e os links diretos ou outras possíveis ações exibidas na janela de sobreposição (mostrada na etapa 3 na Figura 1) é específica para a implementação do Google Assistente. Por exemplo, o app Google Assistente usa links diretos e links de apps para direcionar o tráfego para apps de destino.

Implementar o próprio assistente

Você pode implementar o próprio assistente. Conforme mostrado na Figura 2, o usuário pode selecionar o app assistente ativo. O app assistente precisa fornecer uma implementação de VoiceInteractionSessionService e VoiceInteractionSession, conforme mostrado neste exemplo de VoiceInteraction. Isso também requer a permissão BIND_VOICE_INTERACTION. O assistente pode receber o texto e a hierarquia de visualização representada como uma instância de AssistStructure em onHandleAssist(). Ele recebe a captura de tela por meio do onHandleScreenshot().