Weiter mit der clientseitigen oder serverseitigen Auftragsausführung

Nachdem Sie nun mit den Grundlagen vertraut sind, können Sie Ihre Aktion mit Canvas-spezifischen Methoden optimieren und anpassen. Sie können Ihre Aktion mit dem Client-Auftragsausführungsmodell oder dem serverseitigen Auftragsausführungsmodell entwickeln, wenn Sie Ihr Actions-Projekt erstellen. Weitere Informationen zu diesen Optionen finden Sie unter Interaktiven Canvas aktivieren.

Wenn Sie die Option für das Clientausführungsmodell auswählen, können Sie Folgendes in Ihrer Aktion verwenden:

Wenn Sie die Option für das Serverausführungsmodell auswählen, können Sie Folgendes in Ihrer Aktion verwenden:

Die Verwendung einiger Interactive Canvas APIs mit einem bestimmten Auftragsausführungsmodell wird nicht empfohlen. In der folgenden Tabelle sind die APIs aufgeführt, die aktiviert werden, wenn Sie die Option für die Client-Auftragsausführung auswählen, und ob diese APIs für jedes Modell empfohlen oder nicht empfohlen werden:

API-Name Unterstützt im Serverausführungsmodell? Unterstützt im Client-Auftragsausführungsmodell?
sendTextQuery() Ja Unterstützt, aber nicht empfohlen (weitere Informationen siehe sendtextQuery())
outputTts() Ja Ja
triggerScene() Nein Ja
createIntentHandler(), expect(), clearExpectations(), prompt() Nein Ja
createNumberSlot(),createTextSlot, createConfirmationSlot, createOptionsSlot() Nein Ja
setHomeParam(), getHomeParam(), setUserParam(), getUserParam() Nein Ja

In den folgenden Abschnitten wird erläutert, wie Sie APIs für die clientseitigen und serverseitigen Auftragsausführungsmodelle in Ihrer interaktiven Canvas-Aktion implementieren.

Mit clientseitiger Auftragsausführung erstellen

Sie können die folgenden Interactive Canvas APIs in die Logik Ihrer Webanwendung einbinden:

outputTts()

Mit dieser API können Sie die Sprachausgabe von einem Gerät aus ausgeben, ohne eine statische Aufforderung von Actions Builder zu senden oder einen Webhook aufzurufen. Wenn keine serverseitige Logik erforderlich ist, die mit der TTS verknüpft ist, können Sie outputTts() clientseitig verwenden, um eine Fahrt zu Ihrem Server zu überspringen und Ihren Nutzern eine schnellere Antwort zu liefern.

Clientseitige outputTts() können die serverseitige Sprachausgabe unterbrechen oder abbrechen. Sie können eine Unterbrechung der serverseitigen Sprachausgabe vermeiden, indem Sie die folgenden Vorsichtsmaßnahmen ergreifen:

  • Vermeide es, outputTts() zu Beginn der Sitzung aufzurufen. Verwende stattdessen in der ersten Unterhaltungsrunde deiner Aktion die serverseitige Sprachausgabe.
  • Rufen Sie outputTts() nicht hintereinander auf, ohne dass der Nutzer dazwischen aktiv ist.

Das folgende Snippet zeigt, wie outputTts() zur Ausgabe der Sprachausgabe auf Clientseite verwendet wird:

interactiveCanvas.outputTts(
      '<speak>This is an example response.</speak>', true);

Sie können auch outputTts() mit onTtsMark() verwenden, um SSML-Markierungen in der Textsequenz zu platzieren. Mit onTtsMark() wird die Animation oder der Spielstatus Ihrer Webanwendung an bestimmten Punkten eines SSML-TTS-Strings synchronisiert, wie im folgenden Snippet gezeigt:

interactiveCanvas.outputTts(
      '<speak>Speak as <mark name="number" /> number <break time="700ms"/>' +
      '<say-as interpret-as="cardinal">12345</say-as> <break time="300ms"/> ' +
      'Speak as <mark name="digits" /> digits <break time="700ms"/>' +
      '<say-as interpret-as="characters">12345</say-as></speak>', true);

