Callbacks

Sie können die folgenden Callbacks in Ihrer interaktiven Canvas-Aktion implementieren:

onUpdate()

Der onUpdate()-Callback übergibt Daten vom Webhook an die Webanwendung, um die Web-App entsprechend zu aktualisieren. Sie sollten diesen Callback nur mit dem serverseitigen Auftragsausführungsmodell der Interactive Canvas-Entwicklung verwenden.

Weitere Informationen zu onUpdate() finden Sie unter Daten zum Aktualisieren der Web-App übergeben.

onTtsMark()

Der onTtsMark()-Callback wird aufgerufen, wenn dem Nutzer während der Sprachausgabe benutzerdefinierte <mark>-Tags, die in der Speech Synthesis Markup Language (SSML) Ihrer Antwort enthalten sind, vorgelesen werden. Sie können onTtsMark() sowohl für die serverseitigen als auch die clientseitigen Entwicklungsmodelle für die Auftragsausführung verwenden.

In den folgenden Snippets synchronisiert onTtsMark() die Animation der Webanwendung mit der entsprechenden TTS-Ausgabe. Wenn die Aktion zum Nutzer „Entschuldigung, du hast verloren“ gesagt hat, schreibt die Webanwendung das richtige Wort aus und zeigt dem Nutzer die Buchstaben an.

Im folgenden Beispiel enthält der Webhook-Handler revealWord eine benutzerdefinierte Markierung in der Antwort an den Nutzer, wenn er das Spiel verloren hat:

…
app.handle('revealWord', conv => {
  conv.add(new Simple(`<speak>Sorry, you lost.<mark name="REVEAL_WORD"/> The word is ${conv.session.params.word}.</speak>`));
  conv.add(new Canvas());
});
…
    

Mit dem folgenden Code-Snippet wird dann der onTtsMark()-Callback registriert, der Name der Marke geprüft und die Funktion revealCorrectWord() ausgeführt, mit der die Webanwendung aktualisiert wird:

…
setCallbacks() {
    // declare Assistant Canvas Action callbacks
    const callbacks = {
        onTtsMark(markName) {
            if (markName === 'REVEAL_WORD') {
                // display the correct word to the user
                that.revealCorrectWord();
            }
        },
    }
    callbacks.onUpdate.bind(this);
}
…
    

onInputStatusChanged()

Der onInputStatusChanged()-Callback benachrichtigt Sie, wenn sich der Eingabestatus in Ihrer interaktiven Canvas-Aktion ändert. Änderungen des Eingangsstatus zeigen an, wenn das Mikrofon geöffnet und geschlossen wird oder wenn Assistant eine Anfrage verarbeitet. Die folgenden Ereignisse können dazu führen, dass sich der Eingabestatus ändert:

• Der Nutzer, der zu deiner Aktion spricht
• Der Nutzer, der Text in die Google App für Android (AGSA) eingibt
• Die Webanwendung, die die sendTextQuery() API verwendet, um eine Textabfrage an die Aktion zu senden
• Die Aktion, die in den Speicher für dein Zuhause geschrieben wird, und andere Assistant-Ereignisse

Der primäre Anwendungsfall für diesen Callback ist die Synchronisierung deiner Aktion mit den Sprachinteraktionen des Nutzers. Wenn ein Nutzer beispielsweise ein Interactive Canvas-Spiel spielt und das Mikrofon öffnet, können Sie das Spiel anhalten, während der Nutzer spricht. Sie können auch warten, bis das Mikrofon eingeschaltet ist, um eine Textanfrage an Assistant zu senden, um sicherzustellen, dass sie empfangen wird.

Diese API meldet die folgenden Status:

• LISTENING: Gibt an, dass das Mikrofon eingeschaltet ist.
• IDLE: Gibt an, dass das Mikrofon geschlossen ist.
• PROCESSING: Gibt an, dass Assistant gerade eine Abfrage ausführt und das Mikrofon geschlossen ist.

Die API meldet den Eingabestatus jedes Mal an Ihre Aktion, wenn sich der Status ändert.

Obwohl jeder Übergang zwischen den Zuständen möglich ist, sind die folgenden Abläufe üblich:

• IDLE>LISTENING>PROCESSING>IDLE: Der Nutzer sagt eine Abfrage, die Abfrage wird verarbeitet und das Mikrofon wird geschlossen.
• IDLE>PROCESSING>IDLE: Die Webanwendung verwendet die sendTextQuery() API, um eine Textabfrage an die Aktion zu senden.
• IDLE>LISTENING>IDLE: Der Nutzer öffnet das Mikrofon, sagt aber keine Anfrage.

Wenn Sie dieses Feature in Ihrer Aktion verwenden möchten, fügen Sie dem Code Ihrer Webanwendung onInputStatusChanged() hinzu, wie im folgenden Snippet gezeigt:

onInputStatusChanged(inputStatus) {
   console.log("The new input status is: ", inputStatus);
}

Der onInputStatusChanged()-Callback gibt einen einzelnen Enum-Parameter inputStatus zurück. Sie können diesen Wert überprüfen, um den aktuellen Eingabestatus zu sehen. inputStatus kann LISTENING, PROCESSING oder IDLE sein.

Fügen Sie als Nächstes dem callbacks-Objekt onInputStatusChanged() hinzu, um es zu registrieren, wie im folgenden Snippet gezeigt:

 /**
  * Register all callbacks used by the Interactive Canvas Action
  * executed during game creation time.
  */
 setCallbacks() {
   const that = this;
   // Declare the Interactive Canvas action callbacks.
   const callbacks = {
     onUpdate(data) {
       console.log('Received data', data);
     },
     onInputStatusChanged(inputStatus) {
       console.log("The new input status is: ", inputStatus);
     },
   };
   // Called by the Interactive Canvas web app once web app has loaded to
   // register callbacks.
   this.canvas.ready(callbacks);
 }
}