Google Assistente para Wear OS

Assistentes por voz em relógios podem ser usados de forma fácil e eficiente em qualquer lugar. As interações por voz em wearables são dinâmicas, o que significa que o usuário pode falar com o pulso sem precisar olhar para o dispositivo enquanto aguarda uma resposta.

Com as Ações no app, os desenvolvedores Android podem estender os apps para Wear OS para o Google Assistente e encaminhar rapidamente os usuários aos apps com comandos de voz, como "Ok Google, iniciar corrida no AppDeExemplo".

Limitações

O Google Assistente no Wear oferece suporte a interações de mídia e monitoramento de atividade física. Para orientações sobre como integrar apps de mídia ao Google Assistente, consulte Google Assistente e apps de mídia. As BIIs de saúde e fitness abaixo oferecem suporte a apps para Wear OS:

• START_EXERCISE
• STOP_EXERCISE
• PAUSE_EXERCISE
• RESUME_EXERCISE

Como funciona

As Ações no app estendem a funcionalidade do app ao Google Assistente, permitindo que os usuários acessem recursos rapidamente usando a voz. Quando um usuário indica que quer usar seu app, o Google Assistente procura Ações no app registradas no recurso shortcuts.xml do app.

As Ações no app são descritas em shortcuts.xml com elementos de recurso do Android. Os elementos de recurso pareiam intents integradas (BII, na sigla em inglês), que são descrições semânticas da capacidade de um app, com instruções de fulfillment, como um modelo de link direto. Quando você faz upload do seu app usando o Google Play Console, o Google registra os recursos declarados em shortcuts.xml, disponibilizando-os para serem acionados pelo Google Assistente.

O diagrama anterior demonstra um usuário pausando o exercício em um app independente. Estas são as etapas:

1. O usuário faz uma solicitação por voz ao Google Assistente para o app wearable específico.
2. O Google Assistente faz a correspondência da solicitação com um modelo pré-treinado (BII, na sigla em inglês) e extrai todos os parâmetros encontrados na consulta com suporte da BII.
3. No exemplo, o Google Assistente faz a correspondência da consulta com a BII PAUSE_EXERCISE e extrai o parâmetro de nome do exercício, "hike" (trilha).
4. O app é acionado com a definição de fulfillment shortcuts.xml para essa BII.
5. O app processa o fulfillment, pausando o exercício.

Conectividade

O desenvolvimento de Ações no app varia de acordo com a funcionalidade do app no ecossistema de dispositivos Android.

• Vinculado: quando um app para wearables depende da versão para dispositivos móveis para funcionalidade completa, as consultas do usuário feitas pelo Google Assistente pelo relógio são atendidas no dispositivo móvel. A lógica de fulfillment de Ações no app precisa ser integrada ao app para dispositivos móveis para que esse cenário funcione corretamente.

• Desvinculados: quando um app para wearables é independente da versão para dispositivos móveis para funcionalidade, o Google Assistente realiza consultas de usuários localmente no relógio. Os recursos de Ações no app precisam ser integrados ao app para wearable para que essas solicitações sejam atendidas corretamente.

Observação: isso só se aplica à funcionalidade de Ações no app em wearables. Consultas gerais no Assistente, como tarefas, automação residencial e informações úteis do dia, são processadas automaticamente pelo app Google Assistente.

Adicionar recursos de voz ao Wear

Integre Ações no app Wear OS seguindo estas etapas:

1. Associe a funcionalidade no app que você quer ativar por voz a uma BII correspondente.

2. Declare suporte para atalhos do Android no recurso AndroidManifest.xml da atividade principal.

   <!-- AndroidManifest.xml -->
   <meta-data
       android:name="android.app.shortcuts"
       android:resource="@xml/shortcuts" />
   

3. Adicione um elemento <intent-filter> ao AndroidManifest.xml. Isso permite que o Google Assistente use links diretos para se conectar ao conteúdo do app.

4. Crie um arquivo shortcuts.xml para fornecer detalhes de fulfillment para suas BIIs. Use os elementos de atalho capability para declarar ao Google Assistente as BIIs que podem ser usadas com o app. Para mais informações, consulte Adicionar recursos.

5. No shortcuts.xml, implemente um recurso para a BII escolhida. O exemplo abaixo mostra um recurso para a BII de START_EXERCISE:

   <?xml version="1.0" encoding="utf-8"?>
   <!-- This is a sample shortcuts.xml -->
   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
     <capability android:name="actions.intent.START_EXERCISE">
       <intent
         android:action="android.intent.action.VIEW"
         android:targetPackage="YOUR_UNIQUE_APPLICATION_ID"
         android:targetClass="YOUR_TARGET_CLASS">
         <!-- Eg. name = "Running" -->
         <parameter
           android:name="exercise.name"
           android:key="name"/>
         <!-- Eg. duration = "PT1H" -->
         <parameter
           android:name="exercise.duration"
           android:key="duration"/>
       </intent>
     </capability>
   </shortcuts>
   

