Creare un'azione canvas interattiva per l'Assistente Google con Actions Builder

1. Panoramica

Actions on Google è una piattaforma di sviluppo che ti consente di creare software per estendere la funzionalità dell'Assistente Google, l'assistente personale virtuale di Google, su oltre un miliardo di dispositivi, tra cui smart speaker, smartphone, auto, TV, cuffie e altro ancora. Gli utenti interagiscono con l'Assistente Google per svolgere attività come acquistare generi alimentari o prenotare una corsa. Per un elenco completo di ciò che è possibile fare ora, consulta la directory delle azioni. In qualità di sviluppatore, puoi utilizzare Actions on Google per creare e gestire facilmente esperienze conversazionali utili e piacevoli tra gli utenti e il tuo servizio di terze parti.

Questo codelab è un modulo avanzato destinato ai lettori che hanno già esperienza nella creazione di Azioni per l'Assistente Google. Se non hai esperienza di sviluppo precedente con Azioni su Google, acquisisci familiarità con la piattaforma seguendo i codelab introduttivi ( livello 1 e livello 2). Questi moduli ti guideranno attraverso una serie di funzionalità che possono aiutarti a espandere la funzionalità dell'azione e ad aumentare il tuo pubblico.

In questo codelab, utilizzi Interactive Canvas, un framework basato su Google Assistant, per aggiungere un gioco a schermo intero a un'azione conversazionale. Il gioco è un'app web interattiva che l'assistente invia come risposta all'utente nella conversazione. L'utente può quindi giocare tramite input vocale o di testo su smart display e dispositivi mobili Android.

Anziché creare un intero gioco, implementi un gioco parzialmente predefinito chiamato Snow Pal e aggiungi la logica del gioco man mano che avanzi nel codelab. Snow Pal è una variante del tradizionale gioco Impiccato. Il gioco ti presenta una serie di spazi vuoti che rappresentano una parola e tu devi indovinare le lettere che ritieni possano far parte della parola. A ogni risposta errata, il tuo amico di neve si scioglie un po' di più. Vinci la partita se riesci a indovinare la parola prima che il tuo amico di neve si sciolga completamente.

Figura 1. Una partita a Snow Pal parzialmente completata

Cosa creerai

In questo codelab, creerai un'azione che utilizza Interactive Canvas. La tua Azione avrà le seguenti funzionalità:

Un gioco di parole a schermo intero che gli utenti possono giocare con i comandi vocali
Un pulsante che gli utenti possono premere per iniziare la partita
Un pulsante che gli utenti possono premere per giocare di nuovo

Al termine di questo codelab, l'azione completata avrà il seguente flusso conversazionale:

Assistente: Welcome to Snow Pal! Would you like to start playing the game?

Utente: Yes.

Assistente: Try guessing a letter in the word or guessing the word.

Utente: I guess the letter E.

Assistente: Let's see if your guess is there...E is right. Right on! Good guess.

L'utente continua a indovinare le lettere o la parola sconosciuta fino alla fine della partita.

Obiettivi didattici

Come creare ed eseguire il deployment di un'azione Interactive Canvas
Come aggiornare il gioco di parole in base all'input vocale e tattile di un utente
Come trasferire dati all'app web utilizzando metodi diversi
Come eseguire il debug dell'azione Interactive Canvas

Che cosa ti serve

I prerequisiti per questo codelab includono quanto segue:

Un browser web, ad esempio Google Chrome
Un IDE o un editor di testo a tua scelta
Node.js, npm e git installati sul tuo computer

Per comprendere il codice utilizzato in questo codelab, è consigliabile avere familiarità con JavaScript (ES6).

(Facoltativo) Ottieni il codice campione completo

In questo codelab, creerai il campione passo dopo passo a partire da una versione incompleta. Se preferisci, puoi anche scaricare l'esempio completato dal repository GitHub.

2. Introduzione a Canvas interattivo

Interactive Canvas è un framework basato sull'Assistente Google che ti consente di aggiungere immagini e animazioni a schermo intero alla tua Azione conversazionale.

Un'azione che utilizza Interactive Canvas funziona in modo simile a una normale azione conversazionale. Tuttavia, un'azione Interactive Canvas ha la capacità aggiuntiva di inviare una risposta al dispositivo che apre un'app web a schermo intero.

L'utente fornisce input all'app web tramite voce o tocco fino al termine della conversazione.

Figura 2. Un'azione creata con Interactive Canvas.

In questo codelab, il progetto è organizzato nelle tre parti principali seguenti:

