Diese Seite wurde von der Cloud Translation API übersetzt.

Mit Actions Builder eine interaktive Canvas-Aktion für Google Assistant erstellen

1. Übersicht

Actions on Google ist eine Entwicklerplattform, mit der Sie Software erstellen können, um die Funktionen von Google Assistant, dem virtuellen persönlichen Assistenten von Google, auf mehr als einer Milliarde Geräten wie intelligenten Lautsprechern, Smartphones, Autos, Fernsehern und Kopfhörern zu erweitern. Nutzer interagieren mit Google Assistant, um Dinge zu erledigen, z. B. Lebensmittel zu kaufen oder eine Fahrt zu buchen. Eine vollständige Liste der aktuellen Möglichkeiten finden Sie im Aktionsverzeichnis. Als Entwickler können Sie mit Actions on Google ganz einfach ansprechende und nützliche Unterhaltungen zwischen Nutzern und Ihrem eigenen Drittanbieterdienst erstellen und verwalten.

Dieses Codelab ist ein Modul für Fortgeschrittene für Leser, die bereits Erfahrung mit dem Erstellen von Actions for Google Assistant haben. Wenn Sie noch keine Entwicklungserfahrung mit Actions on Google haben, machen Sie sich mithilfe der Codelabs ( Level 1 und Level 2) mit der Plattform vertraut. In diesen Modulen lernst du verschiedene Funktionen kennen, mit denen du die Funktionen deiner Aktion erweitern und mehr Zuschauer gewinnen kannst.

In diesem Codelab verwenden Sie Interactive Canvas, ein Framework auf Google Assistant, um einer Konversationsaktion ein Spiel im Vollbildmodus hinzuzufügen. Das Spiel ist eine interaktive Web-App, die Assistant als Antwort an den Nutzer in einer Unterhaltung sendet. Der Nutzer kann das Spiel dann entweder per Sprach- oder Texteingabe auf Smart Displays und Android-Mobilgeräten spielen.

Anstatt ein ganzes Spiel selbst zu entwickeln, stellen Sie ein teilweise vorgefertigtes Spiel namens Snow Pal bereit und fügen die Spiellogik im Codelab hinzu. Snow Pal ist eine Variante des traditionellen Hangman-Spiels. zeigt Ihnen das Spiel eine Reihe von Leerräumen an, die ein Wort darstellen, und Sie erraten Buchstaben, die Ihrer Meinung nach in dem Wort vorkommen könnten. Mit jedem falschen Tipp schmilzt dein Snow Pal ein wenig weiter. Du gewinnst das Spiel, wenn du das Wort errätst, bevor dein Snow Pals vollständig schmilzt.

Abbildung 1. Ein teilweise abgeschlossenes Snow Pal-Spiel

Aufgaben

In diesem Codelab erstellen Sie eine Aktion mit interaktivem Canvas. Deine Aktion wird die folgenden Funktionen haben:

Ein Wortspiel im Vollbildmodus, das Nutzer per Sprachbefehl spielen können
Eine Schaltfläche, mit der Nutzer das Spiel starten können
Schaltfläche, über die der Nutzer das Spiel noch einmal spielen kann

Wenn du dieses Codelab abgeschlossen hast, läuft die abgeschlossene Aktion so aus:

Assistent : Welcome to Snow Pal! Would you like to start playing the game?

Nutzer: Yes.

Assistent : Try guessing a letter in the word or guessing the word.

Nutzer: I guess the letter E.

Assistent : Let's see if your guess is there...E is right. Right on! Good guess.

Bis das Spiel zu Ende ist, rät der Nutzer weiter Buchstaben oder unbekannte Wörter.

Lerninhalte

Interaktive Canvas-Aktion erstellen und bereitstellen
So aktualisieren Sie das Wortspiel basierend auf der Sprach- und Berührungseingabe eines Nutzers
Daten mithilfe verschiedener Methoden an die Webanwendung übergeben
Fehlerbehebung für interaktive Canvas-Aktion

Voraussetzungen

Für dieses Codelab müssen folgende Voraussetzungen erfüllt sein:

Ein Webbrowser wie Google Chrome
Eine IDE oder einen Texteditor Ihrer Wahl
Node.js, npm und git auf Ihrem Computer installiert

Es wird dringend empfohlen, mit JavaScript (ES6) vertraut zu sein, damit Sie den in diesem Codelab verwendeten Code besser verstehen.

Optional: Vollständigen Beispielcode abrufen

In diesem Codelab erstellen Sie das Beispiel Schritt für Schritt aus einer unvollständigen Version. Sie können das vollständige Beispiel auch im GitHub-Repository herunterladen.

2. Einführung in Interactive Canvas

Interactive Canvas ist ein Framework, das auf Google Assistant basiert und es Ihnen ermöglicht, Ihrer Konversationsaktion Bilder und Animationen im Vollbildmodus hinzuzufügen.

Eine Aktion mit interaktivem Canvas funktioniert ähnlich wie eine normale Conversational Action. Eine interaktive Canvas-Aktion hat jedoch die zusätzliche Möglichkeit, eine Antwort an das Gerät zu senden, über das eine Vollbild-Web-App geöffnet wird.

Der Nutzer kann die Web-App entweder per Spracheingabe oder durch Berührung eingeben, bis die Unterhaltung beendet ist.

Abbildung 2: Eine Aktion, die mit Interactive Canvas erstellt wurde.

In diesem Codelab ist Ihr Projekt in die folgenden drei Hauptteile unterteilt:

Web-App:Die Web-App-Dateien enthalten den Code für die Bilder und Animationen Ihrer Web-App sowie eine Logik, um die Web-App basierend auf der Eingabe des Nutzers zu aktualisieren.
Unterhaltungsaktion:Diese enthält Ihre Unterhaltungslogik, die die Eingabe des Nutzers erkennt, verarbeitet und darauf reagiert.
Webhook:Der Webhook verarbeitet die Logik des Spiels. In diesem Codelab können Sie sich den Webhook als Ihren Gameserver vorstellen.

