Estendi un'app per Android all'Assistente Google con Azioni app (livello 2)

1. Panoramica

Azioni app consente agli utenti di avviare direttamente funzionalità dell'app tramite l'Assistente Google per aiutarti a espandere la copertura della tua app per Android. In qualità di sviluppatore Android, puoi implementare funzionalità che consentano all'Assistente Google di conoscere il tipo di funzionalità disponibile per gli utenti e come vuoi soddisfare queste richieste.

Nel primo codelab sulle Azioni app hai imparato come estendere l'Assistente Google a un'app per il fitness di esempio implementando gli intent integrati (BII) della categoria degli intent integrati per salute e fitness. Gli intent integrati sono organizzati in categorie che rappresentano i tipi di attività che gli utenti chiedono spesso di eseguire all'assistente.

Termine chiave: un intent integrato dell'assistente, o BII, è un trigger predefinito per un tipo specifico di funzionalità che l'utente vuole eseguire. Google crea e gestisce i modelli linguistici per gli intent integrati al fine di comprendere un'ampia varietà di query correlate a questo particolare intento.

In questo codelab, imparerai come aggiungere Azioni app a un'app utilizzando gli intent integrati del "Common" Categoria BII, che rappresenta le attività comuni dell'app che quasi tutte le app per Android sono in grado di eseguire.

Questo codelab tratta concetti di livello intermedio per lo sviluppo con Azioni app. Avere esperienza pregressa nello sviluppo di app per Android e nell'implementazione degli intent di Android.

Cosa creerai

In questo codelab, aggiungerai due intent comuni a un'app di esempio per l'elenco di cose da fare, consentendo agli utenti di chiedere all'assistente di:

• Accedi alle funzionalità all'interno dell'app con l'intent integrato actions.intent.OPEN_APP_FEATURE.
• Cerca contenuti utilizzando la ricerca in-app con l'intent integrato actions.intent.GET_THING.

Nota: le app con funzionalità di ricerca sono necessarie per implementare l'intent integrato actions.intent.GET_THING. Scopri di più sui requisiti di deployment di Azioni app.

Figura 1. Tre schermate progressive in cui l'Assistente Google mostra le attività attive in un'app.

Obiettivi didattici

Imparerai a utilizzare gli intent integrati di categoria comuni per estendere l'assistente alla maggior parte delle app per Android. Imparerai inoltre a testare gli intent integrati comuni con il plug-in dell'Assistente Google per Android Studio.

Prerequisiti

• Un terminale per eseguire i comandi della shell con Git installato.
• L'ultima release stabile di Android Studio.
• Un dispositivo Android fisico o virtuale con accesso a internet al Google Play Store per testare le azioni.
• Devi aver eseguito l'accesso ad Android Studio con lo stesso Account Google e sia nell'app Google sia nell'app Assistente Google sul dispositivo di test.

Nota: puoi testare le Azioni app descritte in questo codelab con l'Assistente Google in un numero limitato di lingue. Per scoprire quali intent sono disponibili, in base alle impostazioni internazionali, consulta la documentazione di riferimento sull'intent integrato comune.

In questo codelab, utilizzerai un dispositivo Android (fisico o virtuale) per testare le tue azioni. Se utilizzi un dispositivo fisico, assicurati che sia connesso al computer di sviluppo locale. Devi anche aver eseguito l'accesso all'app Google sul dispositivo e ad Android Studio utilizzando lo stesso Account Google. Sul dispositivo deve essere installata anche l'app Assistente Google.

2. Come funziona

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

Quando un utente indica all'assistente di voler usare la tua app, l'assistente cerca le Azioni app registrate nella tua app da un file shortcuts.xml. Questo file contiene le funzionalità dell'app, che collega un intent o un intent personalizzato integrato dell'assistente a un intent o a un link diretto Android.

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

Quando un utente pronuncia una query all'assistente, l'assistente analizza l'input dell'utente e lo associa a un intent di Azioni app (in questo codelab, si tratterà di un intent integrato). L'assistente sa quali funzionalità supporti dal file shortcuts.xml nell'app per Android. Con la corrispondenza dell'intent, la funzionalità con questo intent integrato contiene come vuoi soddisfare questa richiesta. In questo codelab, il fulfillment è un intent Android che avvia un'attività nella tua app.