App web:i file dell'app web contengono il codice per gli elementi visivi e le animazioni dell'app web, nonché la logica per aggiornare l'app web in base all'input di un utente.
Azione conversazionale: l'azione conversazionale contiene la logica della conversazione, che riconosce, elabora e risponde all'input dell'utente.
Webhook:il webhook gestisce la logica del gioco. Per questo codelab, puoi considerare il webhook come il tuo server di gioco.

Per ogni sezione di questo codelab, modifichi l'app web, l'Azione conversazionale e il webhook per aggiungere funzionalità all'Azione Interactive Canvas.

A livello generale, l'azione conversazionale, il webhook e l'app web nell'azione Snow Pal funzionano nel seguente modo:

L'azione conversazionale chiede all'utente di indovinare una lettera della parola o l'intera parola.
L'utente dice "Credo che la lettera sia la i" all'app web Snow Pal su uno smart display.
L'input dell'utente viene indirizzato all'Azione conversazionale, definita nel progetto Actions Builder e/o Actions SDK.
L'azione conversazionale elabora l'input dell'utente e, a seconda dell'input, attiva la logica nel webhook che aggiorna l'app web o invia metadati per aggiornare direttamente l'app web.
L'app web si aggiorna per mostrare la posizione della lettera nella parola e all'utente viene chiesto di indovinare di nuovo.

Scopri di più su come funziona Interactive Canvas nella sezione Comprendere l'infrastruttura di Interactive Canvas. Ora che conosci le nozioni di base, puoi iniziare a configurare l'ambiente per questo codelab.

3. Configura

Verifica le impostazioni delle autorizzazioni Google

Per testare l'azione che crei per questo codelab, devi abilitare le autorizzazioni necessarie in modo che il simulatore della console Azioni possa accedere alla tua azione. Per attivare le autorizzazioni:

Vai a Gestione attività.
Se necessario, accedi con il tuo Account Google.
Attiva le seguenti autorizzazioni:

Attività web e app
In Attività web e app, seleziona la casella di controllo Includi la cronologia di Chrome e le attività svolte su siti, app e dispositivi che usano i servizi Google.

Installare l'interfaccia a riga di comando gactions

In questo codelab, utilizzi lo strumento di interfaccia a riga di comando (CLI) gactions per sincronizzare il tuo progetto Azioni tra la console Azioni e il tuo file system locale.

Per installare gactions CLI, segui le istruzioni nella sezione Installa lo strumento a riga di comando gactions.

Installa l'interfaccia a riga di comando di Firebase

L'interfaccia a riga di comando (CLI) di Firebase ti consente di eseguire il deployment del progetto Azioni su Cloud Functions e ospitare la tua app web.

Questo codelab utilizza npm per installare l'interfaccia a riga di comando di Firebase. Assicurati di installare npm, che in genere viene fornito con Node.js.

Per installare o eseguire l'upgrade della CLI, apri un terminale ed esegui il seguente comando npm:

npm install -g firebase-tools

Per verificare che la CLI sia stata installata correttamente, esegui questo comando:

firebase --version

Assicurati che la versione dell'interfaccia a riga di comando di Firebase sia 8 o successive, in modo da disporre di tutte le funzionalità più recenti richieste per Cloud Functions. In caso contrario, esegui npm install -g firebase-tools per l'upgrade.

Per accedere a Firebase, esegui questo comando:

firebase login

Quando accedi a Firebase, assicurati di utilizzare lo stesso Account Google che hai utilizzato per creare il progetto Azioni.

Clona il repository

In questa sezione clonerai i file necessari per questo codelab. Per ottenere questi file, segui questi passaggi:

Apri un terminale e passa a una directory in cui di solito memorizzi i progetti di programmazione. Se non ne hai una, passa alla directory home.
Per clonare questo repository, esegui questo comando nel terminale:

git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

Apri la directory start/. Questo repository contiene le seguenti directory importanti con cui lavorerai:

public/: questa directory contiene il codice HTML, CSS e JavaScript per la tua app web.
sdk/custom/: questa directory contiene la logica dell'azione conversazionale (scene, intent e tipi).
sdk/webhooks/: questa directory è il webhook e contiene la logica di gioco.

Figura 3. La struttura del codice della directory start.

4. Configurare il progetto Actions

In questa sezione, crei e configuri il progetto Azioni, esegui il push del codice dal repository clonato alla console Azioni con la CLI gactions e implementi l'app web e il webhook.

crea un progetto Actions

Il progetto Actions è un contenitore per l'azione. Per creare il progetto Azioni per questo codelab:

Apri la console Azioni.
Fai clic su Nuovo progetto.
Digita un Nome progetto, ad esempio canvas-codelab. Questo nome è solo per riferimento interno. In un secondo momento, potrai impostare un nome esterno per il progetto.