In jedem Abschnitt dieses Codelabs ändern Sie die Webanwendung, die Konversationsaktion und den Webhook, um Ihrer interaktiven Canvas-Aktion Funktionen hinzuzufügen.

Grundsätzlich funktionieren Konversationsaktion, Webhook und Webanwendung in der Snow Pal-Aktion so:

Die Konversationsaktion fordert den Nutzer auf, einen Buchstaben im Wort oder das ganze Wort zu erraten.
Der Nutzer sagt auf einem Smart Display „Ich denke, der Buchstabe i“ zur Web-App Snow Pal.
Die Eingabe des Nutzers wird an Ihre Unterhaltungsaktion weitergeleitet, die in Ihrem Actions Builder- und/oder Actions SDK-Projekt definiert ist.
Die Konversationsaktion verarbeitet die Eingabe des Nutzers und löst je nach Eingabe entweder eine Logik im Webhook aus, die die Webanwendung aktualisiert, oder Metadaten sendet, um die Webanwendung direkt zu aktualisieren.
Die Web-App wird aktualisiert und zeigt an, an welcher Stelle der Buchstabe im Wort vorkommt, und der Nutzer wird aufgefordert, noch einmal zu erraten.

Weitere Informationen zur Funktionsweise des interaktiven Canvas finden Sie im Abschnitt Informationen zur Infrastruktur des interaktiven Canvas. Nachdem Sie nun mit den Grundlagen vertraut sind, können Sie Ihre Umgebung für dieses Codelab einrichten.

3. Einrichten

Google-Berechtigungseinstellungen prüfen

Zum Testen der Aktion, die Sie für dieses Codelab erstellen, müssen Sie die erforderlichen Berechtigungen aktivieren, damit der Actions Console-Simulator auf Ihre Aktion zugreifen kann. So aktivieren Sie Berechtigungen:

Gehen Sie zu den Aktivitätseinstellungen.
Melden Sie sich gegebenenfalls mit Ihrem Google-Konto an.
Aktivieren Sie die folgenden Berechtigungen:

Web- & App-Aktivitäten
Wählen Sie unter Web- und App-Aktivitäten: Klicken Sie das Kästchen Auch den Chrome-Verlauf sowie Aktivitäten auf Websites, in Apps und auf Geräten berücksichtigen, die Google-Dienste nutzen an.

gactions-Befehlszeile installieren

In diesem Codelab verwenden Sie das gactions-Befehlszeilentool (CLI), um Ihr Actions-Projekt zwischen der Actions Console und Ihrem lokalen Dateisystem zu synchronisieren.

Folgen Sie der Anleitung im Abschnitt gactions-Befehlszeilentool installieren, um die gactions-Befehlszeile zu installieren.

Firebase-Befehlszeile installieren

Mit der Firebase-Befehlszeile können Sie Ihr Actions-Projekt in Cloud Functions bereitstellen und Ihre Webanwendung hosten.

In diesem Codelab wird npm verwendet, um die Firebase CLI zu installieren. Installieren Sie unbedingt npm, das normalerweise in Node.js enthalten ist.

Öffnen Sie ein Terminal und führen Sie den folgenden npm-Befehl aus, um die Befehlszeile zu installieren oder zu aktualisieren:

npm install -g firebase-tools

Führen Sie den folgenden Befehl aus, um zu prüfen, ob die Befehlszeile korrekt installiert wurde:

firebase --version

Achten Sie darauf, dass Version 8 oder höher der Firebase CLI installiert ist, damit alle neuen Funktionen verfügbar sind, die für Cloud Functions erforderlich sind. Ist dies nicht der Fall, führen Sie npm install -g firebase-tools aus, um ein Upgrade durchzuführen.

Führen Sie den folgenden Befehl aus, um sich bei Firebase anzumelden:

firebase login

Achten Sie bei der Anmeldung in Firebase darauf, dass Sie dasselbe Google-Konto verwenden, mit dem Sie das Actions-Projekt erstellt haben.

Repository klonen

In diesem Abschnitt klonen Sie die Dateien, die Sie für dieses Codelab benötigen. So rufen Sie diese Dateien ab:

Öffnen Sie ein Terminal und wechseln Sie zu einem Verzeichnis, in dem Sie normalerweise Codierungsprojekte speichern. Wenn Sie keins haben, wechseln Sie zu Ihrem Basisverzeichnis.
Führen Sie den folgenden Befehl in Ihrem Terminal aus, um dieses Repository zu klonen:

git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

Öffnen Sie das Verzeichnis start/. Dieses Repository enthält die folgenden wichtigen Verzeichnisse, mit denen Sie arbeiten werden:

public/: Dieses Verzeichnis enthält den HTML-, CSS- und JavaScript-Code für Ihre Webanwendung.
sdk/custom/: Dieses Verzeichnis enthält die Logik für Ihre Konversationsaktion (Szenen, Intents und Typen).
sdk/webhooks/: Dieses Verzeichnis ist Ihr Webhook und enthält die Spiellogik.

Abbildung 3: Die Struktur des Verzeichniscodes start.

4. Actions-Projekt einrichten

In diesem Abschnitt erstellen und konfigurieren Sie Ihr Actions-Projekt, übertragen den Code mit der gactions-Befehlszeile aus dem geklonten Repository per Push an die Actions Console und stellen Ihre Webanwendung und Ihren Webhook bereit.

Actions-Projekt erstellen

Ihr Actions-Projekt ist ein Container für Ihre Aktion. So erstellen Sie das Actions-Projekt für dieses Codelab:

Öffnen Sie die Actions Console.
Klicken Sie auf Neues Projekt.
Geben Sie einen Projektnamen ein, z. B. canvas-codelab. Dieser Name ist für Ihre interne Referenz gedacht. Später können Sie einen externen Namen für Ihr Projekt festlegen.