Im vorherigen Beispiel werden die beiden Markierungen zur Anpassung Ihrer Antwort mit der Sprachausgabe an die Web-App gesendet.

Intent-Auftragsausführung auf dem Client verarbeiten

Im Serverausführungsmodell für Interactive Canvas müssen alle Intents von einem Webhook verarbeitet werden. Dadurch erhöht sich die Latenz Ihrer Aktion. Anstatt einen Webhook aufzurufen, können Sie die Auftragsausführung in Ihrer Webanwendung übernehmen.

Zur clientseitigen Verarbeitung von Intents können Sie die folgenden APIs verwenden:

  • createIntentHandler(): Eine Methode, mit der Sie im Code Ihrer Webanwendung Intent-Handler für benutzerdefinierte Intents definieren können, die in Actions Builder definiert werden.
  • expect(): Eine Methode, mit der der Intent-Handler aktiviert/registriert wird, damit ein Nutzer den Intent zuordnen kann.
  • clearExpectations(): Eine Methode, die die Erwartungen für alle derzeit aktivierten Intents löscht, damit die Intents nicht zugeordnet werden können, selbst wenn ein Nutzer eine Äußerung sagt, die dem Intent entspricht.
  • deleteHandler(): Eine Methode, mit der einzelne Intent-Handler deaktiviert werden, sodass diese Intents nicht zugeordnet werden können.

Mit diesen APIs können Sie Intents für verschiedene Status Ihrer interaktiven Canvas-Aktion selektiv aktivieren oder deaktivieren. Sie müssen expect() für Intent-Handler verwenden, um diese Intents zu aktivieren.

Intent-Handler aktivieren

Das Aktivieren eines Intent-Handlers erfolgt in zwei Schritten. Zuerst müssen Sie den Intent in Actions Builder definieren. Als Nächstes müssen Sie expect() für den Intent-Handler aufrufen, um den Intent zuordnen zu können.

So konfigurieren und aktivieren Sie einen Intent-Handler auf Clientseite:

  1. Öffnen Sie Ihr Projekt in der Actions Console und fügen Sie einen benutzerdefinierten Intent hinzu.
  2. Wählen Sie für Is this a global intent? (Ist dies ein globaler Intent?) Yes (Ja) aus.

  3. Konfigurieren Sie den Intent und klicken Sie auf Save (Speichern).

  4. Definieren Sie den Handler für den Intent in der Logik Ihrer Webanwendung, wie im folgenden Snippet gezeigt:

    /**
    * Define handler for intent.
    */
    const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
      matchedIntent => {
        console.log("Intent match handler to reserve a table was triggered!");
      });
    
    /**
    * Define handler for intent with an argument.
    */
    const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
      matchedIntent => {
        const numberOfPeople = matchedIntent.getIntentArg('numberOfPeople');
        console.log(`Intent match handler to reserve a table for ${number of people} was triggered!`);
      });
    
  5. Rufen Sie die Methode expect() auf, um den Intent-Handler zu registrieren, wie im folgenden Snippet gezeigt:

    /**
    * Define handler for intent and expect() it.
    */
    const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
      matchedIntent => {
        console.log("Intent match handler to reserve a table was triggered!");
      });
    var handler = interactiveCanvas.expect(bookTableIntent);
    

Intent-Handler deaktivieren

Nachdem Sie einen Intent-Handler definiert haben, können Sie den Intent nach Bedarf für Ihre Aktion aktivieren oder deaktivieren. Wenn Sie expect() aufrufen, um einen Intent zu aktivieren, wird ein Objekt mit der Methode deleteHandler() zurückgegeben, mit der Sie den neu erstellten Handler deaktivieren können. Die Definition des Intent-Handlers bleibt auch dann bestehen, wenn der Intent derzeit nicht aktiv ist. Sie können ihn also bei Bedarf wieder aktivieren.

Um einen Intent-Handler zu deaktivieren, rufen Sie deleteHandler() für den Intent-Handler auf, wie im folgenden Snippet gezeigt:

    /**
    * Define handler for intent and expect() it.
    */
    const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
      matchedIntent => {
        console.log("Intent match handler to reserve a table was triggered!");
      });
    var handler = interactiveCanvas.expect(bookTableIntent);
    
    // Delete the handler for `bookTableIntent`.
    handler.deleteHandler();
    

