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

1. Panoramica

Le Azioni app consentono agli utenti di avviare direttamente funzionalità specifiche delle app dall'Assistente Google per aiutarti a espandere la copertura della tua app per Android. In qualità di sviluppatore Android, puoi implementare funzionalità che consentono all'Assistente Google di conoscere il tipo di funzionalità disponibile per gli utenti e il modo in cui vuoi soddisfare queste richieste.

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

Termine chiave: un intent integrato dell'assistente, o BII in breve, è 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 per comprendere un'ampia gamma di query correlate a quell'intent specifico.

In questo codelab imparerai ad aggiungere Azioni app a un'app utilizzando gli intent integrati della categoria "Comune", che rappresenta le attività comuni delle app che quasi tutte le app per Android possono svolgere.

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

Cosa creerai

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

• Vai 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 devono implementare l'intent integrato actions.intent.GET_THING. Scopri di più sui requisiti di implementazione di Azioni app.

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

Obiettivi didattici

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

Prerequisiti

• Un terminale per eseguire comandi 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 accedere ad Android Studio con lo stesso Account Google e sia l'app Google sia l'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 impostazioni internazionali. Consulta la documentazione di riferimento Common BII per scoprire quali intent sono disponibili in base alle impostazioni internazionali.

In questo codelab, utilizzi un dispositivo Android (fisico o virtuale) per testare le azioni. Se utilizzi un dispositivo fisico, assicurati che sia connesso alla tua macchina 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. Comprendere il funzionamento

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

Quando un utente indica all'assistente che vuole utilizzare la tua app, l'assistente cerca le Azioni app registrate per la tua app in un file shortcuts.xml. Questo file contiene le funzionalità dell'app, che collegano un intent integrato o personalizzato dell'assistente a un intent o a un link diretto di 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 la tua app e passare direttamente a un'attività specifica. Per maggiori dettagli, consulta la documentazione di Android sulle funzionalità.

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

Il seguente diagramma mostra questo flusso dell'assistente:

Figura 2. Un flusso che descrive come 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 utilizza l'Azione app
• Quale attività o link diretto Android deve essere fornito all'utente
• Come i parametri della mappa degli intent integrata vengono mappati alle informazioni fornite all'assistente dall'utente

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

3. Prepara l'ambiente di sviluppo

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

Scaricare i file di base

Esegui il comando seguente 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

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

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 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 riceverai l'avviso "I file Gradle sono stati modificati dall'ultima sincronizzazione del progetto...". Fai clic su Sincronizza ora per evitare problemi durante il caricamento dell'app.

Testare l'app sul dispositivo

Prima di apportare altre modifiche all'app, è utile farsi 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 target di 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 su dispositivi con Android 5 (livello API 21).
3. Tieni premuto il pulsante Home per configurare l'assistente e verificarne il funzionamento. Se non l'hai ancora fatto, dovrai accedere all'assistente sul tuo dispositivo.

Per ulteriori informazioni sui dispositivi virtuali Android, vedi Creare e gestire dispositivi virtuali.

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

Esplora brevemente l'app per vedere cosa può fare. Toccando l'icona Più viene creato un nuovo elemento attività e le voci di menu in alto a destra consentono di cercare e filtrare gli elementi attività in base allo stato di completamento.

Installa il plug-in di test

Il plug-in dell'Assistente Google ti consente di testare le Azioni app su un dispositivo di test. Se non hai ancora lo strumento di test, installalo seguendo questi passaggi:

1. Vai a File > Impostazioni (Android Studio > Preferenze su macOS).
2. Nella sezione Plug-in, vai a Marketplace e cerca "Google Assistant".Puoi anche scaricare e installare manualmente lo strumento di test.
   • Se non riesci a trovare il plug-in su 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 test invia informazioni all'assistente tramite l'app Google sul tuo dispositivo Android.

4. Aggiungi l'intent integrato 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 di un'app. Compila i criteri di ricerca con il nome del contenuto o dell'entità utilizzando il parametro di intent thing.name e mostra all'utente i risultati di ricerca più pertinenti.

Definisci la funzionalità Recupero cosa

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

