コールバック

Interactive Canvas アクションでは、次のコールバックを実装できます。

`onUpdate()`

onUpdate() コールバックは、Webhook からウェブアプリにデータを渡し、ウェブアプリを適切に更新します。このコールバックは、Interactive Canvas 開発のサーバーサイドフルフィルメントモデルでのみ使用してください。

onUpdate() の詳細については、データを渡してウェブアプリを更新するをご覧ください。

`onTtsMark()`

onTtsMark() コールバックは、テキスト読み上げ（TTS）中にレスポンスの音声合成マークアップ言語（SSML）に含まれるカスタム <mark> タグがユーザーに読み上げられるときに呼び出されます。onTtsMark() は、サーバーサイドとクライアントサイドの両方のフルフィルメント開発モデルで使用できます。

次のスニペットで、onTtsMark() はウェブアプリのアニメーションを対応する TTS 出力と同期します。アクションがユーザーに「申し訳ありませんが、負けました」と応答すると、ウェブアプリは正しい単語をスペルアウトし、その文字をユーザーに表示します。

次の例では、ユーザーがゲームに負けたときのレスポンスに、Webhook ハンドラ revealWord でカスタムマークが含まれています。

JavaScript

…
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());
});
…

次のコードスニペットは、onTtsMark() コールバックを登録し、マークの名前を確認して、ウェブアプリを更新する revealCorrectWord() 関数を実行します。

JavaScript

…
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()`

onInputStatusChanged() コールバックは、Interactive Canvas アクションで入力ステータスが変更されると通知します。入力ステータスの変化は、マイクの開閉時間や、アシスタントがクエリを処理している時間を示します。次のイベントによって入力ステータスが変更される場合があります。

ユーザーがアクションに向かって話す
Android Google 検索アプリ（AGSA）でのテキスト入力
sendTextQuery() API を使用してテキストクエリをアクションに送信するウェブアプリ
アクションがホームストレージやその他のアシスタントイベントに書き込む

このコールバックの主なユースケースは、アクションをユーザーの音声操作と同期することです。たとえば、インタラクティブキャンバスゲームをプレイしているユーザーがマイクを開いた場合、ユーザーが話している間にゲームを一時停止できます。マイクが開くまで待ってから、テキストクエリをアシスタントに送信し、確実に受信することもできます。

この API は、次のステータスを報告します。

LISTENING - マイクが開いていることを示します。
IDLE - マイクが閉じていることを示します。
PROCESSING - 現在アシスタントがクエリを実行しており、マイクが閉じていることを示します。

入力ステータスが変更されるたびに、API からアクションに入力ステータスが報告されます。

状態間の遷移は可能ですが、一般的なフローは次のとおりです。

IDLE>LISTENING>PROCESSING>IDLE - ユーザーがクエリを言うと、クエリが処理され、マイクが閉じます。
IDLE>PROCESSING>IDLE - ウェブアプリは sendTextQuery() API を使用してテキストクエリをアクションに送信します。
IDLE>LISTENING>IDLE - ユーザーがマイクを開きますが、クエリを言っていません。

アクションでこの機能を使用するには、次のスニペットに示すように、onInputStatusChanged() をウェブアプリコードに追加します。

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

onInputStatusChanged() コールバックは、単一の列挙型パラメータ inputStatus を返します。この値を確認すると、現在の入力ステータスを確認できます。inputStatus は LISTENING、PROCESSING、または IDLE です。

次に、onInputStatusChanged() を callbacks オブジェクトに追加して登録します。以下のスニペットをご覧ください。

 /**
  * 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);
 }
}