Fai clic su Crea progetto.
Nella schermata Che tipo di azione vuoi creare?, seleziona la scheda Gioco.
Fai clic su Avanti.
Seleziona la scheda Progetto vuoto.
Fai clic su Inizia a creare.

Salva l'ID progetto per l'azione

L'ID progetto è un identificatore univoco della tua azione. L'ID progetto ti servirà per diversi passaggi di questo codelab.

Per recuperare l'ID progetto:

Nella console Azioni, fai clic sui tre puntini verticali > Impostazioni progetto.

Copia l'ID progetto.

Associare un account di fatturazione

Per eseguire il deployment del fulfillment più avanti in questo codelab utilizzando Cloud Functions, devi associare un account di fatturazione al tuo progetto in Google Cloud. Se hai già un account di fatturazione, puoi ignorare i passaggi seguenti.

Per associare un account di fatturazione al tuo progetto:

Vai alla pagina di fatturazione di Google Cloud Platform.
Fai clic su Aggiungi account di fatturazione o Crea account.
Compila i dati di pagamento.
Fai clic su Inizia la mia prova senza costi o Invia e attiva la fatturazione.
Vai alla pagina di fatturazione Google Cloud.
Fai clic sulla scheda I miei progetti.
Fai clic sui tre puntini > Modifica fatturazione.
Nel menu a discesa, seleziona l'account di fatturazione che hai configurato.
Fai clic su Imposta account.

Per evitare addebiti, segui i passaggi descritti nella sezione Esegui la pulizia del progetto.

Esegui il deployment dell'app web

In questa sezione, esegui il deployment della tua app web (il gioco Snow Pal) utilizzando l'interfaccia a riga di comando di Firebase. Una volta eseguito il deployment, puoi recuperare l'URL dell'app web e vedere l'aspetto del gioco in un browser.

Per eseguire il deployment della tua app web, segui questi passaggi:

Nel terminale, vai alla directory start/.
Esegui questo comando, sostituendo {PROJECT_ID} con il tuo ID progetto:

firebase deploy --project {PROJECT_ID} --only hosting

Dopo qualche minuto, dovresti vedere "Deploy complete!", che indica che hai eseguito il deployment dell'app web Snow Pal su Firebase.

Per visualizzare il gioco Snow Pal in un browser:

Recupera l'URL di hosting fornito nell'output del terminale. L'URL deve avere il seguente formato: https://<PROJECT_ID>.web.app

Incolla l'URL in un browser. Dovresti visualizzare la schermata iniziale del gioco Snow Pal con il pulsante Inizia partita:

Aggiungere l'URL dell'app web e l'ID progetto al progetto Actions

Poi, aggiungi l'URL dell'app web e l'ID progetto al file actions.intent.MAIN.yaml. L'aggiunta dell'URL dell'app web consente all'azione conversazionale di sapere a quale URL inviare i dati, mentre l'aggiunta dell'ID progetto in settings.yaml ti consente di trasferire i file scaricati nel progetto corretto nella console Actions.

Per aggiungere l'URL dell'app web e l'ID progetto:

Apri il file start/sdk/custom/global/actions.intent.MAIN.yaml nell'editor di testo.
Nel campo URL, sostituisci la stringa segnaposto con l'URL della tua app web.
Apri il file start/sdk/settings/settings.yaml nell'editor di testo.
Nel campo projectId, sostituisci la stringa segnaposto con il tuo ID progetto.

Trasferisci il progetto alla console Actions

Per aggiornare la console di Actions con il tuo progetto locale, devi eseguire il push del progetto Actions nella console di Actions. Per farlo, segui questi passaggi:

Passa alla directory sdk:

cd sdk/

Per copiare la configurazione del file system locale nella console Azioni, esegui il comando seguente:

gactions push

Esegui il deployment del webhook

Quando hai eseguito gactions push, hai importato il codice webhook iniziale nella console Actions. Per il resto di questo codelab, puoi modificare il codice del webhook nella console Azioni. A questo punto, puoi eseguire il deployment del webhook dalla console Azioni.

Per eseguire il deployment del webhook:

Nella console di Actions, fai clic su Sviluppa nella barra di navigazione.
Fai clic sulla scheda Webhook nella barra di navigazione.
Fai clic su Esegui il deployment dell'evasione.

Potrebbero essere necessari alcuni minuti prima che Cloud Functions esegua il provisioning e il deployment del fulfillment. Dovresti visualizzare il messaggio Deployment di Cloud Functions in corso…. Quando il codice viene eseguito il deployment correttamente, il messaggio viene aggiornato a Il deployment di Cloud Functions è aggiornato.

Testare nel simulatore

A questo punto, l'azione è collegata all'app web. Puoi utilizzare il simulatore della console Azioni per assicurarti che l'app web venga visualizzata quando richiami l'azione.

