Estendi un'app per Android all'Assistente Google con Azioni app

1. Panoramica

Con Azioni app, puoi usare l'Assistente Google per accedere direttamente alle funzionalità dell'app e completare attività tramite comandi vocali. In qualità di sviluppatore Android, puoi implementare elementi di funzionalità per aggiungere Azioni app. Le funzionalità consentono all'assistente di sapere quali funzionalità delle app supportano le richieste vocali dell'utente e come vuoi che vengano soddisfatte.

Questo codelab tratta concetti di livello principiante per lo sviluppo con Azioni app. Per seguire questo codelab, devi avere esperienza nello sviluppo di app per Android e intent Android. Se è la prima volta che utilizzi Android, potresti voler iniziare con uno dei codelab relativi ai concetti fondamentali per gli sviluppatori Android.

Cosa creerai

In questo codelab, aggiungerai due intent integrati (BII) di Azioni app a un'app Android per l'attività fisica di esempio, che consentiranno agli utenti di avviare e interrompere un timer di allenamento utilizzando la voce.

Obiettivi didattici

Imparerai a utilizzare gli intent integrati della categoria Salute e fitness per estendere l'assistente a un'app per Android. Imparerai inoltre a utilizzare il plug-in dell'Assistente Google per Android Studio per testare gli intent integrati.

Prerequisiti

Prima di continuare, assicurati di disporre dei seguenti strumenti nel tuo ambiente:

• Un terminale per eseguire i comandi della shell con git installato.
• L'ultima versione di Android Studio.
• Un Account Google con accesso a [Google Play Console][].
• Un dispositivo Android fisico o virtuale con accesso a internet al Play Store.

Prima di continuare, assicurati di aver eseguito l'accesso ad Android Studio e all'app Google con lo stesso Account Google sul dispositivo di test.

2. Come funziona

Le Azioni app collegano gli utenti dall'Assistente Google alla tua app per Android. Come funzionano?

Quando un utente chiede all'assistente di eseguire un'attività utilizzando la tua app, l'assistente abbina la query a un capability di Azioni app definito nella risorsa XML shortcuts.xml dell'app.

Termine chiave: gli elementi di funzionalità sono modelli che definisci in shortcuts.xml per dichiarare i tipi di azioni che gli utenti possono eseguire per avviare la tua app e passare direttamente a un'attività specifica. Per maggiori dettagli, consulta la documentazione di Android per informazioni sulle funzionalità.

Figura 1. Un diagramma di flusso che mostra in che modo l'assistente elabora una query vocale di Azioni app.

Ogni elemento di funzionalità definisce:

• Un intent: l'intent vocale di Azioni app che deve attivare la funzionalità.
• Uno o più fulfillment: intent o link diretti Android che l'assistente genera per avviare l'app e soddisfare la richiesta vocale dell'utente. Le definizioni di fulfillment specificano quali parametri sono previsti dalla query dell'utente e come questi parametri devono essere codificati nelle istruzioni per il lancio.

Intent

Nella comprensione del linguaggio naturale (NLU), un intent è un gruppo di frasi utente con significati simili. Google ha realizzato decine di modelli che coprono un'ampia gamma di tipi di richieste disponibili con Azioni app. Ad esempio, l'assistente è addestrato per associare le frasi "Ordina una pizza" o "Mostrami il menu dei dolci" all'intent integrato ORDER_MENU_ITEM. Con Azioni app, puoi sfruttare questi intent integrati per estendere rapidamente le richieste vocali comuni alla funzionalità dell'app.

Fulfillment

Quando la richiesta di un utente attiva un'Azione app in shortcuts.xml, la tua attività su Android deve rilevare e gestire l'intent Android in arrivo o il link diretto e fornire all'utente la funzionalità desiderata. Il risultato è un'esperienza utente basata sulla voce in cui l'assistente richiama la tua app in risposta alla query di un utente.

3. Prepara l'ambiente di sviluppo

Questo codelab utilizza l'app di esempio Fitness per Android. Questa app consente agli utenti di avviare e interrompere un timer di allenamento e di visualizzare statistiche sulle proprie routine di allenamento.

Scaricare i file di base

Per ottenere i file di base per questo codelab, esegui questo comando per clonare il repository GitHub:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-fitness-kotlin.git

