Canvas-Prompts

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:

  1. 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.
  2. Klicken Sie in der oberen Navigationsleiste der Actions Console auf Develop.
  3. Klicken Sie im linken Navigationsbereich auf Interaktiver Canvas.
  4. 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.
  5. 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.
  6. Klicken Sie auf Speichern.

Wenn Sie das Actions SDK verwenden, führen Sie diese zusätzlichen Schritte aus, um Interactive Canvas zu aktivieren:

  1. Setze das Feld category in deiner settings.yaml-Datei auf GAMES_AND_TRIVIA, um deine Aktion bestmöglich zu beschreiben und Nutzern zu helfen, sie zu finden.
  2. Setzen Sie das Feld usesInteractiveCanvas in Ihrer settings.yaml-Datei auf true.

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:

  1. Prüfe, ob das Gerät des Nutzers die Funktion INTERACTIVE_CANVAS unterstützt. Ist dies der Fall, senden Sie dem Nutzer eine Canvas-Antwort.
  2. 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.
  3. 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:

  1. Wenn der Intent innerhalb einer Szene zugeordnet wird, löst er ein Ereignis aus. Eine Canvas-Antwort, die ein data-Feld mit einer JSON-Nutzlast enthält, wird dann als Antwort zurückgesendet.
  2. Das Feld data wird an einen onUpdate-Callback übergeben und zum Aktualisieren der Webanwendung verwendet.

  3. Die Konversationsaktion kann eine neue Canvas-Antwort senden und Informationen im Feld data 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 der Canvas-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-Antwort Canvas 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.