Klicken Sie auf Projekt erstellen.
Wählen Sie im Bildschirm Welche Art von Aktion möchten Sie erstellen? die Karte Spiel aus.
Klicken Sie auf Weiter.
Wählen Sie die Karte Leeres Projekt aus.
Klicken Sie auf Jetzt erstellen.

Projekt-ID für deine Aktion speichern

Die Projekt-ID ist eine eindeutige Kennung für deine Aktion. Sie benötigen Ihre Projekt-ID für mehrere Schritte in diesem Codelab.

So rufen Sie Ihre Projekt-ID ab:

Klicken Sie in der Actions Console auf das Dreipunkt-Menü > Projekteinstellungen:

Kopieren Sie die Projekt-ID.

Rechnungskonto verknüpfen

Wenn Sie die Auftragsausführung später in diesem Codelab mit Cloud Functions bereitstellen möchten, müssen Sie ein Rechnungskonto mit Ihrem Projekt in Google Cloud verknüpfen. Wenn Sie bereits ein Rechnungskonto haben, können Sie die folgenden Schritte ignorieren.

So verknüpfen Sie ein Rechnungskonto mit Ihrem Projekt:

Rufen Sie die Abrechnungsseite der Google Cloud Platform auf.
Klicken Sie auf Rechnungskonto hinzufügen oder Konto erstellen.
Geben Sie Ihre Zahlungsinformationen ein.
Klicken Sie auf Kostenlosen Test starten oder auf Senden und Abrechnung aktivieren.
Rufen Sie die Abrechnungsseite von Google Cloud auf.
Klicken Sie auf den Tab Meine Projekte.
Klicke auf die drei Punkte > Abrechnung ändern
Wählen Sie im Drop-down-Menü das von Ihnen konfigurierte Rechnungskonto aus.
Klicken Sie auf Konto festlegen.

Führen Sie die Schritte im Abschnitt Projekt bereinigen aus, um Gebühren zu vermeiden.

Webanwendung bereitstellen

In diesem Abschnitt stellen Sie Ihre Webanwendung (das Spiel SnowPal) mit Firebase CLI bereit. Nach der Bereitstellung können Sie die URL für die Webanwendung abrufen und sich ansehen, wie das Spiel in einem Browser aussieht.

So stellen Sie Ihre Webanwendung bereit:

Rufen Sie im Terminal das Verzeichnis start/ auf.
Führen Sie den folgenden Befehl aus und ersetzen Sie dabei {PROJECT_ID} durch Ihre Projekt-ID:

firebase deploy --project {PROJECT_ID} --only hosting

Nach einigen Minuten sollte "Deploy complete!" angezeigt werden. Das bedeutet, dass Sie die Snow Pal-Web-App in Firebase bereitgestellt haben.

So rufen Sie das Spiel Snow Pal in einem Browser auf:

Rufen Sie die Hosting-URL aus der Ausgabe Ihres Terminals ab. Die URL sollte das folgende Format haben: https://<PROJECT_ID>.web.app

Fügen Sie die URL in einen Browser ein. Der Startbildschirm des Spiels Snow Pal sollte mit der Schaltfläche Spiel starten angezeigt werden:

Web-App-URL und Projekt-ID zum Actions-Projekt hinzufügen

Fügen Sie als Nächstes die URL Ihrer Webanwendung und die Projekt-ID zur Datei actions.intent.MAIN.yaml hinzu. Wenn Sie die URL der Webanwendung hinzufügen, weiß die Conversational Action, an welche URL Daten gesendet werden sollen. Wenn Sie hingegen die Projekt-ID in settings.yaml hinzufügen, können Sie die heruntergeladenen Dateien in das richtige Projekt in der Actions Console verschieben.

So fügen Sie die URL der Web-App und die Projekt-ID hinzu:

Öffnen Sie die Datei start/sdk/custom/global/actions.intent.MAIN.yaml in Ihrem Texteditor.
Ersetzen Sie im Feld URL den Platzhalterstring durch die URL Ihrer Web-App.
Öffnen Sie die Datei start/sdk/settings/settings.yaml in Ihrem Texteditor.
Ersetzen Sie im Feld projectId den Platzhalterstring durch Ihre Projekt-ID.

Projekt an Actions Console übertragen

Um die Actions Console mit Ihrem lokalen Projekt zu aktualisieren, müssen Sie Ihr Actions-Projekt an die Actions Console übertragen. Führen Sie dazu die folgenden Schritte aus:

Wechseln Sie in das Verzeichnis sdk:

cd sdk/

Führen Sie den folgenden Befehl aus, um die Konfiguration Ihres lokalen Dateisystems in die Actions Console zu kopieren:

gactions push

Webhook bereitstellen

Bei der Ausführung von gactions push haben Sie den Startcode des Webhooks in die Actions Console importiert. Für den Rest dieses Codelabs können Sie den Webhook-Code in der Actions Console bearbeiten. Jetzt können Sie den Webhook über die Actions Console bereitstellen.

So stellen Sie den Webhook bereit:

Klicken Sie in der Actions Console in der Navigationsleiste auf Develop.
Klicken Sie in der Navigationsleiste auf den Tab Webhook.
Klicken Sie auf Deploy Fulfillment (Auftragsausführung bereitstellen).

Es kann einige Minuten dauern, bis Cloud Functions die Auftragsausführung bereitgestellt und bereitgestellt hat. Es sollte die Meldung Cloud Function-Bereitstellung in Bearbeitung... angezeigt werden. Wenn der Code erfolgreich bereitgestellt wurde, wird die Meldung Ihre Cloud Functions-Bereitstellung ist auf dem neuesten Stand aktualisiert.

Im Simulator testen

Jetzt ist deine Aktion mit der Web-App verknüpft. Mit dem Actions Console-Simulator kannst du dafür sorgen, dass die Web-App angezeigt wird, wenn du deine Aktion aufrufst.