Sie können expect() aufrufen, um einen deaktivierten Intent-Handler wieder hinzuzufügen, wie im folgenden Snippet gezeigt:

    // Re-add the `bookTableIntent` handler.
    handler = interactiveCanvas.expect(bookTableIntent);

Wenn Sie Intents im Bulk-Verfahren deaktivieren möchten, können Sie die Methode clearExpectations() verwenden, mit der alle derzeit aktivierten Intents deaktiviert werden. Das folgende Snippet zeigt, wie die Erwartungen für alle Intent-Handler gelöscht werden:

interactiveCanvas.clearExpectations();

Slot-Füllung auf dem Client handhaben

Anstatt einer Szene in Actions Builder die Slot-Füllung hinzuzufügen, können Sie die Slot-Füllung direkt in Ihrer Webanwendung vornehmen.

Zur Verarbeitung der Slot-Füllung auf Clientseite müssen Sie zuerst einen Slot mit einer der folgenden APIs erstellen:

  • createNumberSlot(callback, hints): Eine Methode, mit der Sie ein Nummernfeld im Code Ihrer Webanwendung definieren können. Wird verwendet, um den Nutzer zur Eingabe einer Nummer aufzufordern.
  • createTextSlot(callback, hints): Eine Methode, mit der Sie eine Textfläche im Code Ihrer Webanwendung definieren können. Wird verwendet, um den Nutzer zur Eingabe eines Wortes aufzufordern.
  • createConfirmationSlot(callback, hints): Eine Methode, mit der Sie eine Bestätigungsfläche im Code Ihrer Webanwendung definieren können. Wird verwendet, um den Nutzer zur Bestätigung aufzufordern (Ja/Nein).
  • createOptionsSlot(options, callback, hints): Eine Methode, mit der Sie einen Optionsslot im Code Ihrer Webanwendung definieren können. Wird verwendet, um den Nutzer zur Auswahl aus einer Liste vordefinierter Optionen aufzufordern.

Wenn Sie einen Slot erstellen, können Sie optional triggerHints definieren. Dies sind Keywords, die das NLU-System (Natural Language Understanding) für Ihre Aktion verbessern. Diese Keywords sollten kurze Wörter sein, die der Nutzer beim Füllen einer Anzeigenfläche aussprechen könnte. Das Schlüsselwort triggerHints für einen Zahlenslot könnte beispielsweise years sein. Wenn ein Nutzer in der Unterhaltung auf eine Frage zu seinem Alter mit der Antwort "Ich bin dreißig Jahre alt" antwortet, erkennt deine Aktion eher, dass der Nutzer die Anzeigenfläche richtig füllt.

Nachdem Sie einen Slot erstellt haben, können Sie den Nutzer mit der prompt API zur Eingabe eines Slots auffordern:

  • prompt(tts, slot): Eine Methode, bei der die Sprachausgabe an den Nutzer ausgegeben wird, um ihn zur Eingabe eines erwarteten Slots aufzufordern.

Durch den Aufruf von prompt() wird ein Versprechen mit dem Status und Wert des gefüllten Slots zurückgegeben.

Slotnummer erstellen

Mit einem Zahlenslot können Sie einen Nutzer während der Unterhaltung zur Eingabe einer Nummer auffordern. Weitere Informationen zur Slot-Füllung finden Sie in der Actions Builder-Dokumentation im Abschnitt Slot-Füllung.

So fordern Sie den Nutzer auf der Clientseite auf, ein Zahlenfeld zu füllen:

  1. Rufen Sie die Methode createNumberSlot() auf, um ein Nummernfeld in Ihrer Webanwendungslogik zu erstellen:

    /**
     * Create number slot.
     */
    const triggerHints = { associatedWords: ['guess number', 'number'] };
    const slot = interactiveCanvas.createNumberSlot(
      number => {
        console.log(`Number guessed: ${number}.`);
      }, triggerHints);
    
    
  2. Rufen Sie die Methode prompt() auf, um den Nutzer zur Eingabe des Slots aufzufordern und den Slotwert aus dem zurückgegebenen Versprechen zu verarbeiten, wie im folgenden Snippet gezeigt:

    const promptPromise = interactiveCanvas.prompt(
      { text: 'What number am I thinking of between 1 and 10?' }, slot);
    
    promptPromise.then(
      answer => {
        if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
          // answer === {value: 5, status: ANSWERED}
          // Do something with answer.value
        } else {
          console.error('Promise returned unsuccessful status ' + answer.status);
        }
      });
    