Per testare l'azione, segui questi passaggi:

Nella barra di navigazione della console Azioni, fai clic su Test.
Digita Talk to Snow Pal sample nel campo Input e premi Enter.
Digita Yes nel campo Input e premi Enter. In alternativa, fai clic su Inizia partita.

Non hai ancora configurato la logica per indovinare una lettera o la parola, quindi se indovini una parola o una lettera, ricevi la risposta "…Errato. Continua a provare. Sembra che dobbiamo aggiungere altre funzionalità per far funzionare correttamente questa opzione."

5. Comprendere l'infrastruttura di Interactive Canvas

Per questo progetto, la funzionalità è organizzata in tre componenti principali: l'azione conversazionale, l'app web e il webhook. Tieni presente che questo è un modello di configurazione dell'azione e che è organizzato in questo modo per evidenziare la funzionalità principale di Interactive Canvas.

Le sezioni seguenti descrivono in dettaglio il funzionamento combinato dell'azione conversazionale, del webhook e dell'app web, nonché altri importanti elementi di Interactive Canvas.

Azione conversazionale

Il componente Azione conversazionale dell'azione gestisce il riconoscimento, l'elaborazione e l'invio dell'input dell'utente alla scena appropriata, in cui viene creata una risposta per l'utente. Ad esempio, se un utente dice "Credo che la lettera sia la E" nel gioco Snow Pal, l'azione conversazionale estrae la lettera come parametro di intent e la trasmette alla logica di gioco appropriata, che determina se la risposta è corretta e aggiorna l'app web di conseguenza. Puoi visualizzare e modificare questa logica conversazionale in Actions Builder, un IDE basato sul web nella console Actions. Lo screenshot seguente mostra una parte dell'azione conversazionale in Actions Builder:

Immagine 4. Una visualizzazione di Main invocation in Actions Builder.

Questo screenshot mostra l'Main invocation per l'azione, che gli utenti utilizzano quando dicono una frase come "Hey Google, parla con l'esempio di Snow Pal". Quando l'utente richiama l'azione, Main invocation invia un prompt con una risposta canvas, che contiene l'URL della tua app web.

La prima risposta canvas nell'azione deve includere l'URL dell'app web. Questa risposta indica all'assistente di eseguire il rendering dell'app web all'indirizzo specificato sul dispositivo dell'utente. Le risposte canvas aggiuntive in Actions Builder possono includere un campo, send_state_data_to_canvas_app, impostato su true. Questo campo invia il nome dell'intent e tutti i valori dei parametri all'app web quando l'intent viene abbinato e l'app web si aggiorna in base a questi dati inseriti dall'utente.

Webhook

Per questo codelab, il webhook contiene la logica del gioco (puoi considerarlo come un server di gioco). La logica del gioco include elementi come determinare se la risposta di un utente è corretta o errata o se l'utente ha vinto o perso e costruire una risposta in base al risultato. Puoi modificare il webhook in Actions Builder.

Quando l'azione deve eseguire la logica di gioco, Actions Builder chiama il webhook. Ad esempio, l'intent guess nella scena Game effettua una chiamata webhook al gestore guess, che esegue quindi la logica per determinare se la risposta dell'utente è corretta o meno. Il webhook può includere Canvas risposte all'interno dei gestori che mappano i file dell'app web e aggiornano il web in modo appropriato.

App web

Figura 5. Una rappresentazione visiva dell'interazione tra l'azione conversazionale, il webhook e l'app web in un'azione Interactive Canvas.

I file dell'app web contengono il codice per gli elementi visivi e le animazioni dell'app web, nonché la logica per aggiornare l'app web in base all'input di un utente. Modifichi i file dell'app web nell'editor di testo ed esegui il deployment di queste modifiche utilizzando la CLI Firebase.

Comunicazione tra l'azione conversazionale e l'app web

Devi attivare la comunicazione tra l'azione conversazionale e l'app web in modo che l'app web possa aggiornarsi in base all'input dell'utente. Ad esempio, se un utente dice "Credo che la lettera sia la F",

l'azione conversazionale deve fornire all'app web la lettera f in modo che l'app web possa aggiornarsi di conseguenza. Per trasferire l'input dell'utente dall'azione conversazionale all'app web, devi caricare l'API Interactive Canvas.

Lo script per questa API è incluso in /public/index.html, che è il file HTML principale del gioco Snow Pal. Questo file definisce l'aspetto e il caricamento della tua UI in diversi script:

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

Per aggiornare l'app web in base all'input dell'utente, devi anche registrare e configurare i callback nel file dell'app web. I callback consentono alla tua app web di rispondere a informazioni o richieste dell'azione conversazionale.