Il seguente diagramma mostra il flusso dell'assistente:

Figura 2. Un flusso che descrive in che modo l'Assistente Google elabora una query vocale.

Il file di progetto shortcuts.xml contiene le seguenti informazioni per ogni Azione app:

• Quale intent integrato o personalizzato per intenzione utilizza l'Azione app
• Quale attività Android o link diretto deve essere fornito all'utente
• In che modo i parametri per l'intent integrato vengono mappati alle informazioni fornite all'assistente dall'utente

La tua attività Android filtra e gestisce l'intent Android fornito o il link diretto per fornire all'utente la funzionalità desiderata. Il risultato è un'esperienza utente in cui l'assistente richiama la funzionalità dell'app in risposta alla query di un utente.

3. Prepara l'ambiente di sviluppo

Questo codelab utilizza l'app di esempio per l'elenco di cose da fare per Android. Questa app di esempio può aggiungere articoli a elenchi di cose da fare, cercare articoli per categoria e visualizzare informazioni sulle attività completate.

Scarica i tuoi file di base

Esegui questo comando per clonare il repository GitHub dell'app di esempio:

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

Una volta clonato il repository, segui questi passaggi per aprirlo 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.

Per visualizzare una versione dell'app che rappresenta il codelab completato, clona il repository dell'app di esempio utilizzando il flag --branch master.

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 aver aggiornato applicationId, riceverai il messaggio "I file Gradle sono stati modificati dall'ultima sincronizzazione del progetto..." in Android Studio. Fai clic su Sincronizza ora per evitare problemi durante il caricamento dell'app.

Testa l'app sul tuo dispositivo

Prima di apportare altre modifiche all'app, è utile avere un'idea di cosa può fare l'app di esempio. Per eseguire l'app sull'emulatore, segui questi passaggi:

1. In Android Studio, seleziona Esegui > Esegui app o fai clic su Esegui nella barra degli strumenti.
2. Nella finestra di dialogo Seleziona la destinazione del deployment, seleziona un dispositivo e fai clic su OK. La versione del sistema operativo consigliata è Android 10 (livello API 30) o versioni successive, anche se le azioni vengono eseguite sui dispositivi fino ad Android 5 (livello API 21).
3. Tieni premuto a lungo il pulsante Home per configurare l'assistente e verificarne il funzionamento. Dovrai accedere all'assistente sul tuo dispositivo, se non l'hai ancora fatto.

Per saperne di più sui dispositivi virtuali Android, vedi Creare e gestire dispositivi virtuali.

Figura 3. Un'animazione che mostra l'app di esempio con l'elenco di cose da fare.

Esplora brevemente l'app per vedere cosa sa fare. Se tocchi l'icona Più, viene creata una nuova voce di attività. Le voci di menu in alto a destra ti consentono di cercare e filtrare le voci delle attività in base allo stato di completamento.

Installa il plug-in di prova

Il plug-in dell'Assistente Google ti consente di testare le Azioni app su un dispositivo di test. Se non disponi già dello strumento di test, installalo procedendo 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". Puoi anche scaricare e installare manualmente lo strumento di test.
   • Se non riesci a trovare il plug-in in Marketplace, scaricalo manualmente e segui le istruzioni riportate in Installare il plug-in dal disco.
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.

4. Aggiungi la funzionalità degli intent integrati Get Thing

L'intent integrato actions.intent.GET_THING estende la funzionalità di ricerca in-app all'Assistente Google. In questo passaggio, implementerai e testerai l'intent integrato GET_THING, consentendo agli utenti di cercare attività specifiche nell'app di esempio.

Suggerimento: l'intent integrato GET_THING viene utilizzato per cercare contenuti o entità utilizzando la funzionalità di ricerca in-app predefinita in un'app. Compila i criteri di ricerca con il nome dei contenuti o dell'entità utilizzando il parametro intent thing.name e presenta i risultati di ricerca più pertinenti all'utente.

Definisci la funzionalità Get Thing

