回调

您可以在 Interactive Canvas Action 中实现以下回调:

onUpdate()

onUpdate() 回调将数据从您的 webhook 传递到您的 Web 应用,以适当地更新 Web 应用。您只能将此回调与 Interactive Canvas 开发的服务器端执行方式模型结合使用。

如需详细了解 onUpdate(),请参阅传递数据以更新 Web 应用

onTtsMark()

在文字转语音 (TTS) 期间,向用户读出响应的语音合成标记语言 (SSML) 中包含的自定义 <mark> 标记时,系统会调用 onTtsMark() 回调。您可以在服务器端和客户端执行方式开发模型中使用 onTtsMark()

在以下代码段中,onTtsMark() 会将 Web 应用的动画与相应的 TTS 输出同步。当 Action 对用户说“Sorry, you missing”时,Web 应用会读出正确的单词并向用户显示相应字母。

在以下示例中,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() 函数,该函数会更新 Web 应用:

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

当 Interactive Canvas Action 中的输入状态发生更改时,onInputStatusChanged() 回调会通知您。输入状态的变化指明了麦克风何时打开和关闭,或者 Google 助理何时处理查询。以下事件可能会导致输入状态发生变化:

  • 与您的 Action 对话的用户
  • 用户在 Android Google 搜索应用 (AGSA) 中输入文本
  • 使用 sendTextQuery() API 向 Action 发送文本查询的 Web 应用
  • “写入住宅存储空间和其他 Google 助理事件”操作

此回调的主要用例是将您的 Action 与用户的语音互动进行同步。例如,如果用户正在玩 Interactive Canvas 游戏并打开麦克风,您可以在用户讲话时暂停游戏。您也可以等到麦克风打开时再向 Google 助理发送文本查询,以确保 Google 助理收到该查询。

此 API 会报告以下状态:

  • LISTENING - 表示麦克风已打开。
  • IDLE - 表示麦克风已关闭。
  • PROCESSING - 表示 Google 助理当前正在执行查询,并且麦克风已关闭。

每当输入状态发生变化时,该 API 都会向您的 Action 报告输入状态。

虽然状态之间可以发生任何转换,但以下流程很常见:

  • IDLE>LISTENING>PROCESSING>IDLE - 用户说出查询,查询处理完毕,然后麦克风关闭。
  • IDLE>PROCESSING>IDLE - Web 应用使用 sendTextQuery() API 向 Action 发送文本查询。
  • IDLE>LISTENING>IDLE - 用户打开麦克风,但未说出查询。

如需在您的 Action 中使用此功能,请将 onInputStatusChanged() 添加到您的 Web 应用代码中,如以下代码段所示:

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

onInputStatusChanged() 回调会传回单个枚举参数 inputStatus。您可以检查此值,以了解当前输入状态。inputStatus 可以是 LISTENINGPROCESSINGIDLE

接下来,将 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);
 }
}