In /public/js/action.js, esiste una classe preconfigurata chiamata Action per dichiarare e registrare i callback. La classe Action è un wrapper intorno all'API Interactive Canvas. Quando l'app web viene creata con la funzione create() in scene.js, viene creata una nuova istanza Action e viene chiamato setCallbacks(), come mostrato nel seguente snippet:

scene.js

// Set Assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register Assistant Action callbacks.
this.assistant.setCallbacks();

La funzione setCallbacks() è definita nella classe Action di /public/js/action.js. Questa funzione dichiara i callback e li registra con l'API Interactive Canvas al momento della creazione del gioco:

  setCallbacks() {
    // Declare the Interactive Canvas Action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

La funzione setCallbacks() dichiara il callback onUpdate(), che viene chiamato ogni volta che invii una risposta Canvas.

La sezione successiva descrive come è configurato il codice specifico per questo progetto per trasferire i dati dall'Azione conversazionale all'app web.

Aggiornamento dell'app web in base all'input dell'utente

In questo codelab, utilizzi una mappa dei comandi per aggiornare l'app web in base all'input di un utente. Ad esempio, quando l'intent start_game viene abbinato nella scena Welcome, la risposta canvas inclusa nel prompt viene inviata all'app web. onUpdate() analizza i metadati della risposta canvas e chiama il comando START_GAME, che a sua volta chiama la funzione start() in scene.js e aggiorna l'app web per iniziare una nuova sessione di gioco.

La funzione start() in scene.js chiama anche una funzione, updateCanvasState(), che utilizza un metodo chiamato setCanvasState() per aggiungere dati di stato a cui il webhook può accedere.

Il metodo updateCanvasState() viene chiamato alla fine di ogni comando (li aggiungerai durante il codelab) e aggiorna lo stato dell'app web. Ogni volta che viene chiamato updateCanvasState(), i valori di displayedWord e incorrectGuesses vengono aggiornati in base allo stato attuale:

scene.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

Lo stato aggiornato è quindi disponibile per il turno di conversazione successivo. Puoi accedere a questo stato nel webhook tramite conv.context.canvas.state, come mostrato nello snippet di codice seguente:

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

6. Aggiungere la funzionalità di indovino

In questa sezione, aggiungi la funzionalità guess all'Azione, che consente all'utente di indovinare le lettere all'interno della parola o la parola stessa.

Azione conversazionale

Nella sezione Test nel simulatore, hai ricevuto una risposta che includeva la frase "Sembra che dobbiamo aggiungere altre funzionalità per far funzionare correttamente questa azione". Ora puoi eliminare la richiesta nella console Azioni in modo da chiamare solo il webhook (nella scena Game, l'intent guess è già configurato per effettuare una chiamata webhook quando viene abbinato).

Per rimuovere il prompt statico quando viene rilevato l'intent guess:

Nella console Azioni, fai clic su Scenari nella barra di navigazione.
Fai clic su Partita per andare alla scena Game.
Fai clic su Quando la stima corrisponde in Gestione dell'intent dell'utente. Deseleziona Invia prompt per rimuovere il prompt.
Fai clic su Salva.

Webhook

In questa sezione, aggiorna il webhook con la logica che mappa la risposta corretta o errata di un utente alla logica in un file dell'app web, che poi aggiorna l'app web di conseguenza. L'handler di intent guess è già configurato per te nel webhook, quindi devi solo aggiungere risposte Canvas a questo intent per attivare la logica che aggiorna l'app web.

Per aggiornare il webhook:

Nella console Azioni, fai clic su Webhook nella barra di navigazione.
Aggiungi il seguente codice a index.js sotto il gestore guess:

index.js (sezione A):

// Add Section A `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (sezione B):

// Add Section B `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));

Fai clic su Salva adempimento.
Fai clic su Esegui il deployment dell'evasione. Al termine del deployment, viene visualizzato il messaggio Il deployment di Cloud Functions è aggiornato.

App web

Ora puoi configurare la tua app web per gestire i comandi CORRECT_ANSWER e INCORRECT_ANSWER.

Apri public/js/action.js nell'editor di testo.
Aggiorna l'app web per gestire i comandi CORRECT_ANSWER e INCORRECT_ANSWER:

action.js (sezione C):

// Add Section C `CORRECT_ANSWER: (params) => {` content here.
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },

Esegui questo comando per aggiornare l'app web:

firebase deploy --project {PROJECT_ID} --only hosting

Testare l'azione nel simulatore

A questo punto, l'azione può riconoscere se un tentativo è corretto o errato e aggiornare l'app web di conseguenza.

Per testare l'azione, segui questi passaggi:

Nella barra di navigazione, fai clic su Test.
Digita Talk to Snow Pal sample nel campo Input e premi Enter.
Digita Yes nel campo Input e premi Enter. In alternativa, fai clic sul pulsante Sì.
Digita la lettera che vuoi indovinare nel campo Input e premi Enter.

comprendi il codice

Nella sezione precedente, hai aggiunto il codice che consente agli utenti di indovinare le lettere nel gioco e di vedere i risultati delle loro ipotesi nella parola o nel pupazzo di neve. A livello generale, effettui una chiamata webhook in Actions Builder quando viene corrisposta l'intent guess, che passa i dati alla tua app web per aggiornarla di conseguenza. Ad esempio, se l'utente indovina una lettera nel gioco Amico di neve che esiste nella parola, l'app web viene aggiornata per mostrare la lettera nella posizione corretta della parola.

Per le azioni che utilizzano Interactive Canvas, il flusso generale di trasferimento dei dati dal webhook all'app web è il seguente:

L'input dell'utente corrisponde a un intent che include una risposta Canvas.
L'azione conversazionale o il webhook invia la risposta Canvas, che attiva il callback onUpdate().
Il callback onUpdate() corrisponde a una logica personalizzata che aggiorna l'app web di conseguenza.

Per questo progetto specifico, il codice funziona nel seguente modo:

Quando l'utente corrisponde all'intent guess, Actions Builder estrae la lettera dall'input dell'utente come parametro.
Actions Builder chiama il gestore guess nel webhook, che contiene la logica per determinare se la lettera indovinata dall'utente è presente nella parola.
Il gestore guess contiene due risposte Canvas: una che viene eseguita quando la lettera è corretta e una che viene eseguita quando la lettera è errata. Ogni risposta Canvas trasmette i dati appropriati (il comando CORRECT_ANSWER o INCORRECT_ANSWER) all'app web.
I dati contenuti nel campo data della risposta Canvas vengono passati al metodo onUpdate() in action.js. onUpdate() chiama il comando appropriato nella mappa dei comandi in scene.js.
La mappa dei comandi corrisponde alle funzioni correctAnswer() e incorrectAnswer() in scene.js. Queste funzioni aggiornano l'app web in modo appropriato per riflettere la risposta dell'utente e chiamano setCanvasState() per inviare i dati di stato dall'app web al webhook.

7. Aggiungere la funzionalità di vittorie/sconfitte

In questa sezione, aggiungi la funzionalità di vittoria e sconfitta all'azione, che include la logica che determina se l'utente ha vinto o perso e la logica per aggiornare l'immagine dell'app web in base al risultato dell'utente.

Azione conversazionale

La funzionalità che gestisce la vittoria o la sconfitta dell'utente nella partita verrà configurata nell'intent guess, quindi non devi eseguire alcuna configurazione aggiuntiva in Actions Builder.

Webhook

In questa sezione, aggiorni il webhook con la logica che gestisce la vittoria o la sconfitta di un utente e la mappa alla logica dell'app web che aggiorna il gioco con la schermata appropriata di vittoria o sconfitta.

Per aggiornare il webhook:

Nella console Azioni, fai clic su Webhook nella barra di navigazione.
Aggiungi il seguente codice a index.js sotto il gestore guess:

index.js (sezione D):

// Add Section D `if (userHasWon)` content here.
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!  
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (sezione E):

// Add Section E `}` here.
}

