Prompt di Canvas

Per inoltrare informazioni alla tua app web, devi inviare una risposta Canvas dalla tua logica di conversazione. Una risposta Canvas può eseguire una delle seguenti operazioni:

  • Visualizza l'app web a schermo intero sul dispositivo dell'utente
  • Trasmetti i dati per aggiornare l'app web

Le sezioni seguenti descrivono come restituire una risposta di Canvas per ogni in questo scenario.

Attiva canvas interattivo

Per utilizzare il canvas interattivo, devi configurare l'azione in un modo specifico. La creazione di un'azione che utilizza Interactive Canvas richiede configurazione nella console Actions (e, per l'SDK Actions, le modifiche il tuo file settings.yaml). Per vedere la procedura completa per creare configurazione di un'azione Canvas interattiva con l'SDK Actions, consulta Crea un progetto.

Quando usi Actions Builder, segui questi passaggi aggiuntivi per attivare la modalità interattiva Tela:

  1. Se non hai selezionato la scheda Gioco nella sezione Che tipo di azione, vuoi creare la build?, fai clic su Esegui il deployment nella barra di navigazione in alto. Nella sezione Informazioni aggiuntive, seleziona la casella Giochi e divertente. Fai clic su Salva.
  2. Fai clic su Sviluppo nella barra di navigazione superiore della console di Actions.
  3. Fai clic su Canvas interattivo nel riquadro di navigazione a sinistra.
  4. In Vuoi che l'azione utilizzi Canvas interattivo?, seleziona una delle le seguenti:
      .
    • Abilita Canvas interattivo con il completamento del webhook server. Questa opzione si basa sul webhook per accedere a determinate funzionalità e utilizza spesso onUpdate() per trasmettere i dati all'app web. Se l'opzione è attivata, le corrispondenze di intent vengono gestito in scene e puoi scegliere di chiamare il webhook prima della transizione a un'altra scena o alla fine della conversazione.
    • Attiva Interactive Canvas con il completamento del cliente. Questa opzione consente di spostare la logica di fulfillment webhook nell'app web e limitare chiamate webhook solo alle funzionalità conversazionali che lo richiedono, come il collegamento degli account. Quando l'opzione è attiva, puoi usare expect() per gestori di intent di registrazione 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 a la chiamata principale.
  6. Fai clic su Salva.

Se usi l'SDK Actions, segui questi passaggi aggiuntivi per attivare la modalità interattiva Tela:

  1. Imposta il campo category del 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 del file settings.yaml su true.

Verifica la capacità della superficie

Il framework Interactive Canvas funziona solo sui dispositivi con l'assistente che forniscono un'interfaccia visiva, quindi l'Azione deve controllare il INTERACTIVE_CANVAS funzionalità sul dispositivo dell'utente. Quando definisci i prompt in Actions Builder, puoi specificare un elenco delle funzionalità del dispositivo nel campo selector della Oggetto candidates. Il selettore di prompt seleziona il candidato del prompt più adatto appropriato per le funzionalità del dispositivo dell'utente.

Per restituire una risposta Canvas, la logica dell'azione dovrebbe procedere nel seguente modo:

  1. Verifica che il dispositivo dell'utente supporti la funzionalità INTERACTIVE_CANVAS. Se invia all'utente una risposta Canvas.
  2. Se la funzionalità Canvas interattivo non è disponibile, controlla se la funzionalità dispositivo supporta la funzionalità RICH_RESPONSE. In tal caso, invia all'utente uno una risposta avanzata.
  3. Se la funzionalità di risposta avanzata non è disponibile, invia all'utente un 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.');
}

Visualizza l'app web

Un'azione che utilizza il canvas interattivo include un'app web con immagini che invii agli utenti in risposta. Dopo il rendering dell'app web, gli utenti continuerà a interagire con il dispositivo tramite comandi vocali, SMS o tocco finché conversazione terminata.

