Prompt di Canvas

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:

  1. 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.
  2. Fai clic su Sviluppa nella barra di navigazione in alto della console di Actions.
  3. Fai clic su Interactive Canvas nel menu di navigazione a sinistra.
  4. 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.
  5. 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.
  6. Fai clic su Salva.

Quando utilizzi l'SDK Actions, segui questi passaggi aggiuntivi per abilitare Interactive Canvas:

  1. Imposta il campo category nel file settings.yaml su GAMES_AND_TRIVIA per descrivere al meglio l'Azione e aiutare gli utenti a scoprire l'Azione.
  2. Imposta il campo usesInteractiveCanvas nel file settings.yaml su true.

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:

  1. Verifica che il dispositivo dell'utente supporti la funzionalità INTERACTIVE_CANVAS. In caso affermativo, invia all'utente una risposta Canvas.
  2. 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.
  3. 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:

  1. Quando l'intent corrisponde a una scena, attiva un evento e una risposta Canvas contenente un campo data con un payload JSON viene inviata come risposta.
  2. Il campo data viene passato a un callback onUpdate e utilizzato per aggiornare l'app web.

  3. L'azione conversazionale può inviare una nuova risposta Canvas e fornire informazioni nel campo data 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 risposta Canvas 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 include Canvas, 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.