Assistente Google per Wear OS

Guarda gli assistenti vocali per situazioni rapide ed efficienti ovunque ti trovi. Le interazioni vocali sui dispositivi indossabili sono dinamiche, ovvero l'utente può parlare al polso senza necessariamente guardare il dispositivo in attesa di una risposta.

Con Azioni app dell'assistente, gli sviluppatori Android possono estendere le app Wear OS all'Assistente Google, facendo avanzare velocemente gli utenti nelle loro app con comandi vocali come "Hey Google, avvia la mia corsa su ExampleApp".

Limitazioni

L'assistente su Wear supporta le interazioni con i contenuti multimediali e l'attività fisica di monitoraggio dell'attività fisica. Per linee guida sull'integrazione delle app multimediali con l'assistente, vedi Assistente Google e app multimediali. Per le app Wear OS sono supportati i seguenti BII relativi a salute e fitness:

• START_EXERCISE
• STOP_EXERCISE
• PAUSE_EXERCISE
• RESUME_EXERCISE

Come funziona

Le azioni app estendono le funzionalità dell'app all'assistente, consentendo agli utenti di accedere rapidamente alle funzionalità dell'app tramite comandi vocali. Quando un utente indica all'assistente di voler utilizzare la tua app, l'assistente cerca le azioni app registrate per la tua app nella risorsa shortcuts.xml dell'app.

Le azioni app sono descritte in shortcuts.xml con elementi di funzionalità Android. Gli elementi di funzionalità accoppiano gli intent integrati (BII), ovvero descrizioni semantiche di una funzionalità dell'app, con istruzioni di fulfillment, ad esempio un modello di link diretto. Quando carichi la tua app utilizzando Google Play Console, Google registra le funzionalità dichiarate in shortcuts.xml, rendendole disponibili per l'attivazione dall'assistente.

Il diagramma precedente mostra un utente che mette in pausa l'allenamento in un'app autonoma. Si verificano i seguenti passaggi:

1. L'utente fa una richiesta vocale all'assistente per l'app indossabile specifica.
2. L'assistente abbina la richiesta a un modello preaddestrato (BII) ed estrae tutti i parametri trovati nella query che sono supportati da BII.
3. Nell'esempio, l'assistente abbina la query allo BII di PAUSE_EXERCISE ed estrae il parametro del nome dell'allenamento, "escursionismo".
4. L'app viene attivata tramite la definizione del fulfillment della funzionalità shortcuts.xml per questo BII.
5. L'app elabora il fulfillment, mettendo in pausa l'allenamento.

Connettività

Lo sviluppo di Azioni app varia a seconda della funzionalità dell'app nell'ecosistema di dispositivi Android.

• Con tethering: quando un'app indossabile dipende dall'app mobile per la piena funzionalità, le query degli utenti inviate all'assistente tramite lo smartwatch vengono soddisfatte sul dispositivo mobile. Affinché questo scenario funzioni correttamente, la logica di fulfillment delle azioni app deve essere integrata nell'app mobile.

• Senza tethering: quando un'app indossabile è indipendente da un'app mobile per funzionalità, l'assistente risponde alle query degli utenti localmente sull'orologio. Le funzionalità di Azioni app devono essere integrate nell'app indossabile affinché queste richieste vengano soddisfatte correttamente.

Nota: si applica solo alla funzionalità Azioni app su indossabili. Le query generiche all'assistente, ad esempio le attività svolte, il controllo della casa e informazioni utili per la giornata, vengono gestite automaticamente tramite l'app Assistente Google.

Aggiungere funzionalità vocali a Wear

Integra Azioni app con la tua app Wear OS seguendo questi passaggi:

1. Abbina la funzionalità in-app per cui vuoi attivare i comandi vocali a uno BII corrispondente.

2. Dichiara il supporto delle scorciatoie Android nella risorsa AndroidManifest.xml dell'attività principale.

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

3. Aggiungi un elemento <intent-filter> a AndroidManifest.xml. In questo modo l'assistente può usare i link diretti per connettersi ai contenuti della tua app.

