Per inoltrare informazioni alla tua app web, devi inviare una risposta Canvas
dalla logica di conversazione. Una risposta Canvas
può eseguire una delle seguenti operazioni:
- Esegui il rendering dell'app web a schermo intero sul dispositivo dell'utente
- Trasmettere dati per aggiornare l'app web
Le seguenti sezioni descrivono come restituire una risposta di Canvas per ogni scenario.
Attiva Interactive Canvas
Per utilizzare Interactive Canvas, devi configurare l'Azione in un modo specifico.
La creazione di un'azione che utilizza Interactive Canvas richiede un'ulteriore configurazione nella console Actions (e, per l'SDK Actions, modifiche al file settings.yaml
). Per visualizzare la procedura completa per creare e configurare un'azione Canvas interattiva con l'SDK Actions, consulta Creare un progetto.
Quando utilizzi Actions Builder, segui questi passaggi aggiuntivi per attivare Interactive Canvas:
- Se non hai selezionato la scheda Gioco nella schermata Che tipo di azione vuoi creare?, fai clic su Implementa nella barra di navigazione in alto. In Ulteriori informazioni, seleziona la categoria Giochi e divertimento. Fai clic su Salva.
- Fai clic su Sviluppa nella barra di navigazione in alto della console di Actions.
- Fai clic su Interactive Canvas nel menu di navigazione a sinistra.
- In Vuoi che l'azione utilizzi Interactive Canvas?, seleziona una delle seguenti opzioni:
- Abilita Interactive Canvas con fulfillment di webhook del server. Questa opzione si basa sul webhook per accedere a determinate funzionalità e utilizza spesso
onUpdate()
per passare dati all'app web. Se questa opzione è attiva, le corrispondenze di intent vengono gestite nelle scene e puoi scegliere di chiamare il webhook prima di passare a un'altra scena o terminare la conversazione. - Abilita Interactive Canvas con fulfillment client. Questa opzione ti consente di spostare la logica di fulfillment del webhook nell'app web e di limitare le chiamate dei webhook solo alle funzionalità di conversazione che la richiedono, ad esempio il collegamento dell'account. Se questa opzione è abilitata, puoi utilizzare
expect()
per registrare i gestori di intent sul lato client.
- Abilita Interactive Canvas con fulfillment di webhook del server. Questa opzione si basa sul webhook per accedere a determinate funzionalità e utilizza spesso
- Facoltativo: inserisci l'URL dell'app web nel campo Imposta l'URL dell'app web predefinita. Questa azione aggiunge una risposta
Canvas
predefinita con il campo URL alla chiamata principale. - Fai clic su Salva.
Quando utilizzi l'SDK Actions, segui questi passaggi aggiuntivi per abilitare Interactive Canvas:
- Imposta il campo
category
nel filesettings.yaml
suGAMES_AND_TRIVIA
per descrivere al meglio l'Azione e aiutare gli utenti a scoprire l'Azione. - Imposta il campo
usesInteractiveCanvas
nel filesettings.yaml
sutrue
.
Controlla la capacità della piattaforma
Il framework Interactive Canvas viene eseguito solo sui dispositivi con l'assistente che forniscono
un'interfaccia visiva, quindi l'Azione deve verificare la
funzionalità di INTERACTIVE_CANVAS
sul dispositivo dell'utente. Quando definisci i prompt in Actions Builder, puoi specificare un elenco di funzionalità del dispositivo nel campo selector
dell'oggetto candidates
. Il selettore di prompt seleziona il candidato più
appropriato per le funzionalità del dispositivo dell'utente.
Per restituire una risposta Canvas
, la logica dell'Azione deve:
- Verifica che il dispositivo dell'utente supporti la funzionalità
INTERACTIVE_CANVAS
. In caso affermativo, invia all'utente una rispostaCanvas
. - Se la funzionalità Canvas interattiva non è disponibile, verifica se il dispositivo
dell'utente supporta la funzionalità
RICH_RESPONSE
. Se è così, invia all'utente una risposta avanzata. - Se la funzionalità di risposta avanzata non è disponibile, invia all'utente una risposta semplice.
I seguenti snippet restituiscono la risposta appropriata in base alle funzionalità del dispositivo dell'utente:
YAML
candidates: - selector: surface_capabilities: capabilities: - INTERACTIVE_CANVAS canvas: url: 'https://example.web.app' - selector: surface_capabilities: capabilities: - RICH_RESPONSE content: card: title: Card title text: Card Content image: url: 'https://example.com/image.png' alt: Alt text button: name: Link name open: url: 'https://example.com/' - first_simple: variants: - speech: Example simple response.
JSON
{ "candidates": [ { "selector": { "surface_capabilities": { "capabilities": [ "INTERACTIVE_CANVAS" ] } }, "canvas": { "url": "https://example.web.app" } }, { "selector": { "surface_capabilities": { "capabilities": [ "RICH_RESPONSE" ] } }, "content": { "card": { "title": "Card title", "text": "Card Content", "image": { "url": "https://example.com/image.png", "alt": "Alt text" }, "button": { "name": "Link name", "open": { "url": "https://example.com/" } } } } }, { "first_simple": { "variants": [ { "speech": "Example simple response." } ] } } ] }
Node.js
const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE"); const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS"); if (supportsInteractiveCanvas) { // Respond with a Canvas response conv.add(new Canvas({ url: 'https://example.web.app', })); } else if (supportsRichResponse) { // Respond with a rich response conv.add(new Card({ title: 'Card title', image: new Image({ url: 'https://example.com/image.png', alt: 'Alt text', }), button: new Link({ name: 'Link name', open: { url: 'https://example.com/', }, }), })); } else { // Respond with a simple response conv.add('Example simple response.'); }
Esegui il rendering dell'app web
Un'Azione che utilizza Interactive Canvas include un'app web con immagini personalizzate che invii agli utenti in risposta. Una volta eseguito il rendering dell'app web, gli utenti continuano a interagire con essa tramite voce, testo o tocco fino al termine della conversazione.
La tua prima risposta Canvas
deve contenere l'URL dell'app web. Questo tipo di risposta Canvas
indica all'Assistente Google di visualizzare l'app web a quell'indirizzo sul dispositivo dell'utente. In genere, devi inviare la prima risposta Canvas
subito dopo che l'utente chiama l'Azione. Quando viene caricata l'app web, viene caricata la libreria
Interactive Canvas e l'app web registra un gestore di callback
con l'API Interactive Canvas.
Puoi specificare l'URL della tua app web in Actions Builder, come mostrato nello screenshot seguente:
Se crei un prompt che include una risposta Canvas
dopo aver specificato l'URL dell'app web, Actions Builder compila automaticamente il campo URL della risposta Canvas
. Per ulteriori informazioni sull'impostazione dell'URL dell'applicazione web nella console, consulta la sezione Abilitare Interactive Canvas.
I seguenti snippet mostrano come creare risposte Canvas
che mostrino l'app web sia in Actions Builder che nel webhook:
YAML
candidates: - first_simple: variants: - speech: >- Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later. canvas: url: 'https://your-web-app.com'
JSON
{ "candidates": [ { "first_simple": { "variants": [ { "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later." } ] }, "canvas": { "url": "https://your-web-app.com" } } ] }
Node.js
app.handle('welcome', (conv) => { conv.add('Welcome! Do you want me to change color or pause spinning? ' + 'You can also tell me to ask you later.'); conv.add(new Canvas({ url: `https://your-web-app.com`, })); });
JSON
{ "session": { "id": "session_id", "params": {} }, "prompt": { "override": false, "firstSimple": { "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later.", "text": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later." }, "canvas": { "data": [], "suppressMic": false, "url": "https://your-web-app.com" } } }
Trasmettere dati per aggiornare l'app web
Dopo aver inviato la risposta Canvas
iniziale, puoi utilizzare altre risposte Canvas
per fornire aggiornamenti a data
, che la logica personalizzata dell'app web utilizza per apportare modifiche alla tua app web. Quando invii una risposta Canvas
che trasmette dati all'app web, si verificano i seguenti passaggi:
- Quando l'intent corrisponde a una scena, attiva un evento e una risposta
Canvas
contenente un campodata
con un payload JSON viene inviata come risposta. - Il campo
data
viene passato a un callbackonUpdate
e utilizzato per aggiornare l'app web. L'azione conversazionale può inviare una nuova risposta
Canvas
e fornire informazioni nel campodata
per inviare nuovi aggiornamenti o caricare nuovi stati.
Puoi trasmettere i dati alla tua applicazione web in due modi:
- Con Actions Builder. Actions Builder compila automaticamente il campo
data
nella rispostaCanvas
con i metadati necessari per aggiornare l'app web. - Con un webhook. Se hai un webhook, puoi configurare un payload di dati personalizzato per aggiornare l'app web nella risposta
Canvas
.
Le seguenti sezioni descrivono come trasferire i dati tramite Actions Builder e tramite un webhook.
Usare Actions Builder per trasmettere i dati
Con Actions Builder, non è necessario definire un webhook per gestire i metadati inviati all'app web. Al contrario, quando configuri il gestore di intent nell'interfaccia utente di Actions Builder, puoi includere una risposta Canvas
. Un campo data
viene compilato automaticamente con i metadati necessari per aggiornare l'app web, ad esempio il nome dell'intent, i parametri acquisiti dall'input dell'utente e la scena corrente.
Ad esempio, il seguente gestore di intent Guess
indica che vuoi includere una risposta Canvas
:
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
In alternativa, puoi aggiungere il seguente snippet al gestore di intent per inviare un messaggio TTS:
...
- first_simple:
variants:
- speech: Optional message.
Actions Builder estende automaticamente la risposta Canvas
con metadati per
aggiornare l'app web, come mostrato negli snippet seguenti. In questo caso, l'utente
ha intuito la lettera "a" in un gioco di indovina le parole:
YAML
candidates: - canvas: data: - google: intent: params: letter: resolved: a original: a name: guess scene: Game sendStateDataToCanvasApp: true
JSON
{ "candidates": [ { "canvas": { "data": [ { "google": { "intent": { "params": { "letter": { "resolved": "a", "original": "a" } }, "name": "guess" }, "scene": "Game" } } ], "sendStateDataToCanvasApp": true } } ] }
Questa risposta aggiorna la tua app web con la risposta dell'utente e le transizioni alla scena appropriata.
Utilizzare il webhook per trasmettere i dati
Puoi configurare manualmente il campo data
delle risposte Canvas
nel webhook con le informazioni sullo stato necessarie per aggiornare l'app web. Questo approccio è consigliato se devi includere un payload data
personalizzato in una risposta Canvas
anziché trasmettere solo i tipici metadati necessari per aggiornare l'app web.
I seguenti snippet mostrano come trasmettere dati in una risposta Canvas
nel
webhook:
Node.js
app.handle('start_spin', (conv) => { conv.add(`Ok, I'm spinning. What else?`); conv.add(new Canvas({ data: { command: 'SPIN', spin: true, }, })); });
JSON
{ "session": { "id": "session_id", "params": {} }, "prompt": { "override": false, "firstSimple": { "speech": "Ok, I'm spinning. What else?", "text": "Ok, I'm spinning. What else?" }, "canvas": { "data": { "command": "SPIN", "spin": true }, "suppressMic": false, "url": "" } } }
Linee guida e limitazioni
Quando crei l'Azione, tieni presente le seguenti linee guida e limitazioni per le risposte Canvas
:
- Ogni gestore di webhook nel fulfillment deve includere
Canvas
. Se la risposta webhook non includeCanvas
, l'app web si chiude. - Devi includere l'URL dell'app web solo nella prima risposta
Canvas
che invii all'utente. - L'URL della risposta
Canvas
deve essere valido e il protocollo deve essere https. - La risposta
Canvas
deve avere una dimensione massima di 50 kB.