Una volta clonato il repository, aprilo in Android Studio:

1. Nella finestra di dialogo Ti diamo il benvenuto in Android Studio, fai clic su Importa progetto.
2. Trova e seleziona la cartella in cui hai clonato il repository.

Nota: il comando git clone riportato sopra verifica il ramo codelab-start del repository, che è il punto di partenza per questo codelab. Per continuare e vedere l'app una volta completate le istruzioni del codelab, controlla il ramo principale del repository.

Aggiornare l'ID app per Android

L'aggiornamento dell'ID applicazione dell'app identifica in modo univoco l'app sul dispositivo di test ed evita un "Nome pacchetto duplicato" se l'app viene caricata su Play Console. Per aggiornare l'ID applicazione, apri app/build.gradle:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

Sostituisci "MYUNIQUENAME" nel campo applicationId a qualcosa di tuo.

Nota: dopo l'aggiornamento di applicationId, in Android Studio verrà visualizzato questo avviso: "I file Gradle sono cambiati dall'ultima sincronizzazione del progetto...". In questa finestra di avviso, fai clic su Sincronizza ora per evitare problemi che potrebbero verificarsi durante il caricamento dell'app.

Prova l'app sul tuo dispositivo

Prima di apportare ulteriori modifiche al codice dell'app, è utile avere un'idea di cosa può fare l'app di esempio. Il test dell'app nell'ambiente di sviluppo prevede i seguenti passaggi:

1. Apertura del dispositivo Android di test virtuale o fisico.
2. È in corso la verifica del funzionamento dell'app dell'assistente.
3. Utilizzo di Android Studio per implementare ed eseguire l'app di esempio sul dispositivo.

Per testare l'app, procedi nel seguente modo:

1. In Android Studio, seleziona Esegui > Esegui app o fai clic su Esegui nella barra degli strumenti.
2. Se utilizzi un dispositivo virtuale, nella finestra di dialogo Seleziona il target del deployment, seleziona un dispositivo virtuale e fai clic su OK. La versione del sistema operativo consigliata è Android 8 (livello API 26) o versioni successive, anche se le azioni vengono eseguite sui dispositivi già su Android 5 (livello API 21).
3. Dopo aver aperto l'app, premi a lungo il pulsante Home per configurare l'assistente e verificare che funzioni. Accedi all'assistente se non l'hai ancora fatto.
4. Riapri l'app.

Nota:per saperne di più sui dispositivi virtuali, vedi Creare e gestire i dispositivi virtuali.

Figura 2. L'app di esempio Fit Actions che mostra le statistiche di allenamento.

Esplora brevemente l'app per vedere cosa sa fare. Toccando l'icona Corsa viene avviato un timer di allenamento e toccando l'icona X si interrompe il timer. Queste sono le attività che attiverai per il controllo vocale con Azioni app.

Installa il plug-in dell'Assistente Google

Il plug-in dell'Assistente Google ti consente di testare le Azioni app su un dispositivo di test. Per aggiungerla ad Android Studio, procedi nel seguente modo:

1. Vai su File > Impostazioni (Android Studio > Preferenze su MacOS).
2. Nella sezione Plug-in, vai a Marketplace e cerca "Assistente Google".
3. Installa lo strumento e riavvia Android Studio.

Nota: il plug-in di prova invia informazioni all'assistente tramite l'app Google sul tuo dispositivo Android. Il dispositivo di test deve accedere al Play Store per aggiornare l'app Google prima che le Azioni app possano funzionare correttamente.

4. Aggiungi la funzionalità di intent integrato Avvia allenamento

L'intent integrato actions.intent.START_EXERCISE consente agli utenti di aprire un'app e iniziare un esercizio tramite comandi vocali. In questo passaggio, implementerai una funzionalità per questo intent integrato, che consente agli utenti di chiedere all'assistente di avviare una corsa nell'app Fitness.

Definisci la funzionalità

L'assistente usa gli elementi capability definiti in shortcuts.xml per elaborare i comandi vocali tramite comandi vocali seguendo questi passaggi:

1. L'assistente associa la query vocale dell'utente a un intent integrato definito nelle funzionalità dell'app.
2. L'assistente estrae i valori dalla query nei parametri dell'intent integrato. Ogni parametro viene aggiunto a un elemento Bundle associato a un elemento Intent generato.
3. L'assistente utilizza Intent per avviare l'app, consentendo all'app di accedere ai parametri in bundle.