4. Crea shortcuts.xml per fornire i dettagli di fulfillment per i tuoi BII. Puoi usare gli elementi scorciatoia capability per dichiarare all'assistente i BII supportati dalla tua app. Per ulteriori informazioni, consulta la sezione Aggiungere funzionalità.

5. In shortcuts.xml, implementa una funzionalità per lo BII scelto. Il seguente esempio illustra una funzionalità per lo standard BII di 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 applicabile, espandi il supporto per le varianti vocali dell'utente utilizzando un inventario in linea, che rappresenta le funzionalità e i contenuti della tua 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. Aggiorna la logica dell'app per gestire il fulfillment di azioni app in arrivo.

   //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)
   }
   

Visualizzare l'anteprima, testare e pubblicare l'app

Le azioni app forniscono strumenti per esaminare e testare la tua app. Per informazioni più dettagliate, consulta la pagina relativa al plug-in dell'Assistente Google per Android Studio. Dopo aver testato l'app e creato una release di test, puoi richiedere una revisione di Azioni app e il relativo deployment. Consulta le best practice riportate di seguito per ottenere indicazioni sulla gestione degli errori più comuni.

Nota: la revisione di Azioni app è separata dalla revisione di Google Play e non influisce sul tuo stato in Google Play. La tua app potrebbe superare il controllo di Google Play e essere pubblicata, ma la funzionalità Azioni app non funzionerà per gli utenti dell'app fino al termine del controllo di Azioni app.

Best practice

Crea un'esperienza utente positiva quando integri la tua app con l'assistente seguendo queste best practice consigliate.

Mostra una schermata di conferma corrispondente o pertinente, insieme alla tecnologia aptica e al feedback audio, per rispondere alla richiesta di un utente quando viene soddisfatta una richiesta o per segnalare un errore.

Qualità di base	Qualità migliore	Migliore qualità
Crea un intent per avviare ConfirmationActivity da un'attività.	Crea un intent per avviare ConfirmationActivity da un'attività. Riproduci un segnale acustico E un feedback aptico per indicare lo stato attuale.	Crea un intent per avviare ConfirmationActivity da un'attività. Text-to-Speech (TTS) e feedback aptico per indicare un errore o l'esito positivo.

Nota: le richieste di sintesi vocale personalizzate non sono disponibili tramite Azioni app.

Errori comuni e soluzioni

Per i seguenti casi di errore, utilizza i messaggi della seguente app consigliata per ConfirmationActivity.

Caso di errore	Esempio di interazione utente	Risposta dell'app
Attività già in corso	"Avvia il mio ExerciseName" "Riprendi il mio ExerciseName"	Errore di visualizzazione: attività già in corso."
Nessuna attività iniziata	"Metti in pausa/Interrompi il mio ExerciseName"	Errore di visualizzazione: "Nessuna attività iniziata".
Tipi di attività non corrispondenti	"Metti in pausa/Interrompi il mio ExerciseName", che è un tipo di allenamento diverso dall'attività in corso.	Errore di visualizzazione: "Mancata corrispondenza del tipo di attività".
Errore di accesso	"Avvia il mio ExerciseName" quando l'utente non ha eseguito l'accesso all'app.	Riproduci la tecnologia aptica per avvisare l'utente e reindirizzare alla schermata di accesso.
Errore autorizzazioni	L'utente non è autorizzato ad avviare l'attività richiesta.	Riproduci la tecnologia aptica per avvisare l'utente e reindirizzare alla schermata di richiesta di autorizzazione.
Problema con il sensore	I servizi di geolocalizzazione sono disattivati nelle impostazioni del dispositivo dell'utente.	Riproduci la tecnologia aptica per avvisare gli utenti e mostrare la schermata di errore del sensore. Passaggi successivi facoltativi: Avvia l'attività senza rilevamento del sensore e invia una notifica all'utente. Richiedi la conferma dell'utente per avviare l'attività senza monitoraggio del sensore.

---