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).
![](https://developer.android.google.cn/static/images/training/assistant/image01.png?authuser=8&hl=pt-br)
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.
![](https://developer.android.google.cn/static/images/training/assistant/image02.png?authuser=8&hl=pt-br)
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:
![](https://developer.android.google.cn/static/images/training/assistant/image03.png?authuser=8&hl=pt-br)
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:
- Ajusta a intent de conteúdo fornecida para refletir melhor o contexto de nível superior da atividade.
- Fornece o URI do conteúdo mostrado.
- Preenche
setClipData()
com outro conteúdo de interesse que o usuário esteja 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 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:
- Fornecer os atributos
android:contentDescription
. - Preencher
AccessibilityNodeInfo
para visualizações personalizadas. - Confira
se os objetos
ViewGroup
personalizados expõem os filhos corretamente.
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.
![](https://developer.android.google.cn/static/images/training/assistant/image04.png?authuser=8&hl=pt-br)
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()
.