L'intent integrato START_EXERCISE supporta il parametro dell'intent integrato exercise.name. Utilizzerai questo parametro per consentire agli utenti di specificare il tipo di allenamento da monitorare nell'app.

Aggiungi l'intent integrato START_EXERCISE all'app aggiungendo questo capability a shortcuts.xml, che si trova nella directory del progetto di esempio app/src/main/res/xml:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <parameter
      android:name="exercise.name"
      android:key="exerciseType"/>
  </intent>
</capability>

Sostituisci PUT_YOUR_APPLICATION_ID_HERE con il valore applicationId univoco che hai definito nel passaggio precedente.

Il file XML di esempio precedente:

• Dichiara una capacità per l'intent integrato START_EXERCISE.
• Specifica il valore intent Android generato dall'assistente per avviare l'app:
  • Gli attributi targetPackage e targetClass specificano l'attività ricevente.
  • L'attributo parameter mappa il parametro dell'intent integrato exercise.name a exerciseType nei Bundle extra ricevuti dall'attività.

Gestire i parametri degli intent integrati con un inventario in linea

I parametri dell'intent integrato rappresentano gli elementi estratti da una query dell'utente dell'assistente. Ad esempio, quando un utente dice "Hey Google, avvia un'esecuzione su ExampleApp", l'assistente estrae "Esegui". nel parametro dell'intent integrato schema.org di exercise.name. Per alcuni intent integrati, puoi chiedere all'assistente di far corrispondere i parametri degli intent integrati a un set di identificatori previsto dall'app.

Per farlo, associa gli elementi inline Inventory al parametro dell'intent integrato. Un inventario in linea è un insieme di valori parametro dell'intent integrato, come "run", "hike" e "jog", e l'ID della scorciatoia corrispondente, ad esempio EXERCISE_RUN. Questa associazione dell'inventario consente all'assistente di passare l'ID scorciatoia per i parametri corrispondenti, anziché il valore della query non elaborata, all'attività di evasione degli ordini.

Alcuni parametri degli intent integrati, come exercise.name, richiedono un inventario in linea per funzionare. Per gestire questo parametro, aggiungi i seguenti elementi shortcut dell'inventario a shortcuts.xml:

<!-- shortcuts.xml -->

<shortcuts>
  <shortcut
    android:shortcutId="running"
    android:shortcutShortLabel="@string/activity_running">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/runningSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="walking"
    android:shortcutShortLabel="@string/activity_walking">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/walkingSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="cycling"
    android:shortcutShortLabel="@string/activity_cycling">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/cyclingSynonyms"/>
    </capability-binding>
  </shortcut>

  <capability> ... </capability>
</shortcuts>

Nel codice precedente, hai definito tre scorciatoie che rappresentano un inventario in linea per i tipi di allenamento supportati dall'app: corsa, camminata e ciclismo. Ogni scorciatoia è associata alla funzionalità nei seguenti modi:

• L'attributo android:key di ogni elemento capability-binding fa riferimento allo stesso intent integrato START_EXCERCISE definito per la funzionalità.
• L'elemento parameter-binding di ogni tasto di scelta rapida per il parametro dell'intent integrato exercise.name.

Nota: dopo aver completato questo passaggio, Android Studio potrebbe avvisarti che non è in grado di risolvere i simboli dei valori dei sinonimi. Risolvi il problema completando il passaggio successivo.

Aggiungi sinonimi per l'inventario in linea

Gli attributi android:value dell'elemento parameter-binding nelle scorciatoie dell'inventario precedenti fanno riferimento a una risorsa array di sinonimi per ciascun elemento dell'inventario. I sinonimi consentono le varianti di un tipo di elemento, come "corsa", "jog" e "sprint" per fare riferimento allo stesso shortcutId. Aggiungi le seguenti voci di sinonimi alla risorsa array.xml del progetto:

<!-- array.xml -->
<array name="runningSynonyms">
  <item>Run</item>
  <item>Jog</item>
  <item>Jogging</item>
  <item>Sprint</item>
</array>