Textbereich erstellen

Mit einem Textfeld können Sie einen Nutzer während der Unterhaltung zur Eingabe eines Wortes auffordern. Weitere Informationen zur Slot-Füllung finden Sie in der Actions Builder-Dokumentation im Abschnitt Slot-Füllung.

So fordern Sie den Nutzer auf der Clientseite auf, eine Anzeigenfläche auszufüllen:

  1. Rufen Sie die Methode createTextSlot() auf, um eine Textfläche in der Logik Ihrer Webanwendung zu erstellen:

    /**
     * Create text slot.
     */
    const triggerHints = { associatedWords: ['favorite color', 'color'] };
    const slot = interactiveCanvas.createTextSlot(
      text => {
        console.log(`Favorite color: ${text}.`);
      }, triggerHints);
    
    
  2. Rufen Sie die Methode prompt() auf, um den Nutzer zur Eingabe des Slots aufzufordern und den Slotwert aus dem zurückgegebenen Versprechen zu verarbeiten, wie im folgenden Snippet gezeigt:

    const promptPromise = interactiveCanvas.prompt(
      { text: 'What is your favorite color?' }, slot);
    
    promptPromise.then(
      answer => {
        if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
          // answer === {value: "red", status: ANSWERED}
          // Do something with answer.value
        } else {
          console.error('Promise returned unsuccessful status ' + answer.status);
        }
      });
    

Bestätigungsslot erstellen

In einem Bestätigungsslot können Sie einen Nutzer zur Bestätigung auffordern. Der Nutzer kann dann mit „Ja“ oder „Nein“ antworten, um den Slot zu füllen. Weitere Informationen zur Slot-Füllung finden Sie in der Actions Builder-Dokumentation im Abschnitt Slot-Füllung.

Wenn Sie den Nutzer auffordern möchten, einen Bestätigungsslot auf Clientseite auszufüllen, gehen Sie so vor:

  1. Rufen Sie die Methode createConfirmationSlot() auf, um einen Bestätigungsslot in der Logik Ihrer Webanwendung zu erstellen:

    /**
     * Create confirmation slot (boolean).
     */
    const triggerHints = { associatedWords: ['user confirmation', 'confirmation'] };
    const slot = interactiveCanvas.createConfirmationSlot(
      yesOrNo => {
        console.log(`Confirmation: ${yesOrNo}`);
      }, triggerHints);
    
    
  2. Rufen Sie die Methode prompt() auf, um den Nutzer zur Eingabe des Slots aufzufordern und den Slotwert aus dem zurückgegebenen Versprechen zu verarbeiten, wie im folgenden Snippet gezeigt:

    const promptPromise = interactiveCanvas.prompt(
      { text: 'Do you agree to the Terms of Service?' }, slot);
    
    promptPromise.then(
      answer => {
        if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
          // answer === {value: true, status: ANSWERED}
          // Do something with answer.value
        } else {
          console.error('Promise returned unsuccessful status ' + answer.status);
        }
      });
    

Optionsslot erstellen

Mit einem Optionsslot können Sie den Nutzer auffordern, aus einer Liste vordefinierter Optionen auszuwählen. Weitere Informationen zur Slot-Füllung finden Sie in der Actions Builder-Dokumentation im Abschnitt Slot-Füllung.

