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

1. Panoramica

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

Questo codelab tratta i concetti di livello principiante per lo sviluppo con Azioni app. Per seguire questo codelab, devi avere esperienza pregressa con lo sviluppo di app per Android e con gli intent di Android. Se non hai mai utilizzato Android, ti consigliamo di iniziare con uno dei codelab per le nozioni di base per gli sviluppatori Android.

Cosa creerai

In questo codelab, aggiungerai due intent integrati (BII) di Azioni app a un'app per il fitness Android di esempio, consentendo agli utenti di avviare e interrompere un timer per l'allenamento usando la voce.

Obiettivi didattici

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

Prerequisiti

Prima di continuare, assicurati di avere i seguenti strumenti nel tuo ambiente:

• Un terminale per eseguire comandi 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 per il Play Store.

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

2. Comprendere il funzionamento

Le Azioni app collegano gli utenti dell'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'Azione app capability definita nella risorsa XML shortcuts.xml della tua app.

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

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

Ogni elemento di funzionalità definisce:

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

Intent

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

Fulfillment

Quando una richiesta utente attiva un'Azione app in shortcuts.xml, l'attività Android deve rilevare e gestire l'intent o il link diretto Android in entrata 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 campione Fitness per Android. Questa app consente agli utenti di avviare e arrestare un timer di allenamento e visualizzare statistiche sulle loro routine di allenamento.

Scaricare i file di base

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

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

Dopo aver clonato il repository, aprilo in Android Studio:

1. Nella finestra di dialogo 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 estrae il ramo codelab-start del repository, che è il punto di partenza di questo codelab. Per andare avanti e vedere l'app dopo aver completato le istruzioni del codelab, consulta il ramo principale del repository.

Aggiornare l'ID applicazione Android

L'aggiornamento dell'ID applicazione dell'app identifica in modo univoco l'app sul dispositivo di test ed evita l'errore "Nome del 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 con un nome univoco.

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

Provare l'app sul dispositivo

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

1. Apertura del dispositivo di test Android virtuale o fisico.
2. Verifica che l'app Assistente funzioni.
3. Utilizzando Android Studio per eseguire il deployment ed eseguire l'app di esempio sul tuo dispositivo.

Per testare l'app, segui questi passaggi:

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 target di 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 su dispositivi con Android 5 (livello API 21) o versioni successive.
3. Dopo aver aperto l'app, tieni premuto il tasto Home per configurare l'assistente e verificare che funzioni. Accedi all'assistente se non l'hai ancora fatto.
4. Riapri l'app.

Nota:per ulteriori informazioni sui dispositivi virtuali, vedi Creare e gestire dispositivi virtuali.

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

Esplora brevemente l'app per vedere cosa può fare. Toccando l'icona Corsa si avvia un timer per l'esercizio e toccando l'icona X si arresta il timer. Queste sono le attività che attiverai per il controllo vocale con le Azioni app.

Installare 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 aggiungerlo ad Android Studio:

1. Vai a 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 test 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. Aggiungere l'intent integrato Avvia allenamento

L'intent integrato actions.intent.START_EXERCISE consente agli utenti di aprire un'app e iniziare un allenamento usando la voce. In questo passaggio, implementi una funzionalità per questo intent integrato, che consente agli utenti di chiedere all'assistente di iniziare una corsa nell'app Fitness.

Definisci la funzionalità

L'assistente utilizza gli elementi capability definiti in shortcuts.xml per elaborare i comandi vocali con i seguenti passaggi:

1. L'assistente abbina la query vocale dell'utente a un intent integrato definito nelle funzionalità della tua app.
2. L'assistente estrae i valori dalla query nei parametri dell'intent integrato. Ogni parametro viene aggiunto a un Bundle allegato a un Intent generato.
3. L'assistente utilizza Intent per avviare l'app, consentendole di accedere ai parametri inclusi.

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 alla tua 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 applicationId univoco definito nel passaggio precedente.

L'XML di esempio precedente:

• Dichiara una funzionalità per l'intent integrato START_EXERCISE.
• Specifica l'intent Android intent che l'assistente genera per avviare l'app:
  • Gli attributi targetPackage e targetClass specificano l'attività di ricezione.
  • L'attributo parameter mappa il parametro exercise.name dell'intent integrato a exerciseType negli extra Bundle ricevuti dall'attività.

Gestire i parametri BII con un inventario in linea

I parametri degli intent integrati rappresentano gli elementi estratti da una query dell'utente dell'assistente. Ad esempio, quando un utente dice "Hey Google, inizia una corsa su EsempioApp", l'assistente estrae "corsa" nel parametro intent integrato exercise.name schema.org. Per alcuni intent integrati, puoi chiedere all'assistente di abbinare i parametri dell'intent integrato a un insieme di identificatori previsti dalla tua app.

A questo scopo, associa gli elementi inventario in linea al parametro dell'intent integrato. Un inventario in linea è un insieme di valori dei parametri BII supportati, ad esempio "corri", "cammina" e "fai jogging", e il relativo ID scorciatoia, ad esempio EXERCISE_RUN. Questo binding dell'inventario consente all'assistente di trasmettere l'ID scorciatoia per i parametri corrispondenti, anziché il valore della query non elaborata, all'attività di evasione.