<array name="walkingSynonyms">
  <item>Walk</item>
  <item>Hike</item>
  <item>Hiking</item>
</array>

<array name="cyclingSynonyms">
  <item>Biking</item>
  <item>Riding</item>
  <item>Pedaling</item>
</array>

Soddisfa gli intent Android in arrivo

Gli intent di Android sono oggetti di messaggistica utilizzati da Android per richiedere un'azione da un'altra app. L'assistente soddisfa le esigenze query vocali generando un intent in base ai dettagli di configurazione nella funzionalità attivata. Per soddisfare gli intent per la funzionalità START_EXERCISE, aggiorna la classe di destinazione FitMainActivity in modo che gestisca i parametri dell'intent e dell'intent integrato in entrata.

Innanzitutto, sostituisci la funzione Intent.handleIntent con il seguente codice:

//FitMainActivity.kt

private fun Intent.handleIntent() {
  when (action) {
    // When the BII is matched, Intent.Action_VIEW will be used
    Intent.ACTION_VIEW -> handleIntent(data)
    // Otherwise start the app as you would normally do.
    else -> showDefaultView()
  }
}

Successivamente, aggiungi una nuova funzione handleIntent alla classe con il seguente codice:

//FitMainActivity.kt

/**
 * Use extras provided by the intent to handle the different BIIs
 */

private fun handleIntent(data: Uri?) {
  // path is normally used to indicate which view should be displayed
  // i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
  var actionHandled = true

  val startExercise = intent?.extras?.getString(START_EXERCISE)
  // Add stopExercise variable here

  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  else{
   // path is not supported or invalid, start normal flow.
   showDefaultView()

   // Unknown or invalid action
   actionHandled = false
  }
  notifyActionSuccess(actionHandled)
}

Nella funzione Intent.handleIntent precedente, quando viene attivato ACTION_VIEW, i dati di intent dell'Azione app vengono passati alla funzione handleIntent. Si accede ai parametri dell'intent integrato nell'intent START_EXERCISE tramite intent?.extras?.getString(START_EXERCISE). Il resto della funzione aggiorna il FitTrackingFragment per visualizzare il tipo di allenamento startExercise scelto.

Testa l'azione app

Durante lo sviluppo delle Azioni app, utilizzi il plug-in dell'Assistente Google per visualizzare l'anteprima delle Azioni su un dispositivo di test. Puoi usare il plug-in anche per regolare i valori dei parametri di intent di un'azione e verificare in che modo l'app gestisce i vari modi in cui un utente potrebbe inviare una richiesta all'assistente per la tua app.

Per testare l'Azione app con il plug-in:

1. Esegui l'app in Android Studio selezionando Esegui > Esegui app o facendo clic sull'icona Esegui nella barra degli strumenti in alto.
2. Vai a Strumenti > Azioni app > Assistente Google > Strumento di test delle Azioni app.
3. Fai clic su Crea anteprima. Se richiesto, leggi e accetta le norme e i termini di servizio di Azioni app.
4. Seleziona l'intent integrato actions.intent.START_EXERCISE.
5. Nella casella exercise, lascia il valore predefinito running (corsa).
6. Fai clic su Run App Action (Esegui azione app). Verifica che l'assistente rimandi direttamente al timer dell'allenamento dell'app e che il timer abbia iniziato un esercizio di corsa.

Suggerimento:in caso di problemi con l'esecuzione dello strumento di test, consulta la guida alla risoluzione dei problemi.

Hai implementato la tua prima Azioni app con l'intent integrato START_EXERCISE. Complimenti! Successivamente, consentiremo agli utenti di interrompere un esercizio di corsa nella tua app.

5. aggiungi la funzionalità di intent integrato Arresta esercizio

L'intent integrato actions.intent.STOP_EXERCISE consente agli utenti di interrompere una sessione di allenamento chiedendo, ad esempio, "Hey Google, interrompi la mia corsa su ExampleApp". Implementa questo intent integrato nell'app Fitness aggiungendo un secondo capability a shortcuts.xml:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.STOP_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <!-- Eg. name = "Running" -->
    <parameter
        android:name="exercise.name"
        android:key="stopExercise"/>
  </intent>
</capability>

Sostituisci PUT_YOUR_APPLICATION_ID_HERE con il tuo applicationId univoco.