Gehen Sie so vor, um den Nutzer aufzufordern, eine Optionsfläche auf der Clientseite auszufüllen:

  1. Rufen Sie die Methode createOptionsSlot() auf, um einen Optionsslot in Ihrer Webanwendungslogik zu erstellen:

    /**
     * Create options slot (list selection).
     */
    const triggerHints = { associatedWords: ['select fruit', 'choose fruit'] };
    // Define selectable options
    const options = [{
      key: 'apple',
      synonyms: ['apple', 'large apple', 'gala apple'],
    }, {
      key: 'banana',
      synonyms: ['banana', 'green banana', 'plantain'],
    }];
    const slot = interactiveCanvas.createOptionsSlot(
      options,
      selectedOption => {
        console.log(`You have selected ${selectedOption} as your fruit.`);
      }, triggerHints);
    
    
  2. Rufen Sie die Methode prompt() auf, um den Nutzer zur Eingabe des Slots aufzufordern und den Slotwert aus dem zurückgegebenen Versprechen zu verarbeiten, wie im folgenden Snippet gezeigt:

    const promptPromise = interactiveCanvas.prompt(
      { text: 'Would you like a banana or an apple?' }, slot);
    
    promptPromise.then(
      answer => {
        if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
          // answer === {value: 'apple', status: ANSWERED}
          // Do something with answer.value
        } else {
          console.error('Promise returned unsuccessful status ' + answer.status);
        }
      });
    

triggerScene()

Mit der triggerScene() API können Sie von der clientseitigen Auftragsausführung zu einer anderen Szene in Ihrer interaktiven Canvas-Aktion wechseln. Mit triggerScene() können Sie auch von der clientseitigen zur serverseitigen Auftragsausführung wechseln, wenn der Nutzer auf eine Systemszene in Actions Builder zugreifen muss, für die ein Webhook erforderlich ist. Sie können beispielsweise triggerScene() aufrufen, wenn ein Nutzer sein Konto verknüpfen oder Benachrichtigungen erhalten muss. Anschließend können Sie mit einer Canvas-Aufforderung von dieser Szene zur clientseitigen Auftragsausführung zurückkehren.

Das folgende Snippet zeigt, wie triggerScene() in deine Aktion implementiert wird:

interactiveCanvas.triggerScene('SceneName').then((status) => {
  console.log("sent the request to trigger scene.");
}).catch(e => {
  console.log("Failed to trigger a scene.");
})

Privat- und Nutzerspeicher auf dem Client

Anstatt einen Webhook zu verwenden, um Speicherwerte für Start und Nutzer abzurufen und festzulegen, können Sie clientseitige APIs aufrufen, um den Home- und Nutzerspeicher in Ihrer Webanwendung zu verwalten. Ihre Webanwendung kann diese gespeicherten Werte dann über mehrere Sitzungen hinweg verwenden (z. B. in Aufforderungen und Bedingungen) und bei Bedarf auf Werte für einen bestimmten Haushalt oder Nutzer zugreifen. Die Verwendung dieser APIs kann die Latenz in Ihrer interaktiven Canvas-Aktion reduzieren, da Sie keinen Webhook mehr aufrufen müssen, um Speicherwerte abzurufen und festzulegen.

Der Startseiten- und Nutzerspeicher in der Webanwendung folgt denselben allgemeinen Prinzipien wie der Speicher im Webhook. Weitere Informationen zum Privat- und Nutzerspeicherplatz finden Sie in der Dokumentation zu Speicher und Nutzerspeicher.

Clientseitiger Speicher für zu Hause

Mit dem Speicher für Zuhause können Sie Werte für Haushaltsnutzer basierend auf der Grafik des Zuhauses speichern. Dieser wird von allen Sitzungen im Haushalt gemeinsam genutzt. Wenn ein Nutzer beispielsweise ein Interactive Canvas-Spiel in einem Haushalt spielt, kann die Punktzahl des Spiels im Home Storage gespeichert werden. Andere Haushaltsmitglieder können das Spiel dann mit der gespeicherten Punktzahl weiterspielen.

So aktivierst du, dass deine Aktion das Speichern im Zuhause unterstützt:

  1. Gehen Sie in der Actions Console zu Deploy > Directory information > Additional Information (Bereitstellen > Verzeichnisinformationen > Zusätzliche Informationen).
  2. Klicke das Kästchen Ja unter Verwendet deine Aktionen den Speicherplatz im Zuhause? an.