6. Se aplicável, expanda o suporte para variações de fala do usuário usando um inventário inline, que representa os recursos e o conteúdo no seu app.

   <capability android:name="actions.intent.START_EXERCISE">
     <intent
       android:targetPackage="com.example.myapp"
       android:targetClass="com.example.myapp.ExerciseActivity">
       <parameter android:name="exercise.name" android:key="exercise" />
     </intent>
   </capability>
   
   <shortcut android:shortcutId="CARDIO_RUN">
     <capability-binding android:key="actions.intent.START_EXERCISE">
       <parameter-binding
         android:key="exercise.name"
         android:value="@array/run_names" />
       </capability-bindig>
   </shortcut>
   

7. Atualize a lógica do app para processar o fulfillment de Ações no app.

   //FitMainActivity.kt
   
   private fun handleIntent(data: Uri?) {
       var actionHandled = true
       val startExercise = intent?.extras?.getString(START_EXERCISE)
   
       if (startExercise != null){
           val type = FitActivity.Type.find(startExercise)
           val arguments = Bundle().apply {
               putSerializable(FitTrackingFragment.PARAM_TYPE, type)
           }
           updateView(FitTrackingFragment::class.java, arguments)
       }
       else{
           showDefaultView()
           actionHandled = false
       }
       notifyActionSuccess(actionHandled)
   }
   

Visualizar, testar e publicar o app

As Ações no app oferecem ferramentas para analisar e testar seu app. Para informações mais detalhadas, consulte Plug-in do Google Assistente para o Android Studio. Depois de testar seu app e criar uma versão de teste, é possível solicitar uma análise das Ações no app e implantar. Consulte as práticas recomendadas abaixo para orientar o processamento de erros comuns.

Observação: a avaliação de Ações no app é separada da avaliação do Google Play e não afeta seu status no Google Play. Embora seu app possa ser aprovado na avaliação do Google Play e publicado, as Ações no app não funcionarão para os usuários dele até que a análise seja concluída.

Práticas recomendadas

Crie uma experiência do usuário positiva ao integrar seu app ao Google Assistente seguindo estas práticas recomendadas.

Mostre uma tela de confirmação correspondente ou relevante, com retorno tátil e de áudio para responder a uma solicitação do usuário, seja ao atender uma solicitação ou para alertar sobre um erro.

Qualidade básica	Melhor qualidade	Qualidade excelente
Crie uma intent para iniciar a ConfirmationActivity usando uma atividade.	Crie uma intent para iniciar a ConfirmationActivity usando uma atividade. Toque uma campainha E um retorno tátil para indicar o estado atual.	Crie uma intent para iniciar a ConfirmationActivity usando uma atividade. Use a conversão de texto em voz (TTS) e o retorno tátil para indicar erro ou sucesso.

Observação: as solicitações personalizadas de TTS não estão disponíveis nas Ações no app.

Erros e soluções comuns

Para os casos de erro abaixo, use esta mensagem recomendada da ConfirmationActivity do app.

Erro	Exemplo de interação do usuário	Resposta do app
Atividade já em andamento	"Iniciar meu NomeDoExercício" "Retomar meu NomeDoExercício"	Mostra o erro: "Atividade já em andamento".
Nenhuma atividade iniciada	"Pausar/parar meu NomeDoExercício"	Mostra o erro: "Nenhuma atividade iniciada".
Incompatibilidade de tipos de atividade	"Pausar/parar meu NomeDoExercício", que é um tipo de exercício diferente da atividade em andamento.	Mostra o erro: "Tipo de atividade incompatível".
Erro de login	"Iniciar meu NomeDoExercício" quando o usuário não estiver conectado ao app.	Usar o retorno tátil para alertar o usuário e redirecionar para a tela de login.
Erro de permissões	O usuário não tem permissão para iniciar a atividade solicitada.	Usar o retorno tátil para alertar o usuário e redirecionar para a tela de solicitação de permissão.
Problema com o sensor	Os Serviços de localização estão desativados nas configurações do dispositivo do usuário.	Usar o retorno tátil para alertar os usuários e mostrar a tela de erro do sensor. Próximas etapas opcionais: Iniciar atividade sem rastreamento do sensor e notificar o usuário. Solicitar a confirmação do usuário para iniciar a atividade sem o rastreamento do sensor.

---