So testest du deine Aktion:

Klicken Sie in der Navigationsleiste der Actions Console auf Testen.
Geben Sie Talk to Snow Pal sample in das Feld Eingabe ein und drücken Sie Enter.
Geben Sie Yes in das Feld Eingabe ein und drücken Sie Enter. Alternativ können Sie auch auf Spiel starten klicken.

Sie haben noch keine Logik zum Erraten eines Buchstabens oder eines Wortes konfiguriert. Wenn Sie also ein Wort oder einen Buchstaben erraten, erhalten Sie die Antwort "...Falsch. Versuch es weiter! Es sieht so aus, als müssten wir weitere Funktionen hinzufügen, damit das richtig funktioniert.“

5. Informationen zur Interactive Canvas-Infrastruktur

Bei diesem Projekt ist die Funktionalität in drei Hauptkomponenten organisiert: die Konversationsaktion, die Webanwendung und den Webhook. Beachten Sie, dass dies nur ein Modell für die Einrichtung Ihrer Aktion ist. Es ist so organisiert, dass die Hauptfunktionen von Interactive Canvas hervorgehoben werden.

In den folgenden Abschnitten finden Sie weitere Informationen zum Zusammenspiel von Konversationsaktionen, Webhooks und Web-Apps sowie weiterer wichtiger Elemente des interaktiven Canvas.

Konversationsaktion

Die Komponente „Conversational Action“ deiner Aktion verarbeitet die Eingabe des Nutzers, verarbeitet sie und sendet sie an die entsprechende Szene, wo eine Antwort für den Nutzer generiert wird. Wenn ein Nutzer im Spiel Snow Pal beispielsweise "Ich erraten den Buchstaben e" sagt, extrahiert Ihre Konversationsaktion den Buchstaben als Intent-Parameter und übergibt ihn an die entsprechende Spiellogik. Diese prüft, ob die Vermutung korrekt ist, und aktualisiert die Webanwendung entsprechend. Sie können diese Konversationslogik in Actions Builder, einer webbasierten IDE, in der Actions Console ansehen und ändern. Der folgende Screenshot zeigt einen Teil der Konversationsaktion im Actions Builder:

Abbildung 4: Eine Visualisierung von Main invocation in Actions Builder.

Dieser Screenshot zeigt das Main invocation für deine Aktion, mit dem Nutzer übereinstimmen, wenn sie einen Satz wie „Hey Google, sprich mit Snow Pal-Beispiel“ sagen. Wenn der Nutzer deine Aktion aufruft, sendet Main invocation eine Eingabeaufforderung mit der Antwort canvas, die die URL deiner Webanwendung enthält.

Die erste canvas-Antwort in deiner Aktion muss die URL der Webanwendung enthalten. Durch diese Antwort wird Assistant angewiesen, die Web-App unter dieser Adresse auf dem Gerät des Nutzers zu rendern. Zusätzliche canvas-Antworten in Actions Builder können das Feld send_state_data_to_canvas_app enthalten, für das true festgelegt ist. Über dieses Feld werden der Intent-Name und alle Parameterwerte an die Web-App gesendet, wenn der Intent zugeordnet wird. Die Web-App wird dann anhand dieser Daten aus der Nutzereingabe aktualisiert.

Webhook

In diesem Codelab enthält der Webhook die Spielelogik. Sie können sich den Webhook wie einen Spieleserver vorstellen. Die Spiellogik umfasst Elemente wie die Feststellung, ob die Vermutung eines Nutzers richtig oder falsch ist oder ob der Nutzer gewonnen oder verloren hat, und die Erstellung einer Antwort basierend auf dem Ergebnis. Sie können Ihren Webhook in Actions Builder ändern.

Wenn deine Aktion die Spiellogik ausführen muss, sendet Actions Builder einen Aufruf an den Webhook. Der Intent guess in der Szene Game sendet beispielsweise einen Webhook-Aufruf an den Handler guess, der dann eine Logik ausführt, um festzustellen, ob die Vermutung des Nutzers richtig ist. Der Webhook kann Canvas-Antworten in den Handlern enthalten, die Dateien der Web-App zugeordnet sind und das Web entsprechend aktualisieren.

Web-App

Abbildung 5: Eine visuelle Darstellung der Interaktion zwischen der Konversationsaktion, dem Webhook und der Webanwendung in einer interaktiven Canvas-Aktion.

Die Web-App-Dateien enthalten den Code für die Bilder und Animationen Ihrer Web-App sowie eine Logik, um die Web-App basierend auf den Eingaben des Nutzers zu aktualisieren. Sie ändern die Dateien der Web-App im Texteditor und stellen sie mithilfe der Firebase CLI bereit.

Kommunikation zwischen Konversationsaktionen und Web-Apps

Sie müssen die Kommunikation zwischen Ihrer Konversationsaktion und der Web-App aktivieren, damit Ihre Web-App basierend auf Nutzereingaben aktualisiert werden kann. Sagt ein Nutzer beispielsweise "Ich erkenne den Buchstaben f",

Die Conversational Action muss der Webanwendung den Buchstaben f bereitstellen, damit sie entsprechend aktualisiert werden kann. Um die Eingabe des Nutzers aus der Conversational Action an die Webanwendung zu übergeben, müssen Sie die Interactive Canvas API laden.

Das Skript für diese API ist in /public/index.html enthalten. Dies ist die HTML-Hauptdatei für das Spiel Snow Pal. Diese Datei definiert in verschiedenen Skripts, wie Ihre Benutzeroberfläche aussieht und geladen wird:

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

Wenn Sie die Web-App basierend auf den Eingaben des Nutzers aktualisieren möchten, müssen Sie außerdem Callbacks in Ihrer Web-App-Datei registrieren und konfigurieren. Mit Callbacks kann Ihre Webanwendung auf Informationen oder Anfragen der Konversationsaktion reagieren.