Durante un'Azione app correlata alla ricerca, l'assistente estrae i termini di ricerca dalla query dell'utente nel parametro dell'intent integrato thing.name, quindi lo passa all'app per Android.

Per aggiungere l'intent integrato GET_THING all'app, aggiorna shortcuts.xml, che si trova nella directory del progetto di esempio app/src/main/res/xml, con un elemento <capability> nel tag <shortcuts> di primo livello:

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

La configurazione qui sopra:

1. Dichiara che l'app risponde all'intent integrato GET_THING.
2. Specifica come creare un intent Android che avvia l'app in risposta all'intent integrato.
   • L'attività viene identificata utilizzando targetPackage e targetClass.
   • Il parametro dell'intent integrato thing.name è mappato nell'intent Extra denominato q.

L'attività denominata deve essere presente nel file manifest dell'app ed esportata.

L'applicazione Android fornita contiene metadati per indicare che AndroidManifest riconosce il file shortcuts.xml:

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

Testa l'azione app

Per testare la ricerca in-app della tua app dall'assistente, svolgi i seguenti passaggi:

1. Assicurati che il tuo dispositivo Android sia connesso.
2. Vai a Strumenti > Assistente Google > Strumento di test delle Azioni app.
3. Fai clic su Crea anteprima per accettare i valori predefiniti per Nome app e locale. Se richiesto, leggi e accetta le norme e i termini di servizio di Azioni app.
4. Nel primo passaggio in cui lo strumento ti chiede di selezionare e configurare un intent integrato, seleziona actions.intent.GET_THING. Modifica il valore di name da running shoes a milk.
5. Fai clic su Run App Action (Esegui azione app).

In questo test, l'intent integrato GET_THING utilizza l'attributo name per cercare nell'app attività contenenti "latte". Come nel caso dell'Azione app precedente, puoi testare l'azione usando lo strumento di test oppure semplicemente dire "Hey Google, cerca il mix di dolci nell'elenco attività" o altre frasi di ricerca sul dispositivo di test.

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

5. Aggiungi la funzionalità degli intent integrati per la funzionalità Apri app

In questo passaggio implementerai l'intent integrato per la funzionalità Apri app, che consente agli utenti di visualizzare le loro attività attive e completate utilizzando l'assistente. Per farlo, completa la funzionalità in shortcuts.xml, che contiene informazioni su come viene attivata la funzionalità, come vengono passati i parametri e quali intent Android richiamare. Per questo codelab, utilizzerai l'intent integrato OPEN_APP_FEATURE. Dopo aver implementato questo intent integrato, testerai l'azione sul tuo dispositivo.

Nota: questo intent integrato avvia una funzionalità dell'app. Questo intent è particolarmente utile per aiutare gli utenti a raggiungere funzionalità all'interno dell'app che altrimenti potrebbero essere difficili da trovare o che richiedono più tocchi per accedervi. Devi specificare l'inventario in linea per il parametro della funzionalità.

Aggiungi la funzionalità Apri app

Aggiungi una seconda funzionalità per la funzionalità Apri app in shortcuts.xml sotto l'elemento Ottieni funzionalità:

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

Questa funzionalità mappa l'intent integrato dell'app aperta e l'intent Android in modo che, quando viene attivata la funzionalità Apri app, anche l'intent Android si attivi.

Prima di attivare l'intent Android, i parametri supportati vengono estratti dall'input dell'utente. L'intent integrato OPEN_APP_FEATURE supporta un parametro, feature, che rappresenta la funzionalità dell'app estratta dalla query dell'utente. Questa applicazione supporterà due tipi di funzionalità: Attività attiva e Attività completata. Queste funzionalità consentono agli utenti di aprire l'app con una visualizzazione filtrata del proprio elenco di attività. Per supportare queste funzionalità, devi utilizzare l'inventario in linea.

Termine chiave: un inventario in linea guida l'estrazione delle entità per gli intent integrati fornendo un insieme di entità che l'app riconosce a un parametro dell'intent integrato che supporta l'inventario in linea. Per maggiori dettagli, vedi Inventario incorporato per Azioni app.

Gestire i parametri di intent utilizzando l'inventario in linea

