Canvas-Prompts

Wenn Sie Informationen an Ihre Web-App weiterleiten möchten, müssen Sie eine Canvas-Antwort senden aus Ihrer Konversationslogik. Eine Canvas-Antwort kann eine der folgenden Aktionen ausführen:

  • Vollbild-Web-App auf dem Gerät des Nutzers rendern
  • Daten übergeben, um die Web-App zu aktualisieren

In den folgenden Abschnitten wird beschrieben, wie Sie für jede Szenario.

Interaktiven 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 Interactive Canvas verwendet, sind zusätzliche Konfiguration in der Actions Console (und für das Actions SDK) Ihre settings.yaml-Datei). Um das vollständige Verfahren zum Erstellen und Konfigurieren einer interaktiven Canvas-Aktion mit dem Actions SDK, siehe Projekt erstellen

Wenn Sie Actions Builder verwenden, führen Sie die folgenden zusätzlichen Schritte aus, um die interaktive Funktion zu aktivieren Leinwand:

  1. Wenn du die Karte Spiel auf der Seite Welche Art von Aktion nicht ausgewählt hast, Wollen Sie erstellen? klicken Sie im oberen Navigationsbereich auf Bereitstellen. Wählen Sie unter Weitere Informationen die Option Spiele und in der Kategorie „Spaß“. Klicken Sie auf Speichern.
  2. Klicken Sie im oberen Navigationsbereich der Actions Console auf Develop.
  3. Klicken Sie im linken Navigationsbereich auf Interaktiver Canvas.
  4. Wählen Sie unter Möchten Sie, dass Ihre Aktion den interaktiven Canvas verwendet? eine der folgenden Optionen aus: Folgendes: <ph type="x-smartling-placeholder">
      </ph>
    • Interaktiven Canvas mit Server-Webhook-Ausführung aktivieren. Diese Option benötigt den Webhook, um auf bestimmte Funktionen zuzugreifen, und verwendet häufig onUpdate(), um Daten an die Web-App zu übergeben. Wenn diese Option aktiviert ist, werden Intent-Übereinstimmungen Sie können den Webhook vor der Umstellung aufrufen, in eine andere Szene verschieben oder das Gespräch beenden.
    • Aktivieren Sie Interactive Canvas mit Clientausführung. Mit dieser Option können die Logik für die Auftragsausführung von Webhooks in die Webanwendung verschieben, Webhook nur die Conversational-Features aufruft, etwa die Kontoverknüpfung. Wenn diese Option aktiviert ist, kannst du expect() für Folgendes verwenden: Registrierung von Intent-Handlern auf Clientseite.
  5. Optional: Geben Sie die URL Ihrer Web-App in das Feld Standardmäßige Web-App-URL festlegen ein. ein. Durch diese Aktion wird eine Canvas-Standardantwort mit dem URL-Feld hinzugefügt deinen Hauptaufruf.
  6. Klicken Sie auf Speichern.

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

  1. Legen Sie das Feld category in der Datei settings.yaml auf GAMES_AND_TRIVIA fest. um deine Aktion am besten zu beschreiben und Nutzern zu helfen, deine Aktion zu finden.
  2. Legen Sie das Feld usesInteractiveCanvas in der Datei settings.yaml auf true fest.

Oberflächenkapazität prüfen

Das Interactive Canvas-Framework läuft nur auf Assistant-Geräten mit eine visuelle Oberfläche, sodass deine Aktion prüfen muss, ob INTERACTIVE_CANVAS Funktion auf dem Gerät des Nutzers aktivieren. Wenn Sie Prompts in Actions Builder definieren, können Sie im Feld selector des candidates-Objekt. Mit der Prompt-Auswahl wird der Vorschlag ausgewählt, der am besten die für die Gerätefunktionen des Nutzers geeignet sind.

Um eine Canvas-Antwort zurückzugeben, sollte die Logik deiner Aktion folgende Schritte ausführen:

  1. Prüfe, ob das Gerät des Nutzers die Funktion INTERACTIVE_CANVAS unterstützt. Wenn wird dem Nutzer eine Canvas-Antwort gesendet.
  2. Wenn die Funktion „Interactive Canvas“ nicht verfügbar ist, prüfen Sie, ob die Funktion Gerät die Funktion RICH_RESPONSE unterstützt. Falls ja, senden Sie dem Nutzer eine Rich-Media-Antwort.
  3. Wenn die Rich-Response-Funktion nicht verfügbar ist, senden Sie dem Nutzer eine einfache Antwort.

Die folgenden Snippets geben basierend auf den Funktionen die entsprechende Antwort zurück. des Nutzergeräts:

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.');
}

Webanwendung rendern