La prima risposta Canvas deve contenere l'URL dell'app web. Questo tipo di La risposta di Canvas indica all'Assistente Google di eseguire il rendering dell'app web all'indirizzo indicato sul dispositivo dell'utente. In genere, invii la prima Canvas risposta subito dopo che l'utente richiama l'azione. Quando viene caricata l'app web, Viene caricata la libreria Canvas interattiva 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 in il seguente screenshot:

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 informazioni sull'impostazione dell'URL dell'app web nella console, consulta Attiva Canvas interattivo.

I seguenti snippet mostrano come creare risposte Canvas da visualizzare nell'app web sia in Actions Builder sia 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"
    }
  }
}

Trasmetti i dati per aggiornare l'app web

Dopo aver inviato la risposta iniziale di Canvas, puoi utilizzare altri Canvas risposte per fornire aggiornamenti a data, che la logica personalizzata della tua app web utilizza per apportare modifiche alla tua app web. Quando invii una risposta Canvas che supera all'app web, si verificano i seguenti passaggi:

  1. Quando l'intent trova una corrispondenza all'interno di una scena, attiva un evento e una risposta Canvas contenente un campo data con un payload JSON viene quindi rinviato come risposta.
  2. Il campo data viene passato a un callback onUpdate e utilizzato per aggiornare il nell'app web di Google.

  3. L'azione conversazionale può inviare una nuova risposta Canvas e fornire informazioni in il campo data per inviare nuovi aggiornamenti o caricare nuovi stati.

Puoi trasmettere i dati alla tua app web in due modi:

  • Con Actions Builder. Actions Builder compila automaticamente il campo data in la risposta Canvas con i metadati necessari per aggiornare l'app web.
  • Con un webhook. Se hai un webhook, puoi configurare dati personalizzati per aggiornare l'app web nella risposta Canvas.

Le seguenti sezioni descrivono come trasferire dati tramite Actions Builder e un webhook.

Usare Actions Builder per trasmettere dati

Con Actions Builder, non è necessario definire un webhook per gestire i metadati inviato alla tua applicazione web. Quando configuri il gestore di intent in nell'interfaccia utente di Actions Builder, puoi includere una risposta Canvas. R Il campo data viene compilato automaticamente con i metadati necessari da aggiornare nell'app web, ad esempio il nome dell'intent, gli eventuali parametri acquisiti dall'input dell'utente e la scena attuale.

Ad esempio, il seguente gestore di intent Guess indica che vuoi includere un elemento Canvas risposta:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true

JSON

{
  "candidates": [
    {
      "canvas": {
        "send_state_data_to_canvas_app": true
      }
    }
  ]
}

Facoltativamente, puoi aggiungere il seguente snippet al gestore di intent per inviare un Messaggio di sintesi vocale:

...
  - first_simple:
      variants:
        - speech: Optional message.

Actions Builder estende automaticamente la risposta Canvas con metadati a aggiorna l'app web, come mostrato negli snippet che seguono. In questo caso, l'utente ha indovinato la lettera "a" in un gioco di indovinelli:

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 passa al la scena appropriata.

Utilizzare il webhook per trasmettere i dati

Puoi configurare manualmente il campo data di Canvas risposte nel tuo webhook con le informazioni sullo stato necessarie per aggiornare la tua app web. Questo approccio è consigliato se devi includere un payload data personalizzato in una risposta Canvas anziché trasmettere solo i metadati tipici necessari per aggiornare l'app web.

I seguenti snippet mostrano come trasferire i dati in una risposta Canvas nel tuo 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

Tieni presenti le seguenti linee guida e limitazioni per le risposte di Canvas quando crei l'Azione:

  • Ogni gestore webhook nel fulfillment deve includere Canvas. Se il webhook la risposta non include Canvas, la tua app web si chiude.
  • Devi includere solo l'URL dell'app web nella prima risposta (Canvas) che invii all'utente.
  • L'URL di risposta Canvas deve essere valido e il protocollo deve essere https.
  • La risposta Canvas deve avere una dimensione massima di 50 kB.