Alcuni parametri BII, come exercise.name, richiedono un inventario in linea per funzionare. Per gestire questo parametro, aggiungi i seguenti elementi dell'inventario shortcut 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 corrisponde al parametro exercise.name dell'intent integrato.

Nota:dopo aver completato questo passaggio, Android Studio potrebbe avvisarti che non riesce a risolvere i simboli per i valori dei sinonimi. Risolvi il problema completando il passaggio successivo.

Aggiungere sinonimi di 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 ogni elemento dell'inventario. I sinonimi consentono di utilizzare varianti di un tipo di elemento, come "corsa", "jogging" e "sprint", per fare riferimento alla stessa 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>

Soddisfare gli intent Android in entrata

Gli intent di Android sono oggetti di messaggistica che Android utilizza per richiedere un'azione a un'altra app. L'assistente soddisfa le query vocali degli utenti generando un intent dai dettagli di configurazione nella funzionalità attivata. Per soddisfare gli intent per la funzionalità START_EXERCISE, aggiorna la classe target FitMainActivity per gestire l'intent in entrata e i parametri BII.

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

Dopodiché, 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 dell'intent Azione app vengono passati alla funzione handleIntent. I parametri BII raggruppati nell'intent START_EXERCISE sono accessibili tramite intent?.extras?.getString(START_EXERCISE). Il resto della funzione aggiorna FitTrackingFragment per visualizzare il tipo di attività startExercise scelto.

Testare l'Azione app

Durante lo sviluppo delle Azioni app, utilizzi il plug-in dell'Assistente Google per visualizzare l'anteprima delle tue azioni su un dispositivo di test. Puoi anche utilizzare il plug-in per modificare i valori dei parametri dell'intent di un'Azione per testare il modo in cui la tua app gestisce i vari modi in cui un utente potrebbe formulare una richiesta all'assistente per la tua app.

Per testare l'Azione app con il plug-in, segui questi passaggi:

1. Esegui l'app in Android Studio scegliendo Run (Esegui) > Run App (Esegui app) o facendo clic sull'icona Run (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 esercizio, lascia il valore predefinito corsa.
6. Fai clic su Esegui azione app. Verifica che i link diretti dell'assistente portino al timer per l'allenamento dell'app e che il timer abbia avviato un allenamento di tipo corsa.

Suggerimento:consulta la guida alla risoluzione dei problemi se riscontri problemi durante l'esecuzione dello strumento di test.

Hai implementato le tue prime Azioni app con l'intent integrato START_EXERCISE. Complimenti! Successivamente, consentiremo agli utenti di interrompere un allenamento in corso nella tua app.

5. Aggiungere la funzionalità Interrompi esercizio BII

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 BII con un inventario in linea

Questo intent integrato supporta lo stesso parametro exercise.name dell'intent integrato START_EXERCISE, consentendo agli utenti di specificare quale allenamento attivo vogliono terminare. Per attivare questa opzione, 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>

Soddisfare gli intent Android in entrata

Abilita l'app a gestire gli intent Android STOP_EXERCISE in entrata aggiornando la classe FitMainActivity. Innanzitutto, aggiungi una variabile alla funzione handleIntent per contenere i dati sull'intent STOP_EXERCISE:

// FitMainActivity.kt

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

Successivamente, 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 la presenza dell'intent integrato STOP_EXERCISE nell'intent Android in entrata. Se viene trovato, la funzione interrompe il timer attivo e riporta l'utente alla schermata Home.

Testare l'Azione app

Per testare l'Azione app utilizzando il plug-in dell'Assistente Google:

1. Esegui l'app in Android Studio scegliendo Run (Esegui) > Run App (Esegui app) o facendo clic sull'icona Run (Esegui) nella barra degli strumenti in alto.
2. Nell'app, avvia un nuovo esercizio di "corsa".
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 esercizio, lascia il valore predefinito corsa.
7. Fai clic su Esegui azione app. Verifica che l'assistente interrompa l'allenamento e ti riporti alla schermata Home.

Suggerimento:consulta la guida alla risoluzione dei problemi se riscontri problemi durante l'esecuzione dello strumento di test.

6. Passaggi successivi

Complimenti!

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

• Come consentire agli utenti di approfondire funzionalità specifiche dell'app utilizzando 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 finito, consulta il ramo principale su GitHub.

Ecco alcuni suggerimenti per approfondire l'estensione di questa app con Azioni app:

• Dai un'occhiata agli altri nostri codelab sulle Azioni app.
• Visita il riferimento agli intent integrati di Azioni app per scoprire altre BII per estendere le tue app all'assistente.

Per continuare il tuo percorso con Azioni su Google, esplora queste risorse:

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

Seguici su Twitter @ActionsOnGoogle per rimanere al corrente sui nostri ultimi annunci e twitta con l'hashtag #appactions per condividere ciò che hai creato.

Sondaggio di opinione

Infine, compila questo sondaggio per fornire un feedback sulla tua esperienza con questo codelab.