In /public/js/action.js ist eine vorkonfigurierte Klasse namens Action zum Deklarieren und Registrieren von Callbacks vorhanden. Die Klasse Action ist ein Wrapper um die Interactive Canvas API. Wenn die Web-App mit der Funktion create() in scene.js erstellt wird, wird eine neue Action-Instanz erstellt und setCallbacks() aufgerufen, wie im folgenden Snippet gezeigt:

scene.js

// Set Assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register Assistant Action callbacks.
this.assistant.setCallbacks();

Die Funktion setCallbacks() ist in der Klasse Action von /public/js/action.js definiert. Diese Funktion deklariert Callbacks und registriert sie bei der Interactive Canvas API beim Erstellen des Spiels:

  setCallbacks() {
    // Declare the Interactive Canvas Action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

Die Funktion setCallbacks() deklariert den Callback onUpdate(), der jedes Mal aufgerufen wird, wenn Sie eine Canvas-Antwort senden.

Im nächsten Abschnitt wird beschrieben, wie der spezifische Code für dieses Projekt so konfiguriert ist, dass Daten von der Konversationsaktion an die Webanwendung übergeben werden.

Webanwendung basierend auf Nutzereingaben aktualisieren

In diesem Codelab verwenden Sie eine Befehlszuordnung, um die Webanwendung basierend auf der Eingabe eines Nutzers zu aktualisieren. Wenn beispielsweise der Intent start_game in der Szene Welcome abgeglichen wird, wird die im Prompt enthaltene canvas-Antwort an die Web-App gesendet. onUpdate() parst die Metadaten aus der canvas-Antwort und ruft den START_GAME-Befehl auf, der wiederum die start()-Funktion in scene.js aufruft und die Webanwendung aktualisiert, um eine neue Spielsitzung zu starten.

Die Funktion start() in scene.js ruft auch die Funktion updateCanvasState() auf, die eine Methode namens setCanvasState() verwendet, um Statusdaten hinzuzufügen, auf die der Webhook zugreifen kann.

Die Methode updateCanvasState() wird am Ende jedes Befehls aufgerufen (diese Befehle werden Sie dann im gesamten Codelab einfügen) und aktualisiert den Status der Webanwendung. Bei jedem Aufruf von updateCanvasState() werden die Werte für displayedWord und incorrectGuesses anhand des aktuellen Status aktualisiert:

scene.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

Der aktualisierte Status ist dann für die nächste Unterhaltungsrunde verfügbar. Sie können im Webhook über conv.context.canvas.state auf diesen Status zugreifen, wie im folgenden Code-Snippet gezeigt:

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

6. Vorschlagsfunktion hinzufügen

In diesem Abschnitt fügst du deiner Aktion die Funktion guess hinzu, mit der Nutzer Buchstaben innerhalb des Wortes oder des Wortes selbst erraten können.

Konversationsaktion

Im Abschnitt Test in the simulator (Im Simulator testen) haben Sie eine Antwort mit folgendem Inhalt erhalten: „Es sieht so aus, als müssten wir weitere Funktionen hinzufügen, damit das korrekt funktioniert.“ Jetzt können Sie diese Aufforderung in der Actions Console löschen, sodass nur der Webhook aufgerufen wird. In der Szene Game ist der Intent guess bereits so konfiguriert, dass nach dem Abgleich ein Webhook-Aufruf getätigt wird.

So entfernen Sie die statische Aufforderung, wenn der Intent guess zugeordnet wird:

Klicken Sie in der Actions Console in der Navigationsleiste auf Szenen.
Klicken Sie auf Spiel, um zur Szene Game zu gelangen.
Klicken Sie unter Umgang mit Nutzerabsichten auf Bei Zuordnung der Vermutung. Entfernen Sie das Häkchen aus dem Kästchen neben Prompts senden, um die Aufforderung zu entfernen.
Klicken Sie auf Speichern.

Webhook

In diesem Abschnitt aktualisieren Sie den Webhook mit einer Logik, die die richtige oder falsche Vermutung eines Nutzers der Logik in einer Web-App-Datei zuordnet. Die Webanwendung wird dann entsprechend aktualisiert. Der Intent-Handler guess ist bereits im Webhook für Sie konfiguriert. Daher müssen Sie diesem Intent nur Canvas-Antworten hinzufügen, um die Logik auszulösen, die die Webanwendung aktualisiert.

So aktualisieren Sie den Webhook:

Klicken Sie in der Actions Console in der Navigationsleiste auf Webhook.
Fügen Sie in index.js unter dem Handler guess den folgenden Code hinzu:

index.js (Abschnitt A):

// Add Section A `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (Abschnitt B):

// Add Section B `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));

Klicken Sie auf Auftragsausführung speichern.
Klicken Sie auf Deploy Fulfillment (Auftragsausführung bereitstellen). Wenn die Bereitstellung abgeschlossen ist, wird die Meldung Ihre Cloud Functions-Bereitstellung ist auf dem neuesten Stand angezeigt.

Web-App

Sie können Ihre Webanwendung jetzt für die Verarbeitung der Befehle CORRECT_ANSWER und INCORRECT_ANSWER konfigurieren.

Öffnen Sie public/js/action.js in Ihrem Texteditor.
Aktualisieren Sie die Webanwendung, damit die Befehle CORRECT_ANSWER und INCORRECT_ANSWER verarbeitet werden können:

action.js (Abschnitt C):

// Add Section C `CORRECT_ANSWER: (params) => {` content here.
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },

Führen Sie den folgenden Befehl aus, um die Webanwendung zu aktualisieren:

firebase deploy --project {PROJECT_ID} --only hosting

Aktion im Simulator testen

Deine Aktion kann dann erkennen, ob eine Vermutung richtig oder falsch ist, und die Web-App entsprechend aktualisieren.

So testest du deine Aktion:

Klicken Sie in der Navigationsleiste auf Testen.
Geben Sie Talk to Snow Pal sample in das Feld Eingabe ein und drücken Sie Enter.
Geben Sie Yes in das Feld Eingabe ein und drücken Sie Enter. Alternativ können Sie auch auf die Schaltfläche Ja klicken.
Geben Sie in das Feld Eingabe den Buchstaben ein, den Sie erraten möchten, und drücken Sie die Enter.

Code verstehen

Im vorherigen Abschnitt haben Sie Code hinzugefügt, mit dem Nutzer Buchstaben in Ihrem Spiel erraten können und diese Vermutungen entweder im Wort oder im Snow Pal widergespiegelt werden. Auf übergeordneter Ebene führen Sie einen Webhook-Aufruf in Actions Builder aus, wenn der Intent guess zugeordnet wird. Dieser übergibt Daten an Ihre Webanwendung, um sie entsprechend zu aktualisieren. Wenn der Nutzer beispielsweise im Spiel Snow Pal einen Buchstaben errät, der in dem Wort enthalten ist, wird die Web-App aktualisiert und zeigt den Buchstaben an der richtigen Stelle im Wort an.

Bei Aktionen mit interaktivem Canvas werden Daten vom Webhook an die Web-App grundsätzlich folgendermaßen übergeben:

Die Eingabe des Nutzers stimmt mit einem Intent überein, der eine Canvas-Antwort enthält.
Die Konversationsaktion oder der Webhook sendet die Canvas-Antwort, die den onUpdate()-Callback auslöst.
Der onUpdate()-Callback ist einer benutzerdefinierten Logik zugeordnet, die die Webanwendung entsprechend aktualisiert.

Für dieses spezielle Projekt funktioniert der Code so:

Wenn der Nutzer dem Intent guess entspricht, extrahiert Actions Builder den Buchstaben aus der Nutzereingabe als Parameter.
Actions Builder ruft den guess-Handler im Webhook auf. Dieser enthält die Logik, um zu bestimmen, ob der vom Nutzer erratene Buchstabe im Wort enthalten ist.
Der guess-Handler enthält zwei Canvas-Antworten: eine wird ausgeführt, wenn der Buchstabe korrekt ist, und eine, die ausgeführt wird, wenn der Buchstabe falsch ist. Mit jeder Canvas-Antwort werden die entsprechenden Daten (Befehl CORRECT_ANSWER oder INCORRECT_ANSWER) an die Webanwendung übergeben.
Die Daten im Feld data der Canvas-Antwort werden an die Methode onUpdate() in action.js übergeben. onUpdate() ruft den entsprechenden Befehl in der Befehlszuordnung in scene.js auf.
Die Befehlszuordnung ist den Funktionen correctAnswer() und incorrectAnswer() in scene.js zugeordnet. Diese Funktionen aktualisieren die Web-App entsprechend, sodass sie der Vermutung des Nutzers entspricht, und rufen setCanvasState() auf, um Statusdaten von Ihrer Webanwendung an den Webhook zu senden.

7. Gewinn-/Verlust-Funktion hinzufügen

In diesem Abschnitt fügst du deiner Aktion die Gewinner- und Verliererfunktion hinzu. Dazu gehören eine Logik, die bestimmt, ob der Nutzer gewonnen oder verloren hat, sowie eine Logik, um das Bild der Web-App basierend auf dem Ergebnis des Nutzers zu aktualisieren.

Konversationsaktion

Die Funktionen, mit denen Nutzer gehandhabt werden, um das Spiel zu gewinnen oder zu verlieren, werden im Intent guess konfiguriert, sodass Sie keine zusätzliche Konfiguration in Actions Builder vornehmen müssen.

Webhook

In diesem Abschnitt aktualisieren Sie den Webhook mit einer Logik, die verarbeitet, wenn ein Nutzer das Spiel gewonnen oder verloren hat, und der Web-App-Logik zugeordnet, die das Spiel mit dem entsprechenden Gewinn- oder Verliererbildschirm aktualisiert.

So aktualisieren Sie den Webhook:

Klicken Sie in der Actions Console in der Navigationsleiste auf Webhook.
Fügen Sie in index.js unter dem Handler guess den folgenden Code hinzu:

index.js (Abschnitt D):

// Add Section D `if (userHasWon)` content here.
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!  
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (Abschnitt E):

// Add Section E `}` here.
}

index.js (Abschnitt F):

// Add Section F `Check if the user has exceeded the maximum` content here.
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (Abschnitt G):

// Add Section G `}` here.
}

Klicken Sie auf Auftragsausführung speichern.
Klicken Sie auf Deploy Fulfillment (Auftragsausführung bereitstellen). Wenn die Bereitstellung abgeschlossen ist, wird die Meldung Ihre Cloud Functions-Bereitstellung ist auf dem neuesten Stand angezeigt.

Hier hast du zwei Canvas-Antworten mit den Befehlen WIN_GAME und LOSE_GAME hinzugefügt, um zu verarbeiten, ob Nutzer das Spiel gewinnen oder verlieren. Im nächsten Abschnitt fügen Sie Funktionen hinzu, mit denen die Web-App je nachdem, ob der Nutzer gewonnen oder verloren hat, aktualisiert wird.

Web-App

Sie können Ihre Webanwendung jetzt so konfigurieren, dass Updates je nachdem, ob der Nutzer gewonnen oder verloren hat, konfiguriert werden. So aktualisieren Sie Ihre Web-App:

Öffnen Sie public/js/action.js in Ihrem Texteditor.
Aktualisieren Sie Ihre Webanwendung, damit die Befehle WIN_GAME und LOSE_GAME verarbeitet werden können:

action.js (Abschnitt H):

// Add Section H `WIN_GAME: (params) => {` content here.
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },

Führen Sie den folgenden Befehl aus, um die Webanwendung zu aktualisieren:

firebase deploy --project {PROJECT_ID} --only hosting

Aktion im Simulator testen

An diesem Punkt kann deine Aktion verarbeiten, wenn der Nutzer das Spiel gewinnt oder verliert, und zeigt den entsprechenden Bildschirm für jedes Ergebnis an.

So testest du deine Aktion:

Klicken Sie in der Navigationsleiste der Actions Console auf Testen.
Geben Sie Talk to Snow Pal sample in das Feld Eingabe ein und drücken Sie Enter.
Geben Sie Yes in das Feld Eingabe ein und drücken Sie Enter. Alternativ können Sie auch auf die Schaltfläche Spiel starten klicken.
Errate Buchstaben und Wörter, bis du entweder gewinnst oder verlierst.

Wenn du noch einmal spielen möchtest, erhältst du die Meldung, dass die erforderliche Funktion zum erneuten Spielen noch nicht hinzugefügt wurde. Diese Funktion wird im nächsten Abschnitt hinzugefügt.

Code verstehen

Die Gewinn- und Verlustfunktion funktioniert genauso wie die Rate-Funktion: Der Nutzer ordnet den Intent guess zu und Ihr Webhook wertet die Vermutung des Nutzers aus. Ist die Vermutung richtig, prüft der Code, ob der Nutzer gewonnen hat. Ist dies der Fall, wird der Befehl WIN_GAME an die Webanwendung gesendet. Ist die Vermutung falsch, prüft der Code, ob sie verloren gegangen ist. Ist dies der Fall, wird der Befehl LOSE_GAME an die Webanwendung gesendet. Diese Befehle lösen die Funktionen winGame() und loseGame() in scene.js aus, mit denen die Web-App aktualisiert wird, um den Gewinner- oder Verliererbildschirm anzuzeigen und den Spielstatus zu aktualisieren.

8. Funktion zum erneuten Abspielen hinzufügen

In diesem Abschnitt fügen Sie Funktionen hinzu, mit denen Nutzer entweder „Noch einmal spielen“ sagen oder in der Web-App auf die Schaltfläche Noch einmal spielen klicken können, um ein neues Spiel zu starten. Sie ändern den Intent play_again in Actions Builder so, dass eine canvas-Antwort gesendet wird, die die Web-App entsprechend aktualisiert. Außerdem fügen Sie eine Logik hinzu, die den Intent play_again auslöst, wenn der Nutzer auf die Schaltfläche Noch einmal wiedergeben klickt.

Konversationsaktion

Als du deine Aktion im vorherigen Abschnitt getestet hast, wurde dir die folgende Aufforderung angezeigt, wenn du versucht hast, das Spiel noch einmal zu spielen: „Das wäre toll, aber wir werden diese Funktion in einem späteren Abschnitt einbauen. Setze die Aktion einfach zurück.“ Du kannst diese Aufforderung jetzt löschen und durch eine ersetzen, die dem Nutzer antwortet, wenn er ein anderes Spiel anfordert („Okay, hier ist ein anderes Spiel!“) und die Antwort canvas enthält, damit die Web-App ein neues Spiel startet.

So aktualisieren Sie die Aufforderung, wenn der Nutzer noch einmal spielen möchte:

Klicken Sie in der Actions Console auf das Drop-down-Menü Szene.
Klicken Sie auf die Szene Spiel.
Klicken Sie unter Handhabung der Nutzerabsicht auf Wenn „play_again“ zugeordnet ist.
Ersetzen Sie die Aufforderung so:

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here''s another game!' 
    canvas:
      sendStateDataToCanvasApp: true

Klicken Sie auf Speichern.

Webhook

In diesem Codelab verwaltet der Webhook die Spiellogik. Da für die Wiederholungsfunktion keine logische Validierung erforderlich ist, müssen Sie den Webhook nicht aufrufen. Stattdessen können Sie eine canvas-Antwort direkt aus Actions Builder senden, um die erforderlichen Daten an die Web-App zu übergeben. Dies haben Sie im vorherigen Abschnitt konfiguriert.

Web-App

Sie können Ihre Web-App-Dateien jetzt so ändern, dass sie entsprechend aktualisiert werden, wenn der Nutzer eine erneute Wiedergabe anfordert. So fügen Sie diese Funktion hinzu:

Öffnen Sie public/js/action.js in Ihrem Texteditor.
Aktualisieren Sie die Webanwendung für den Befehl PLAY_AGAIN:

action.js (Abschnitt I):

// Add Section I `PLAY_AGAIN: (params) => {` content here.
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },

Öffnen Sie public/js/scene.js in Ihrem Texteditor.
Aktualisieren Sie die Web-App, um eine neue Spielsitzung zu starten, wenn der Nutzer auf Noch einmal spielen klickt. Schaltfläche:

Scene.js (Abschnitt J):

// Add Section J `sendTextQuery` content here.
     window.interactiveCanvas.sendTextQuery('Play again');

Führen Sie den folgenden Befehl aus, um die Webanwendung zu aktualisieren:

firebase deploy --project {PROJECT_ID} --only hosting

Aktion im Simulator testen

Deine Aktion kann jetzt eine neue Spielsitzung starten, wenn der Nutzer „Noch einmal spielen“ sagt oder auf die Schaltfläche Noch einmal spielen klickt.

So testest du deine Aktion:

Klicken Sie in der Navigationsleiste auf Testen.
Geben Sie Talk to Snow Pal sample in das Feld Eingabe ein und drücken Sie Enter.
Geben Sie Yes in das Feld Eingabe ein und drücken Sie Enter. Alternativ können Sie auch auf die Schaltfläche Spiel starten klicken.
Errate Buchstaben und Wörter, bis du entweder gewinnst oder verlierst.
Geben Sie Play again in das Feld Eingabe ein und drücken Sie Enter. Alternativ kannst du auch auf die Schaltfläche Noch einmal wiedergeben klicken.