index.js (sezione F):

// Add Section F `Check if the user has exceeded the maximum` content here.
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (sezione G):

// Add Section G `}` here.
}

Fai clic su Salva adempimento.
Fai clic su Esegui il deployment dell'evasione. Al termine del deployment, viene visualizzato il messaggio Il deployment di Cloud Functions è aggiornato.

Qui hai aggiunto due risposte Canvas con i comandi WIN_GAME e LOSE_GAME per gestire le situazioni in cui gli utenti vincono o perdono la partita. Nella sezione successiva, aggiungi una funzionalità che aggiorna l'app web in base alla vittoria o alla sconfitta dell'utente.

App web

Ora puoi configurare la tua app web in modo che si aggiorni in base alla vittoria o alla sconfitta dell'utente. Per aggiornare la tua web app:

Apri public/js/action.js nell'editor di testo.
Aggiorna la tua app web per gestire i comandi WIN_GAME e LOSE_GAME:

action.js (sezione H):

// Add Section H `WIN_GAME: (params) => {` content here.
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },

Esegui questo comando per aggiornare l'app web:

firebase deploy --project {PROJECT_ID} --only hosting

Testare l'azione nel simulatore

A questo punto, l'Azione può gestire la vittoria o la sconfitta dell'utente e presenta la schermata appropriata per ogni risultato.

Per testare l'azione, segui questi passaggi:

