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).
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.
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:
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:
- Ajusta a intent de conteúdo fornecida para refletir melhor o contexto de nível superior da atividade.
- Fornece o URI do conteúdo exibido.
- Preenche
setClipData()
com outros conteúdos de interesse relacionados ao que o usuário está visualizando no momento.
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:
- Fornecer os atributos
android:contentDescription
. - Preencher
AccessibilityNodeInfo
para visualizações personalizadas. - Verifique se os objetos
ViewGroup
personalizados expõem corretamente os filhos.
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.
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()
.