Eine Aktion, die den interaktiven Canvas verwendet, enthält eine Web-App mit benutzerdefinierten visuelle Elemente, die Sie als Antwort an Nutzende senden. Sobald die Webanwendung gerendert wird, so lange per Sprach-, Text- oder Berührungseingabe mit ihr interagieren, bis das ist das Gespräch beendet.

Ihre erste Canvas-Antwort muss die URL der Webanwendung enthalten. Diese Art von Canvas-Antwort weist Google Assistant an, die Web-App unter dieser Adresse zu rendern auf dem Gerät der Nutzenden. In der Regel senden Sie die erste Canvas-Antwort direkt nachdem der Nutzer deine Aktion aufgerufen hat. Wenn die Webanwendung geladen wird, Die interaktive Canvas-Bibliothek wird geladen und die Webanwendung registriert einen Callback-Handler. mit der Interactive Canvas API.

Sie können die URL Ihrer Webanwendung in Actions Builder angeben, wie in der folgenden Screenshot:

Wenn Sie einen Prompt erstellen, der eine Canvas-Antwort enthält, nachdem Sie den Parameter Web-App-URL füllt Actions Builder das URL-Feld der Canvas-Antwort automatisch aus. Weitere Informationen Informationen zum Festlegen der Web-App-URL in der Konsole finden Sie in der Bereich Interaktiven Canvas aktivieren.

Die folgenden Snippets zeigen, wie Canvas-Antworten erstellt werden, die die Webanwendung sowohl in Actions Builder als auch im Webhook verwenden:

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 verwenden Antworten, um Updates für data bereitzustellen, die von der benutzerdefinierten Logik Ihrer Webanwendung verwendet werden um Änderungen an Ihrer Webanwendung vorzunehmen. Wenn Sie eine bestandene Canvas-Antwort senden an die Web-App senden, werden die folgenden Schritte durchgeführt:

  1. Wird der Intent in einer Szene zugeordnet, wird ein Ereignis und die Antwort Canvas ausgelöst. der 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 zur Aktualisierung des Web-App.

  3. Deine Unterhaltungsaktion kann eine neue Canvas-Antwort senden und Informationen in Das Feld data, um neue Aktualisierungen zu senden oder neue Status zu laden.

Sie haben zwei Möglichkeiten, Daten an Ihre Webanwendung zu übergeben:

  • Mit Actions Builder Actions Builder füllt das Feld data in Die Canvas-Antwort mit den erforderlichen Metadaten zum Aktualisieren der Webanwendung.
  • Mit einem Webhook. Wenn Sie einen Webhook haben, können Sie benutzerdefinierte Daten Nutzlast, um die Webanwendung in der Canvas-Antwort zu aktualisieren.

In den folgenden Abschnitten wird beschrieben, wie Sie Daten über Actions Builder und über einen Webhook.

Mit Actions Builder Daten übergeben

Mit Actions Builder müssen Sie keinen Webhook definieren, um die Metadaten zu verwalten. der an Ihre Webanwendung gesendet wird. Wenn Sie Ihren Intent-Handler stattdessen in Actions Builder-Benutzeroberfläche können Sie eine Canvas-Antwort einfügen. A Das Feld data wird automatisch mit den erforderlichen Metadaten für die Aktualisierung gefüllt wie der Intent-Name, alle von der Nutzereingabe erfassten Parameter, und die aktuelle Szene.

Der folgende Guess-Intent-Handler gibt beispielsweise an, dass du einen Canvas-Wert einschließen möchtest Antwort:

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 Text-in-Sprache-Nachricht:

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

Actions Builder erweitert die Canvas-Antwort automatisch mit Metadaten auf die Web-App aktualisieren, wie in den folgenden Snippets gezeigt. In diesem Fall hat die nutzende Person hat den Buchstaben „a“ erraten in einem Worträtselspiel:

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 geht zur in der richtigen Szene zu finden.

Daten mit dem Webhook übergeben

Sie können das Feld data von Canvas-Antworten im Webhook manuell konfigurieren mit den erforderlichen Statusinformationen, um Ihre Webanwendung zu aktualisieren. Dieser Ansatz ist 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 in Ihrem 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": ""
    }
  }
}

Richtlinien und Einschränkungen

Beachte die folgenden Richtlinien und Einschränkungen für Antworten auf Canvas beim Erstellen einer Aktion:

  • Jeder Webhook-Handler in der Auftragsausführung muss Canvas enthalten. Wenn der Webhook Antwort nicht Canvas enthält, wird die Webanwendung geschlossen.
  • Sie müssen in der ersten Canvas-Antwort nur die URL Ihrer Web-App angeben. die Sie an den Nutzer senden.
  • Die Canvas-Antwort-URL muss gültig und das dazugehörige HTTPS-Protokoll sein.
  • Die Antwort Canvas darf maximal 50 KB groß sein.