回调

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

onUpdate()

onUpdate() 回调会将数据从 webhook 传递到 Web 应用以进行更新 Web 应用。您只能将此回调函数用于服务器端 Interactive Canvas 开发的 fulfillment 模型。

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

onTtsMark()

当自定义 <mark> 代码包含在onTtsMark() 语音合成标记语言 (SSML) 。您可以 在服务器端和客户端执行方式开发过程中都使用 onTtsMark() 模型。

在以下代码段中，onTtsMark() 会同步 Web 应用的动画 替换为相应的 TTS 输出。当 Action 向用户显示“Sorry, “你输了”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()

onInputStatusChanged() 回调会在输入状态发生变化时通知您 。输入状态变化指示 麦克风打开和关闭，或是在 Google 助理处理询问时。通过 以下事件可能会导致输入状态发生变化：

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

此回调的主要用例是将 Action 与 用户的语音互动。例如，如果用户正在玩互动式广告 画布游戏，并打开麦克风，您可以在用户暂停游戏时暂停游戏 。您也可以等到麦克风打开后再向 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 可以是 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);
 }
}