Code verstehen

Wenn Sie Ihre Aktion getestet haben, konnten Sie ein neues Spiel entweder über die Spracheingabe (Erneut spielen) oder durch Eingabe per Berührung (durch Klicken auf die Schaltfläche Erneut wiedergeben) starten.

Wenn der Nutzer bei der Spracheingabe „Noch einmal spielen“ oder eine Variante davon sagt, wird der Intent play_again zugeordnet und der Aufforderungswarteschlange die Aufforderung „Okay, here's other game!“ hinzugefügt. Die canvas-Antwort in der Aufforderung sendet den Intent-Namen und andere Metadaten an die Webanwendung. Der Intent-Name wird an den onUpdate()-Callback übergeben, der den entsprechenden Befehl PLAY_AGAIN der Befehlszuordnung in action.js zuordnet. Der Befehl PLAY_AGAIN löst die Funktion start() in scene.js aus und aktualisiert die Web-App mit einer neuen Spielsitzung.

Für die Option „Eingabe per Berührung“ verwenden Sie sendTextQuery(). Dies ist eine Interactive Canvas API, mit der Sie einen Intent über die Eingabe per Berührung auslösen können, damit die Schaltfläche funktioniert.

In diesem Codelab verwenden Sie sendTextQuery(), um den Intent play_again aufzurufen, wenn ein Nutzer auf die Schaltfläche Noch einmal abspielen klickt. Das Argument Play again stimmt mit einer Trainingsformulierung im Intent play_again überein und löst diesen Intent auf die gleiche Weise aus, wie ein Nutzer, der Noch einmal spielen sagt, dies tut. Der Intent play_again löst dann eine Logik aus, die die Web-App aktualisiert und eine neue Spielsitzung startet.

9. Integrierten Intent für PLAY_GAME aktualisieren

In diesem Abschnitt aktualisieren Sie den integrierten Intent PLAY_GAME.

Mit dem integrierten Intent PLAY_GAME können Nutzer deine Aktion aufrufen, wenn sie eine allgemeine Anfrage wie „I want to play a game“ (Ich möchte ein Spiel spielen) stellen.

Der Quellcode enthält den integrierten Intent PLAY_GAME unter /sdk/custom/global/actions.intent.PLAY_GAME.yaml. Dies wird in der Konsole im Abschnitt Invocation als PLAY_GAME angezeigt, wie im folgenden Screenshot dargestellt:

Damit Nutzer deine Aktion über diesen integrierten Intent aufrufen können, musst du dem integrierten Intent PLAY_GAME eine canvas-Antwort mit der URL der Webanwendung hinzufügen. Führen Sie dazu die folgenden Schritte aus:

Klicke in der Actions Console in der Navigationsleiste auf PLAY_GAME.
Fügen Sie der Aufforderung die URL Ihrer Web-App hinzu, wie im folgenden Snippet gezeigt:

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

Klicken Sie auf Speichern.

Aktion im Simulator testen

Deine Aktion unterstützt jetzt den integrierten Intent PLAY_GAME.

So testest du deine Aktion:

Klicken Sie in der Navigationsleiste auf Testen.
Klicken Sie auf Integrierte Intent-Verarbeitung testen.
Klicken Sie auf Aktion aufrufen.

Deine Aktion sollte im Simulator aufgerufen werden.

10. Anhang: Fehlerbehebung für die interaktive Canvas-Aktion

In diesem Abschnitt erfahren Sie, wie Sie Fehler in interaktiven Canvas-Aktionen beheben, wenn sie nicht richtig funktionieren. Das Snow Pal-Projekt wird mit einem vorgefertigten Debugging-Overlay geliefert, das Sie aktivieren können. Im Overlay werden unten rechts auf dem Bildschirm alle console.log()- und console.error()-Ausgaben angezeigt, wie im folgenden Screenshot zu sehen ist:

Um dieses Overlay zu aktivieren, öffnen Sie die Datei /public/css/main.css und kommentieren Sie die Zeile display: none !important;, wie im folgenden Snippet gezeigt:

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

Projekt bereinigen [empfohlen]

Um mögliche Kosten zu vermeiden, sollten Sie Projekte entfernen, die Sie nicht verwenden möchten. So löschen Sie die Projekte, die Sie in diesem Codelab erstellt haben:

Führen Sie die im Abschnitt Projekte beenden (löschen) aufgeführten Schritte aus, um das Google Cloud-Projekt und die Ressourcen zu löschen.

Optional: Wenn Sie Ihr Projekt sofort aus der Actions Console entfernen möchten, führen Sie die Schritte im Abschnitt Projekt löschen aus. Wenn Sie diesen Schritt nicht ausführen, wird Ihr Projekt nach etwa 30 Tagen automatisch entfernt.

11. Glückwunsch!

Sie haben das einführende Interaktive Canvas-Codelab abgeschlossen und können nun Ihre eigene interaktive Canvas-Aktion erstellen.

Das haben Sie gelernt

Interaktive Canvas-Aktion erstellen, bereitstellen und testen
Web-App mit Canvas-Antworten aktualisieren
Verschiedene Methoden zur Optimierung deiner Aktion anwenden, z. B. sendTextQuery() und setCanvasState()
Fehler in der Aktion beheben

Weitere Informationen

In den folgenden Ressourcen erfahren Sie mehr über Interactive Canvas:

Dokumentation zum interaktiven Canvas: Die offizielle Dokumentation zu Actions on Google für Interactive Canvas
Interaktives Canvas-Beispiel: Der Code für ein einfaches Interaktives Canvas-Spiel, mit dem Sie ein Dreieck drehen und seine Farben ändern können.
Spieleportal: Die Richtlinien zum Erstellen von Spielen mit Google Assistant.

Feedback-Umfrage

Bevor Sie uns verlassen, möchten wir Sie bitten, an einer kurzen Umfrage zu Ihren Erfahrungen teilzunehmen.