Nella barra di navigazione della console Azioni, fai clic su Test.
Digita Talk to Snow Pal sample nel campo Input e premi Enter.
Digita Yes nel campo Input e premi Enter. In alternativa, fai clic sul pulsante Inizia partita.
Indovina lettere e parole finché non vinci o perdi.

Se chiedi di giocare di nuovo, ricevi un messaggio che indica che la funzionalità necessaria per giocare di nuovo non è ancora stata aggiunta. Aggiungerai questa funzionalità nella prossima sezione.

comprendi il codice

La funzionalità di vittoria e sconfitta funziona allo stesso modo della funzionalità di indovinello: l'utente corrisponde all'intent guess e il webhook valuta il tentativo dell'utente. Se la risposta è corretta, il codice controlla se l'utente ha vinto. In caso affermativo, il comando WIN_GAME viene inviato all'app web. Se la risposta è sbagliata, il codice controlla se l'utente ha perso. In caso affermativo, il comando LOSE_GAME viene inviato all'app web. Questi comandi attivano le funzioni winGame() e loseGame() in scene.js, che aggiornano l'app web per visualizzare la schermata di vittoria o sconfitta e aggiornare lo stato del gioco.

8. Aggiungere la funzionalità di riproduzione

In questa sezione, aggiungi una funzionalità che consente all'utente di dire "Gioca di nuovo" o di fare clic sul pulsante Gioca di nuovo nell'app web per iniziare una nuova partita. Modifica l'intent play_again in Actions Builder per inviare una risposta canvas che aggiorni l'app web in modo appropriato e aggiungi una logica che attivi l'intent play_again quando l'utente fa clic sul pulsante Gioca di nuovo.

Azione conversazionale

Quando hai testato l'azione nella sezione precedente, se hai provato a giocare di nuovo, hai ricevuto il seguente messaggio: "Sarebbe fantastico, ma creeremo questa funzionalità in una sezione successiva. Per ora, reimposta l'azione." Ora puoi eliminare questo prompt e sostituirlo con uno che risponde all'utente quando richiede un altro gioco ("Ok, ecco un altro gioco!") e include una risposta canvas per attivare l'avvio di una nuova partita nell'app web.

Per aggiornare il prompt quando l'utente vuole giocare di nuovo, segui questi passaggi:

Nella console di Actions, fai clic sul menu a discesa Scena.
Fai clic sulla scena Partita.
Fai clic su Quando viene rilevato play_again in Gestione dell'intent dell'utente.
Sostituisci il prompt con il seguente:

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here''s another game!' 
    canvas:
      sendStateDataToCanvasApp: true

Fai clic su Salva.

Webhook

In questo codelab, il webhook gestisce la logica di gioco. Poiché la funzionalità di riproduzione non richiede alcun tipo di convalida della logica, non è necessario chiamare il webhook. Puoi invece inviare una risposta canvas direttamente da Actions Builder per trasferire i dati necessari all'app web (che hai configurato nella sezione precedente).

App web

Ora puoi modificare i file dell'app web in modo che vengano aggiornati correttamente quando l'utente chiede di giocare di nuovo. Per aggiungere questa funzionalità, segui questi passaggi:

Apri public/js/action.js nell'editor di testo.
Aggiorna l'app web per gestire il comando PLAY_AGAIN:

action.js (Sezione I):

// Add Section I `PLAY_AGAIN: (params) => {` content here.
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },

Apri public/js/scene.js nell'editor di testo.
Aggiorna l'app web per avviare una nuova sessione di gioco quando l'utente fa clic sul pulsante "Gioca di nuovo":

scene.js (sezione J):

// Add Section J `sendTextQuery` content here.
     window.interactiveCanvas.sendTextQuery('Play again');

Esegui questo comando per aggiornare l'app web:

firebase deploy --project {PROJECT_ID} --only hosting

Testare l'azione nel simulatore

Ora l'azione può avviare una nuova sessione di gioco quando l'utente dice "Gioca di nuovo" o fa clic sul pulsante Gioca di nuovo.

Per testare l'azione, segui questi passaggi:

Nella barra di navigazione, fai clic su Test.
Digita Talk to Snow Pal sample nel campo Input e premi Enter.
Digita Yes nel campo Input e premi Enter. In alternativa, fai clic sul pulsante Inizia partita.
Indovina lettere e parole finché non vinci o perdi.
Digita Play again nel campo Input e premi Enter. In alternativa, fai clic sul pulsante Gioca di nuovo.

comprendi il codice

Quando hai testato l'azione, potevi iniziare una nuova partita tramite l'input vocale ("Gioca di nuovo") o l'input tattile (fai clic sul pulsante Gioca di nuovo).