Gestire i parametri degli intent integrati con un inventario in linea

Questo intent integrato supporta lo stesso parametro exercise.name dell'intent integrato START_EXERCISE, consentendo agli utenti di specificare l'esercizio attivo da terminare. Per attivare questa funzionalità, aggiungi un secondo insieme di elementi di scorciatoia dell'inventario a shortcuts.xml:

<!-- shortcuts.xml -->

<shortcut
  android:shortcutId="running"
  android:shortcutShortLabel="@string/activity_running">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/runningSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="walking"
  android:shortcutShortLabel="@string/activity_walking">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/walkingSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="cycling"
  android:shortcutShortLabel="@string/activity_cycling">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/cyclingSynonyms"/>
  </capability-binding>
</shortcut>

Soddisfa gli intent Android in arrivo

Per consentire all'app di gestire gli intent Android in arrivo di STOP_EXERCISE, aggiorna la classe FitMainActivity. Innanzitutto, aggiungi una variabile alla funzione handleIntent che contenga i dati di intent STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
  //...
}

A questo punto, aggiorna la logica condizionale della funzione handleIntent per gestire gli intent STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  //...
  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  <strong>
  } else if(stopExercise != null){
    // Stop the tracking service if any and return to home screen.
    stopService(Intent(this, FitTrackingService::class.java))
    updateView(FitStatsFragment::class.java)
  }
  </strong>
  //...
}

Nel codice precedente, hai aggiornato la funzione handleIntent per verificare l'intent integrato STOP_EXERCISE nell'intent Android in arrivo. Se trovata, la funzione interrompe il timer attivo e riporta l'utente alla schermata Home.

Testa l'azione app

Testa l'Azione app con il plug-in dell'Assistente Google procedendo nel seguente modo:

1. Esegui l'app in Android Studio selezionando Esegui > Esegui app o facendo clic sull'icona Esegui nella barra degli strumenti in alto.
2. Nell'app, avvia un nuovo comando "In esecuzione" allenamento.
3. Apri il plug-in in Android Studio: vai a Strumenti > Azioni app > Assistente Google > Strumento di test delle Azioni app.
4. Fai clic su Crea anteprima.
5. Seleziona l'intent integrato actions.intent.STOP_EXERCISE.
6. Nella casella exercise, lascia il valore predefinito running (corsa).
7. Fai clic su Run App Action (Esegui azione app). Verifica che l'assistente interrompa l'esercizio e ti riporti alla schermata Home.

Suggerimento:in caso di problemi con l'esecuzione dello strumento di test, consulta la guida alla risoluzione dei problemi.

6. Passaggi successivi

Complimenti!

Ora sai come attivare i comandi vocali per un'app Android utilizzando gli intent integrati dell'assistente. In questo codelab hai appreso:

• Come consentire agli utenti di approfondire le funzionalità specifiche dell'app usando l'assistente.
• Come utilizzare l'inventario in linea.
• Come testare gli intent integrati utilizzando il plug-in dell'Assistente Google.

Passaggi successivi

Da qui, puoi provare a perfezionare ulteriormente la tua app per il fitness. Per fare riferimento al progetto completato, vedi il ramo principale su GitHub.

Ecco alcuni suggerimenti per ulteriori informazioni su come estendere questa app con Azioni app:

• Dai un'occhiata agli altri nostri codelab sulle Azioni app.
• Consulta la documentazione di riferimento sugli intent integrati di Azioni app per scoprire altri intent integrati per estendere le tue app all'assistente.

Per continuare il tuo percorso con Actions on Google, esplora queste risorse:

• developers.google.com/assistant: sito di documentazione ufficiale per Actions on Google.
• Indice di esempio di Azioni app: app di esempio e codice per esplorare le funzionalità delle Azioni app.
• Repository GitHub di Actions on Google: codice e librerie di esempio.
• r/GoogleAssistantDev: community ufficiale di Reddit per gli sviluppatori che lavorano con l'Assistente Google.

Seguici su Twitter @ActionsOnGoogle per non perderti i nostri ultimi annunci e twitta a #appactions per condividere ciò che hai realizzato.

Sondaggio di opinione

Infine, ti invitiamo a rispondere a questo sondaggio per fornire un feedback sulla tua esperienza con questo codelab.