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 usando apps assistentes, como o Google Assistente. O assistente é uma janela de nível superior que os usuários podem acessar para acessar 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 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 assistente, como o Google Assistente, implementa a janela de sobreposição do Assistente usando um recurso chamado "Now a um toque", que funciona com a funcionalidade da plataforma Android. O sistema permite que o usuário selecione um app assistente, que recebe informações contextuais do 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úsica que possa ser iniciado e controlado pelo Assistente, consulte Google Assistente e apps de música.

Como usar o Google Assistente

A Figura 1 ilustra uma interação comum do usuário com o Assistente. Quando o usuário toca no botão home e o mantém pressionado, os callbacks da API Assist são invocados no app de origem (etapa 1). O assistente renderiza a janela de sobreposição (etapas 2 e 3) e, em seguida, o usuário seleciona a ação a ser executada. O assistente executa a ação selecionada, como disparar uma intent com um link direto para o app de restaurante (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 de texto 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 apenas 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 no Assistente, assim como cenários que precisam de tratamento especial, como visualizações personalizadas.

Compartilhar outras informações com o Assistente

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

Para passar mais informações ao Assistente, seu app fornece 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 contexto global de aplicativo, 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 da invocação do callback global opcional. 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 app atual representado como uma instância do AssistStructure. Você pode substituir esse método e colocar o que quiser no pacote para que ele apareça 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. É possível 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 os callbacks onProvideAssistData() e onProvideAssistContent() não forem implementados, o sistema continuará e transmitirá as informações coletadas automaticamente ao 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 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 do suporte à acessibilidade permite que o assistente colete as informações necessárias. Para implementar a compatibilidade com acessibilidade, observe as práticas recomendadas descritas em Como tornar aplicativos acessíveis, incluindo:

Excluir visualizações de assistentes

Para processar informações confidenciais, seu app pode excluir a visualização atual do Assistente, definindo o parâmetro de layout FLAG_SECURE do WindowManager. É necessário definir 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 explicitamente para um app 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 Ações por voz.

Considerações sobre a ordem Z

Um assistente usa uma janela sobreposta leve, exibida sobre a 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 para o Google Assistente geralmente usam links diretos para encontrar apps de destino. Para tornar seu app um possível app de destino, adicione suporte a 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 da Figura 1) é específica da implementação do Google Assistente. Por exemplo, o app Google Assistente usa links diretos e links de apps para direcionar o tráfego aos 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 oferecer uma implementação de VoiceInteractionSessionService e VoiceInteractionSession, conforme mostrado neste VoiceInteraction exemplo. 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 do AssistStructure em onHandleAssist(). Ele recebe a captura de tela por meio do onHandleScreenshot().