I parametri di intent rappresentano gli elementi estratti da una query dell'utente. Ad esempio, se un utente dice, ad esempio, "Hey Google, ordina una pizza da EsempioApp", l'assistente estrae "pizza". in un parametro di intent schema.org di food.item e passa il parametro all'azione da gestire.

L'intent integrato della funzionalità dell'app aperta supporta un parametro, feature, che rappresenta la funzionalità dell'app estratta dalla query dell'utente. Per questo parametro è necessario un inventario in linea, che fornisca all'assistente un insieme di nomi di funzionalità delle app supportati da abbinare al valore del parametro.

Per gestire il parametro di intent feature, aggiungi una scorciatoia a shortcuts.xml con il seguente codice sopra la funzionalità della funzionalità Apri app:

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

Nel codice riportato sopra hai definito un inventario in linea, rappresentato da elementi shortcut con associazioni di funzionalità e parametri. Le scorciatoie possono essere utilizzate come inventario per i parametri degli intent integrati. L'Assistente Google associa la query dell'utente ai valori nell'associazione di parametri delle scorciatoie. Per il valore di un parametro corrispondente, shortcutId verrà aggiunto all'intent di completamento. Quando un utente attiva l'intent integrato OPEN_APP_FEATURE con una richiesta, l'assistente associa il valore del parametro della funzionalità all'attributo del valore di una scorciatoia, passando il valore a targetClass come parameter in Extra.

Ad esempio, se un utente dice qualcosa come "Hey Google, mostrami le attività completate in ExampleApp", l'assistente associa il valore del parametro per l'intent della funzionalità "attività completate" alla corrispondente scorciatoia per l'inventario, che passa quel valore alla funzionalità OPEN_APP_FEATURE. L'assistente attiva quindi l'intent Android.

Testa l'azione app

Durante lo sviluppo e i test, utilizzi il plug-in dell'Assistente Google per visualizzare l'anteprima dell'Azione app con l'assistente su un dispositivo di test. Puoi utilizzare lo strumento anche per regolare i parametri di intent di un'Azione app e verificare in che modo questa gestisce i vari modi in cui un utente potrebbe chiedere all'assistente di eseguirla.

Per testare l'Azione app con lo strumento di test:

1. Collega il tuo dispositivo fisico di test Android o avvia l'emulatore Android
2. Se lo strumento di test non è visibile, aprilo in Strumenti > Assistente Google > Strumento di test delle Azioni app.
3. Fai clic sul pulsante Aggiorna per aggiornare l'anteprima.
4. Nel primo passaggio in cui lo strumento ti chiede di selezionare e configurare un intent integrato, seleziona actions.intent.OPEN_APP_FEATURE.
5. Nella casella feature, aggiorna il valore predefinito di History con Completed tasks.
6. Fai clic su Run App Action (Esegui azione app).

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

In alternativa, puoi utilizzare il nome di chiamata direttamente nell'app Assistente sul tuo dispositivo per provare l'Azione app. Ad esempio, potresti dire "Hey Google, mostra le attività completate nell'elenco attività".

6. Passaggi successivi

Complimenti!

Ora puoi consentire a quasi tutte le app per Android di funzionare con l'Assistente Google, utilizzando gli intent integrati comuni.

Argomenti trattati

In questo codelab hai appreso:

• Come consentire agli utenti di approfondire le funzionalità specifiche dell'app usando l'assistente.
• In che modo gli utenti possono accedere alla ricerca in-app dall'assistente.
• Come testare gli intent integrati comuni utilizzando il plug-in dell'Assistente Google.

Passaggi successivi

Da qui, puoi provare a perfezionare ulteriormente l'app dell'elenco di cose da fare. Per fare riferimento al progetto completato, consulta il repository –master Branch su GitHub.

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

• Per scoprire come monitorare il rendimento delle Azioni app, consulta l'esempio di elenco di cose da fare con Google Analytics per Firebase.
• Consulta la documentazione di riferimento sugli intent integrati di Azioni app per scoprire altri modi 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 #AoGDevs per condividere ciò che hai realizzato.

Sondaggio di feedback

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