Wenn Sie einen Wert in den Basisspeicher Ihrer Webanwendung schreiben möchten, rufen Sie die Methode setHomeParam() auf, wie im folgenden Snippet gezeigt:

interactiveCanvas.setHomeParam('familySize',  10).then(
      result => {
        console.log('Set home param success');
      },
      fail => {
        console.error(err);
      });

Wenn Sie einen Wert aus dem Home Storage in Ihrer Webanwendung lesen möchten, rufen Sie die Methode getHomeParam() auf, wie im folgenden Snippet gezeigt:

interactiveCanvas.getHomeParam('familySize').then(
      value => {
        console.log(JSON.stringify(result));
      },
      err => {
        console.error(err);
      }
  );

Wenn Sie den gesamten vorhandenen Speicher löschen möchten, rufen Sie die Methode resetHomeParam() auf, wie im folgenden Snippet gezeigt:

interactiveCanvas.resetHomeParam();

Clientseitiger Nutzerspeicher

Mit dem Nutzerspeicher können Sie Parameterwerte für einen bestimmten, bestätigten Nutzer über mehrere Sitzungen hinweg speichern. Wenn ein Nutzer beispielsweise ein Spiel spielt, kann der Punktestand des Spiels für diesen Nutzer gespeichert werden. In einer nachfolgenden Spielsitzung kann der Nutzer das Spiel mit derselben Punktzahl weiterspielen.

Wenn Sie einen Wert in den Nutzerspeicher Ihrer Webanwendung schreiben möchten, rufen Sie die Methode setUserParam() auf, wie im folgenden Snippet gezeigt:

interactiveCanvas.setUserParam('color',  'blue').then(
      result => {
        console.log('Set user param success');
      },
      err => {
        console.error(err);
      });

Wenn Sie einen Wert aus dem Nutzerspeicher Ihrer Webanwendung lesen möchten, rufen Sie die Methode getUserParam() auf, wie im folgenden Snippet gezeigt:

interactiveCanvas.getUserParam('color').then(
      value => {
        console.log(JSON.stringify(result));
      },
      err => {
        console.error(err);
      }
  );

Wenn Sie den gesamten vorhandenen Nutzerspeicherplatz löschen möchten, rufen Sie die Methode resetUserParam() auf, wie im folgenden Snippet gezeigt:

interactiveCanvas.resetUserParam();

setCanvasState()

Mit der Methode setCanvasState() können Sie Statusdaten von Ihrer Interactive Canvas-Webanwendung an die Auftragsausführung senden und Assistant wird darüber informiert, dass der Status der Webanwendung aktualisiert wurde. Die Webanwendung sendet ihren aktualisierten Status als JSON-Objekt.

Durch das Aufrufen von setCanvasState() wird kein Intent aufgerufen. Wenn nach dem Aufruf von setCanvasState() sendTextQuery() aufgerufen wird oder die Nutzerabfrage mit einem Intent in der Unterhaltung übereinstimmt, sind die Daten, die in der vorherigen Unterhaltungsrunde mit setCanvasState() festgelegt wurden, in nachfolgenden Unterhaltungsrunden verfügbar.

Im folgenden Snippet verwendet die Web-App setCanvasState(), um die Canvas-Statusdaten festzulegen:

JavaScript

this.action.canvas.setCanvasState({ score: 150 })
    

Canvas-Status über Webhook referenzieren

Sie können in Ihrem Auftragsausführungscode auf gespeicherte Canvas-Statuswerte verweisen. Verwenden Sie die Syntax conv.context.canvas.state.KEY, um auf den Wert zu verweisen, wobei KEY der Schlüssel ist, der beim Festlegen des Canvas-Statuswerts angegeben wurde.

Wenn Sie beispielsweise zuvor einen Highscore-Wert für ein Spiel im Canvas-Status als Parameter score gespeichert haben, verweisen Sie auf diesen Wert mit conv.context.canvas.state.score, um auf diesen Wert in der Auftragsausführung zuzugreifen:

Node.js

app.handle('webhook-name', conv => {
    console.log(conv.context.canvas.state.score);
})
    

Canvas-Status in Prompts verweisen