Per aggiungere l'intent integrato GET_THING alla tua app, aggiorna shortcuts.xml, che si trova nella directory del progetto di esempio app/src/main/res/xml, con un elemento <capability> all'interno del 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 precedente:

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

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

L'applicazione Android fornita contiene metadati, quindi AndroidManifest è a conoscenza del file shortcuts.xml:

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

Testare l'Azione app

Per testare la ricerca in-app per la tua app dall'assistente, segui questi passaggi:

1. Assicurati che il tuo dispositivo Android sia connesso.
2. Vai a Strumenti > Google Assistant > 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 Esegui azione app.

In questo test, l'intent integrato GET_THING utilizza l'attributo name per cercare nell'app attività contenenti "latte". Come per l'Azione app precedente, puoi testare l'azione utilizzando lo strumento di test o semplicemente dire "Hey Google, cerca preparato per torta in Elenco attività" o altre frasi di ricerca sul tuo dispositivo di test.

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

5. Aggiungere la funzionalità di intent integrato Apri app

In questo passaggio, implementa l'intent integrato della funzionalità Apri app, consentendo agli utenti di visualizzare le 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, testa l'azione sul tuo dispositivo.

Nota:questo intent integrato avvia una funzionalità dell'app. È particolarmente utile per aiutare gli utenti a navigare verso funzionalità all'interno dell'app che altrimenti potrebbero essere difficili da trovare o richiedere più tocchi per essere raggiunte. Devi specificare inline inventory per il parametro della funzionalità.

Aggiungere la funzionalità Apri app

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

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 della funzionalità Apri app e l'intent Android insieme, in modo che quando viene attivata la funzionalità Apri app, venga attivato l'intent Android.

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 supporta due tipi di funzionalità: Attività attiva e Attività completata. Queste funzionalità consentono agli utenti di aprire l'app con una visualizzazione filtrata dell'elenco delle attività. Per supportare queste funzionalità, devi utilizzare l'inventario in linea.

Termine chiave: un'entità di guida all'inventario in linea per l'estrazione di entità per gli intent integrati fornisce un insieme di entità che un'app comprende a un parametro di intent integrato che supporta l'inventario in linea. Per maggiori dettagli, vedi Inventario in linea per le Azioni app.

Gestire i parametri di intent utilizzando l'inventario incorporato

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

L'intent integrato della funzionalità Apri app 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à dell'app supportati a cui abbinare il valore del parametro.

Per gestire il parametro intent feature, aggiungi una scorciatoia a shortcuts.xml con il seguente codice sopra la 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 precedente hai definito un inventario incorporato, rappresentato come elementi shortcut con binding 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 nel binding dei parametri delle scorciatoie. Per un valore del parametro corrispondente, shortcutId verrà aggiunto all'intent di evasione. Quando un utente attiva l'intent integrato OPEN_APP_FEATURE con una richiesta, l'assistente associa il valore del parametro della funzionalità all'attributo valore di una scorciatoia, passando il valore a targetClass come parameter in Extra.

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

Testare l'Azione app

Durante lo sviluppo e il test, utilizzi il plug-in dell'Assistente Google per visualizzare l'anteprima dell'Azione app con l'assistente su un dispositivo di test. Puoi anche utilizzare lo strumento per modificare i parametri di intent per un'Azione app, per testare il modo in cui l'azione 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 dispositivo di test Android fisico o avvia l'emulatore Android.
2. Se lo strumento di test non è visibile, aprilo andando a 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 History con Completed tasks.
6. Fai clic su Esegui azione app.

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

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

6. Passaggi successivi

Complimenti!

Ora puoi attivare quasi tutte le app per Android per farle funzionare con l'Assistente Google utilizzando gli intent integrati comuni.

Argomenti trattati

In questo codelab hai imparato:

• Come consentire agli utenti di approfondire funzionalità specifiche dell'app utilizzando l'assistente.
• Come 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 Elenco cose da fare. Per fare riferimento al progetto finito, consulta il repository – master branch su GitHub.

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

• Consulta l'esempio di elenco di cose da fare con Google Analytics for Firebase per scoprire come monitorare il rendimento delle tue Azioni app.
• Visita il riferimento agli intent integrati di Azioni app per scoprire altri modi 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 #AoGDevs per condividere ciò che hai creato.

Sondaggio di feedback

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