Zum Weiterleiten von Informationen an Ihre Webanwendung müssen Sie eine Canvas
-Antwort aus Ihrer Konversationslogik senden. Eine Canvas
-Antwort kann Folgendes tun:
- Web-App im Vollbildmodus auf dem Gerät des Nutzers rendern
- Daten übergeben, um die Web-App zu aktualisieren
In den folgenden Abschnitten wird beschrieben, wie für jedes Szenario eine Canvas-Antwort zurückgegeben wird.
Interaktiver Canvas aktivieren
Sie müssen Ihre Aktion auf eine bestimmte Weise konfigurieren, um den interaktiven Canvas verwenden zu können.
Zum Erstellen einer Aktion, die den interaktiven Canvas verwendet, ist eine zusätzliche Konfiguration in der Actions Console erforderlich. Für das Actions SDK sind außerdem Änderungen an der Datei settings.yaml
erforderlich. Das vollständige Verfahren zum Erstellen und Konfigurieren einer interaktiven Canvas-Aktion mit dem Actions SDK finden Sie unter Projekt erstellen.
Wenn Sie Actions Builder verwenden, führen Sie diese zusätzlichen Schritte aus, um den interaktiven Canvas zu aktivieren:
- Wenn Sie auf dem Bildschirm Welche Art von Aktion möchten Sie erstellen? nicht die Karte Spiel ausgewählt haben, klicken Sie im oberen Navigationsbereich auf Bereitstellen. Wählen Sie unter Weitere Informationen die Kategorie Spiele und Spaß aus. Klicken Sie auf Speichern.
- Klicken Sie in der oberen Navigationsleiste der Actions Console auf Develop.
- Klicken Sie im linken Navigationsbereich auf Interaktiver Canvas.
- Wählen Sie unter Soll Ihre Aktion den interaktiven Canvas verwenden? eine der folgenden Optionen aus:
- Aktivieren Sie den interaktiven Canvas mit Server-Webhook-Auftragsausführung. Bei dieser Option muss der Webhook auf bestimmte Funktionen zugreifen. Außerdem wird häufig
onUpdate()
verwendet, um Daten an die Webanwendung zu übergeben. Wenn diese Option aktiviert ist, werden Intent-Übereinstimmungen in Szenen verarbeitet. Sie können den Webhook aufrufen, bevor Sie zu einer anderen Szene wechseln oder die Unterhaltung beenden. - Aktivieren Sie den interaktiven Canvas mit Client-Auftragsausführung. Mit dieser Option können Sie die Webhook-Auftragsausführungslogik in die Webanwendung verschieben und Webhook-Aufrufe auf die dialogorientierten Features beschränken, die sie benötigen, z. B. die Kontoverknüpfung. Wenn diese Option aktiviert ist, können Sie
expect()
verwenden, um Intent-Handler auf Clientseite zu registrieren.
- Aktivieren Sie den interaktiven Canvas mit Server-Webhook-Auftragsausführung. Bei dieser Option muss der Webhook auf bestimmte Funktionen zugreifen. Außerdem wird häufig
- Optional: Geben Sie die Web-App-URL in das Feld Standard-Web-App-URL festlegen ein. Durch diese Aktion wird dem Hauptaufruf eine Standardantwort
Canvas
mit dem URL-Feld hinzugefügt. - Klicken Sie auf Speichern.
Wenn Sie das Actions SDK verwenden, führen Sie diese zusätzlichen Schritte aus, um Interactive Canvas zu aktivieren:
- Setze das Feld
category
in deinersettings.yaml
-Datei aufGAMES_AND_TRIVIA
, um deine Aktion bestmöglich zu beschreiben und Nutzern zu helfen, sie zu finden. - Setzen Sie das Feld
usesInteractiveCanvas
in Ihrersettings.yaml
-Datei auftrue
.
Oberflächenfähigkeit prüfen
Das Interactive Canvas-Framework wird nur auf Assistant-Geräten ausgeführt, die eine visuelle Oberfläche bieten. Daher muss deine Aktion die INTERACTIVE_CANVAS
-Funktion auf dem Gerät des Nutzers prüfen. Wenn Sie Aufforderungen in Actions Builder definieren, können Sie im Feld selector
des candidates
-Objekts eine Liste von Gerätefunktionen angeben. Mit der Aufforderungsauswahl wird die Vorschlagsauswahl ausgewählt, die für die Gerätefunktion des Nutzers am besten geeignet ist.
Die Logik deiner Aktion sollte Folgendes tun, um eine Canvas
-Antwort zurückzugeben:
- Prüfe, ob das Gerät des Nutzers die Funktion
INTERACTIVE_CANVAS
unterstützt. Ist dies der Fall, senden Sie dem Nutzer eineCanvas
-Antwort. - Wenn die Funktion „Interactive Canvas“ nicht verfügbar ist, prüfen Sie, ob das Gerät des Nutzers die Funktion
RICH_RESPONSE
unterstützt. Ist dies der Fall, senden Sie dem Nutzer stattdessen eine Rich-Media-Antwort. - Wenn die Funktion für umfassende Antworten nicht verfügbar ist, senden Sie dem Nutzer eine einfache Antwort.
Die folgenden Snippets geben die entsprechende Antwort basierend auf den Funktionen des Geräts des Nutzers zurück:
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.'); }
Web-App rendern
Eine Aktion, die den interaktiven Canvas verwendet, umfasst eine Webanwendung mit benutzerdefinierten visuellen Elementen, die Sie als Antwort an Nutzer senden. Nachdem die Webanwendung gerendert wurde, interagieren Nutzer weiterhin per Sprache, Text oder Berührung mit ihr, bis die Unterhaltung beendet ist.
Deine erste Canvas
-Antwort muss die URL der Webanwendung enthalten. Dieser Antworttyp Canvas
weist Google Assistant an, die Webanwendung unter dieser Adresse auf dem Gerät des Nutzers zu rendern. In der Regel senden Sie die erste Canvas
-Antwort sofort, nachdem der Nutzer Ihre Aktion aufgerufen hat. Wenn die Webanwendung geladen wird, wird auch die interaktive Canvas-Bibliothek geladen und die Webanwendung registriert einen Callback-Handler bei der Interactive Canvas API.
Sie können die URL Ihrer Webanwendung in Actions Builder angeben, wie im folgenden Screenshot gezeigt:
Wenn Sie nach Angabe der Web-App-URL eine Eingabeaufforderung erstellen, die eine Canvas
-Antwort enthält, füllt Actions Builder das URL-Feld der Canvas
-Antwort automatisch aus. Weitere Informationen zum Festlegen der Webanwendungs-URL in der Console finden Sie im Abschnitt Interaktiven Canvas aktivieren.
Die folgenden Snippets zeigen, wie Canvas
-Antworten erstellt werden, die die Webanwendung sowohl in Actions Builder als auch in Ihrem Webhook rendern:
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" } } }
Daten übergeben, um die Web-App zu aktualisieren
Nachdem Sie die erste Canvas
-Antwort gesendet haben, können Sie zusätzliche Canvas
-Antworten verwenden, um Aktualisierungen für data
bereitzustellen. Die benutzerdefinierte Logik Ihrer Webanwendung verwendet dann Änderungen an Ihrer Webanwendung. Wenn Sie eine Canvas
-Antwort senden, mit der Daten an die Webanwendung gesendet werden, werden folgende Schritte ausgeführt:
- Wenn der Intent innerhalb einer Szene zugeordnet wird, löst er ein Ereignis aus. Eine
Canvas
-Antwort, die eindata
-Feld mit einer JSON-Nutzlast enthält, wird dann als Antwort zurückgesendet. - Das Feld
data
wird an einenonUpdate
-Callback übergeben und zum Aktualisieren der Webanwendung verwendet. Die Konversationsaktion kann eine neue
Canvas
-Antwort senden und Informationen im Felddata
angeben, um neue Aktualisierungen zu senden oder neue Status zu laden.
Sie können Daten auf zwei Arten an Ihre Webanwendung übergeben:
- Mit Actions Builder. Actions Builder füllt das Feld
data
in derCanvas
-Antwort automatisch mit den erforderlichen Metadaten zum Aktualisieren der Webanwendung. - Mit einem Webhook: Wenn Sie einen Webhook haben, können Sie eine benutzerdefinierte Datennutzlast konfigurieren, um die Webanwendung in Ihrer
Canvas
-Antwort zu aktualisieren.
In den folgenden Abschnitten wird beschrieben, wie Sie Daten über Actions Builder und über einen Webhook übergeben.
Actions Builder zum Übergeben von Daten verwenden
Mit Actions Builder müssen Sie keinen Webhook definieren, um die Metadaten zu verwalten, die an Ihre Webanwendung gesendet werden. Stattdessen können Sie beim Konfigurieren Ihres Intent-Handlers in der Actions Builder-UI eine Canvas
-Antwort einfügen. Das Feld data
wird automatisch mit den erforderlichen Metadaten gefüllt, um Ihre Webanwendung zu aktualisieren, z. B. den Intent-Namen, alle aus der Nutzereingabe erfassten Parameter und die aktuelle Szene.
Der folgende Intent-Handler Guess
gibt beispielsweise an, dass Sie eine Canvas
-Antwort einbinden möchten:
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
Optional können Sie das folgende Snippet an den Intent-Handler anhängen, um eine TTS-Nachricht zu senden:
...
- first_simple:
variants:
- speech: Optional message.
Actions Builder erweitert die Canvas
-Antwort automatisch um Metadaten, um die Webanwendung zu aktualisieren, wie in den folgenden Snippets gezeigt. In diesem Fall hat der Nutzer den Buchstaben „a“ in einem Wortratenspiel erraten:
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 } } ] }
Diese Antwort aktualisiert Ihre Webanwendung mit der Antwort des Nutzers und wechselt zur entsprechenden Szene.
Daten mithilfe des Webhooks übergeben
Sie können das Feld data
der Canvas
-Antworten in Ihrem Webhook manuell mit den erforderlichen Statusinformationen konfigurieren, um Ihre Webanwendung zu aktualisieren. Dieser Ansatz wird empfohlen, wenn Sie eine benutzerdefinierte data
-Nutzlast in eine Canvas
-Antwort einfügen müssen, anstatt nur die typischen Metadaten weiterzugeben, die zum Aktualisieren der Webanwendung erforderlich sind.
Die folgenden Snippets zeigen, wie Daten in einer Canvas
-Antwort im Webhook übergeben werden:
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": "" } } }
Richtlinien und Einschränkungen
Beachten Sie beim Erstellen Ihrer Aktion die folgenden Richtlinien und Einschränkungen für Canvas
-Antworten:
- Jeder Webhook-Handler in der Auftragsausführung muss
Canvas
enthalten. Wenn die Webhook-AntwortCanvas
nicht enthält, wird Ihre Webanwendung geschlossen. - Sie müssen die URL Ihrer Webanwendung nur in der ersten
Canvas
-Antwort angeben, die Sie an den Nutzer senden. - Die
Canvas
-Antwort-URL muss gültig und das Protokoll „https“ sein. - Die
Canvas
-Antwort darf maximal 50 KB groß sein.