Sie können in einem Prompt auf gespeicherte Canvas-Statuswerte verweisen. Verwenden Sie die Syntax $canvas.state.KEY, um auf den Wert zu verweisen, wobei KEY der Schlüssel ist, der beim Festlegen des Canvas-Statuswerts angegeben wurde.

Wenn Sie beispielsweise zuvor einen Highscore-Wert für ein Spiel im Canvas-Status als Parameter score gespeichert haben, verweisen Sie auf diesen Wert mit $canvas.state.score, um in einer Eingabeaufforderung auf diesen Wert zuzugreifen:

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Your high score is $canvas.state.score."
      }]
    }
  }]
}
    

Canvas-Status innerhalb von Bedingungen referenzieren

Sie können auch auf gespeicherte Canvas-Statuswerte in Bedingungen verweisen. Verwenden Sie die Syntax canvas.state.KEY, um auf den Wert zu verweisen, wobei KEY der Schlüssel ist, der beim Festlegen des Canvas-Statuswerts angegeben wurde.

Wenn Sie beispielsweise zuvor einen Highscore-Wert für ein Spiel im Canvas-Status als Parameter score gespeichert haben und ihn mit dem Wert 999 in einer Bedingung vergleichen möchten, können Sie mit canvas.state.score auf den gespeicherten Wert in Ihrer Bedingung verweisen. Der Bedingungsausdruck sieht so aus:

Bedingungssyntax

canvas.state.score >= 999
    

sendTextQuery()

Die Methode sendTextQuery() sendet Textabfragen an die Konversationsaktion, um einen Intent programmatisch zuzuordnen. In diesem Beispiel wird sendTextQuery() verwendet, um das sich drehende Spiel neu zu starten, wenn der Nutzer auf eine Schaltfläche klickt. Wenn der Nutzer auf die Schaltfläche „Spiel neu starten“ klickt, sendet sendTextQuery() eine Textabfrage, die dem Intent Restart game entspricht und ein Promise zurückgibt. Dieses Versprechen führt zu SUCCESS, wenn der Intent ausgelöst wird, und zu BLOCKED, wenn nicht. Das folgende Snippet ordnet den Intent zu und verarbeitet die Erfolgs- und Fehlerfälle des Versprechens:

JavaScript

…
/**
* Handle game restarts
*/
async handleRestartGame() {
    console.log(`Request in flight`);
    this.button.texture = this.button.textureButtonDisabled;
    this.sprite.spin = false;
    const res = await this.action.canvas.sendTextQuery('Restart game');
    if (res.toUpperCase() !== 'SUCCESS') {
        console.log(`Request in flight: ${res}`);
        return;
    }
    console.log(`Request in flight: ${res}`);
    this.button.texture = this.button.textureButtonDisabled;
    this.sprite.spin = false;
}
…
    

Wenn das Promise SUCCESS ergibt, sendet der Webhook-Handler Restart game eine Canvas-Antwort an Ihre Webanwendung:

JavaScript

…
app.handle('restart', conv => {
  conv.add(new Canvas({
    data: {
      command: 'RESTART_GAME'
    }
  }));
});
…
    

Diese Canvas-Antwort löst den onUpdate()-Callback aus, der den Code im folgenden RESTART_GAME-Code-Snippet ausführt:

JavaScript

…
RESTART_GAME: (data) => {
    this.scene.button.texture = this.scene.button.textureButton;
    this.scene.sprite.spin = true;
    this.scene.sprite.tint = 0x00FF00; // green
    this.scene.sprite.rotation = 0;
},
…
    

Mit serverseitiger Auftragsausführung erstellen

Sie können die folgenden Interactive Canvas APIs in Ihrem Webhook implementieren:

Vollbildmodus aktivieren

Standardmäßig enthalten Interactive Canvas-Webanwendungen oben auf dem Bildschirm einen Header mit dem Namen Ihrer Aktion. Mit enableFullScreen kannst du den Header entfernen und durch einen temporären Toast ersetzen, der auf dem Ladebildschirm angezeigt wird. So kann der Nutzer während der Interaktion mit deiner Aktion im Vollbildmodus arbeiten. Die Toast-Meldung enthält den Anzeigenamen der Aktion, den Namen des Entwicklers und eine Anleitung zum Beenden der Aktion. Die Toast-Farbe ändert sich je nachdem, welches Design der Nutzer auf seinem Gerät auswählt.