Per l'opzione di input vocale, quando l'utente dice "Gioca di nuovo" o una variazione, viene abbinato l'intent play_again e viene aggiunta una richiesta ("Ok, ecco un altro gioco!") alla coda delle richieste. La risposta canvas inclusa nel prompt invia il nome dell'intent e altri metadati all'app web. Il nome dell'intent viene passato al callback onUpdate(), che mappa il comando corrispondente, PLAY_AGAIN, alla mappa dei comandi in action.js. Il comando PLAY_AGAIN attiva la funzione start() in scene.js e aggiorna l'app web con una nuova sessione di gioco.

Per l'opzione di input tocco, utilizzi sendTextQuery(), un'API Interactive Canvas che ti consente di attivare un intent tramite l'input tocco, per far funzionare il pulsante.

In questo codelab, utilizzi sendTextQuery() per richiamare l'intent play_again quando un utente fa clic sul pulsante Gioca di nuovo. L'argomento Play again corrisponde a una frase di addestramento nell'intent play_again e attiva questo intent nello stesso modo in cui lo fa un utente che dice "Riproduci di nuovo". L'intent play_again attiva quindi la logica che aggiorna l'app web e avvia una nuova sessione di gioco.

9. Aggiornare l'intent integrato PLAY_GAME

In questa sezione, aggiornerai l'PLAY_GAME intent integrato.

L'intent integrato PLAY_GAME consente agli utenti di richiamare l'azione quando fanno una richiesta generica, ad esempio "Voglio fare un gioco".

Il codice sorgente contiene l'intent integrato PLAY_GAME, che si trova in /sdk/custom/global/actions.intent.PLAY_GAME.yaml. Ciò si riflette nella console nella sezione Invocatione come PLAY_GAME, come mostrato nello screenshot seguente:

Per consentire agli utenti di richiamare l'azione tramite questo intent integrato, devi aggiungere una risposta canvas con l'URL dell'app web all'intent integrato PLAY_GAME. Per farlo, segui questi passaggi:

Nella console Actions, fai clic su PLAY_GAME nella barra di navigazione.
Aggiorna il prompt in modo da includere l'URL della tua app web, come mostrato nello snippet seguente:

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

Fai clic su Salva.

Testare l'azione nel simulatore

La tua azione ora supporta l'intent integrato PLAY_GAME.

Per testare l'azione, segui questi passaggi:

Nella barra di navigazione, fai clic su Test.
Fai clic su Testa la gestione degli intent integrata.
Fai clic su Invoca azione.

L'azione deve essere richiamata nel simulatore.

10. Appendice: risoluzione dei problemi relativi all'azione Interactive Canvas

In questa sezione, imparerai a eseguire il debug dell'Azione Interactive Canvas quando non funziona correttamente. Il progetto Snow Pal viene fornito precompilato con una sovrapposizione di debug che puoi attivare. La sovrapposizione mostra tutti gli output console.log() e console.error() in basso a destra del display, come mostrato nello screenshot seguente:

Per attivare questa sovrapposizione, apri il file /public/css/main.css e commenta la riga display: none !important;, come mostrato nello snippet seguente:

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

Pulire il progetto [consigliato]

Per evitare possibili addebiti, ti consigliamo di rimuovere i progetti che non intendi utilizzare. Per eliminare i progetti che hai creato in questo codelab:

Per eliminare il progetto Google Cloud e le risorse, completa i passaggi elencati nella sezione Chiusura (eliminazione) dei progetti.

(Facoltativo) Per rimuovere immediatamente il progetto dalla console di Actions, completa i passaggi elencati nella sezione Eliminare un progetto. Se non completi questo passaggio, il tuo progetto verrà rimosso automaticamente dopo circa 30 giorni.

11. Complimenti!

Hai completato il codelab introduttivo su Interactive Canvas e ora hai le competenze necessarie per creare la tua Azione Interactive Canvas.

Cosa hai imparato

Come creare, eseguire il deployment e testare un'azione Interactive Canvas
Come utilizzare le risposte di Canvas per aggiornare l'app web
Come utilizzare diversi metodi per migliorare l'azione, ad esempio sendTextQuery() e setCanvasState()
Come eseguire il debug dell'azione

Scopri di più

Consulta le seguenti risorse per scoprire di più su Interactive Canvas:

Documentazione di Interactive Canvas: la documentazione ufficiale di Actions on Google per Interactive Canvas.
Esempio di Interactive Canvas: il codice di un semplice gioco Interactive Canvas che ti consente di far ruotare un triangolo e modificarne i colori.
Portale dei giochi: le linee guida per la creazione di giochi sull'Assistente Google.

Sondaggio di opinione

Prima di andare, compila un breve sondaggio sulla tua esperienza.