Abbildung 1. Eine Toast-Nachricht auf dem Ladebildschirm für eine Aktion.

Wenn ein Nutzer häufig mit deiner Aktion interagiert, wird die Meldung vorübergehend nicht mehr auf dem Ladebildschirm angezeigt. Wenn der Nutzer eine Zeit lang nicht mit Ihrer Aktion interagiert, wird die Toast-Meldung erneut angezeigt, wenn er die Aktion startet.

Sie können den Vollbildmodus in Ihrem Webhook oder in einer statischen Aufforderung in Actions Builder aktivieren.

So aktivieren Sie den Vollbildmodus in Ihrem Webhook:

  1. Setzen Sie das Feld enableFullScreen in der ersten canvas-Antwort, die vom Webhook in einer Sitzung zurückgegeben wird, auf true. Das folgende Snippet ist eine Beispielimplementierung mit der Node.js-Clientbibliothek:

     const { conversation, Canvas } = require('@assistant/conversation');
     const functions = require('firebase-functions');
    
     const app = conversation();
    
     app.handle('invocation_fullscreen', conv => {
       conv.add(new Canvas(
         {
           url: 'https://example-url.com',
           enableFullScreen: true
         }));
     });
    
     exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
    

So aktivieren Sie den Vollbildmodus in einer statischen Aufforderung in Actions Builder:

  1. Öffnen Sie Ihr Projekt in der Actions Console.
  2. Klicken Sie in der Navigationsleiste auf Develop und öffnen Sie die Eingabeaufforderung, die die erste canvas-Antwort enthält.
  3. Legen Sie enable_full_screen auf true fest, wie im folgenden Snippet gezeigt:

     {
      "candidates": [
        {
          "canvas": {
            "url": "https://example-url.com",
            "enable_full_screen": true
          }
        }
      ]
    }
    

continueTtsDuringTouch

Wenn ein Nutzer während einer interaktiven Canvas-Aktion auf den Bildschirm tippt, wird die Sprachausgabe standardmäßig beendet. Du kannst festlegen, dass die Sprachausgabe fortgesetzt wird, wenn Nutzer continueTtsDuringTouch auf den Bildschirm tippen. Dieses Verhalten kann nicht in derselben Sitzung ein- und ausgeschaltet werden.

Sie können dieses Verhalten in Ihrem Webhook oder in einer statischen Eingabeaufforderung in Actions Builder implementieren.

Damit die Sprachausgabe fortgesetzt wird, nachdem der Nutzer auf den Bildschirm in Ihrem Webhook getippt hat, gehen Sie so vor:

  • Setzen Sie das Feld continueTtsDuringTouch in der ersten canvas-Antwort, die vom Webhook in einer Sitzung zurückgegeben wird, auf true. Das folgende Snippet ist eine Beispielimplementierung mit der Node.js-Clientbibliothek:

    const { conversation, Canvas } = require('@assisant/conversation');
    const functions = require('firebase-functions');
    
    const app = conversation();
    
    app.handle('intent-name', conv => {
      conv.add(new Canvas(
        {
          url: 'https://example-url.com',
          continueTtsDuringTouch: true
        }));
    });
    
    exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
    

Damit die Sprachausgabe fortgesetzt wird, nachdem der Nutzer in einer statischen Aufforderung in Actions Builder auf den Bildschirm getippt hat, gehen Sie so vor:

  1. Öffnen Sie Ihr Projekt in der Actions Console.
  2. Klicken Sie in der Navigationsleiste auf Develop und öffnen Sie die Eingabeaufforderung, die die erste canvas-Antwort enthält.
  3. Legen Sie continue_tts_during_touch auf true fest, wie im folgenden Snippet gezeigt:

      {
       "candidates": [
         {
           "canvas": {
             "url": "https://example-url.com",
             "continue_tts_during_touch": true
           }
         }
       ]
     }