Interactive Canvas API 参考文档

Interactive Canvas API 是一个 JavaScript 库，可用于通过 Web 应用中的 interactiveCanvas 对象与对话型 Action 进行交互。

注意 ：interactiveCanvas 对象会附加到 window 对象。如果您使用前端框架来开发 Web 应用，则必须确保有权访问 window 以设置 API。

如需详细了解 Interactive Canvas，请参阅 Interactive Canvas 文档。

方法

警告：部分 Interactive Canvas API 目前为开发者预览版。您可以在模拟器中测试 API，但不要将使用这些功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用这些功能部署的操作在最终用户设备上将无法正常运行。

准备就绪

ready(callbacks) returns undefined

在加载完成后由 Interactive Canvas Web 应用调用以注册回调。

参数
callbacks	InteractiveCanvasCallbacks 一个包含方法回调的对象。

注意 ：页面加载后，您必须立即在 Web 应用中调用 ready API。否则，操作会关闭。

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

向对话操作发送文本查询。

参数
textQuery	string 要发送到对话操作的查询。
state	string 以下任一项： READY: 平台可以接受请求。 BLOCKED:有一个正在执行的查询，新查询将被舍弃。 UNKNOWN:无法确定当前的查询状态。

注意 ：textQuery 不得超过 640 个字符。

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

确定显示屏顶部标头的高度。

参数
height	number 高度（以像素为单位）。

outputTts

outputTts(text, openMic) returns undefined;

播放 SSML 文本。

参数
text	string 要播放的 SSML 支持字符串。
openMic	boolean TTS 播放完毕后是否打开麦克风。

createIntentHandler

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

createIntentHandler(intentId, callback) returns IntentHandler

为 NLU 自定义 intent 创建 intent 处理程序。

参数
intentId	string Actions Builder 中定义的 intent 名称。
callback	function(MatchedIntent) 当 intent 匹配时要执行的函数。
IntentHandler	object 可使用 expect() 注册的 intent 处理程序对象。

IntentHandler

表示 intent 处理程序的对象。可以使用 expect() 或 prompt() 进行注册。

MatchedIntent

包含匹配意图的数据的对象。

方法
getIntentArg(parameterName)	function(string) 用于获取匹配意图的意图参数的方法。

createNumberSlot

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

createNumberSlot(callback, hints?) returns Slot<number>

创建编号类型的槽。

参数
callback	function(FilledSlot) 当槽填充时要执行的函数。
hints	Hints 用户在填充槽时可能会说出的简短字词。hints 可帮助 NLU 系统确定要填充的槽位。
Slot	object 可以使用 prompt() 注册的槽对象。

createTextSlot

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

createTextSlot(callback, hints?) returns Slot<string>

创建字符串类型的槽。

参数
callback	function(FilledSlot) 当槽填充时要执行的函数。
hints	Hints 用户在填充槽时可能会说出的简短字词。hints 可帮助 NLU 系统确定要填充的槽位。
Slot	object 可以使用 prompt() 注册的槽对象。

createConfirmationSlot

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

createConfirmationSlot(callback, hints?) returns Slot<boolean>

创建一个布尔值类型的槽。

参数
callback	function(FilledSlot) 当槽填充时要执行的函数。
hints	Hints 用户在填充槽时可能会说出的简短字词。hints 可帮助 NLU 系统确定要填充的槽位。
Slot	object 可以使用 prompt() 注册的槽对象。

createOptionsSlot

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

createOptionsSlot(options, callback, hints?) returns Slot<string>

根据预定义的选项列表创建一个槽。

参数
options	array<Option> 当槽填充时要执行的函数。
callback	function(FilledSlot) 当槽填充时要执行的函数。
hints	Hints 用户在填充槽时可能会说出的简短字词。hints 可帮助 NLU 系统确定要填充的槽位。
Slot	object 可以使用 prompt() 注册的槽对象。

槽位

一个对象，表示要填充的广告位。可以使用 expect() 或 prompt() 进行注册。

FilledSlot<T>

一个对象，表示已填充的广告位。

参数
T	boolean|number|string 广告位类型。

选项

表示槽类型条目的对象。

字段
key	string 广告位类型条目的唯一标识符。
synonyms	array<string> 用于选择广告位选项的字词列表。

提示

一个对象，表示广告位的提示。

字段
associatedWords	array<string> 一个字词列表，用于帮助 NLU 系统确定要填充哪个槽位。

expect

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

expect(expectation) returns HandlerRegistration

在客户端上注册预期值。可在 intent 处理程序和槽中调用。

参数
expectation	IntentHandler|Slot 要注册的 intent 处理程序或槽。
HandlerRegistration	object 已注册的 intent 处理程序或槽位。

HandlerRegistration

表示已注册的 intent 处理程序的对象。

方法
deleteHandler()	function 取消注册预期的 intent 处理程序。

clearExpectations

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

clearExpectations() returns undefined;

通过删除之前注册的所有 intent 处理程序和槽来移除所有预期。

提示符

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

prompt(tts, expectation) returns Promise<Answer<T>>

使用提供的 TTS 字符串提示用户，并在客户端上注册预期值。可在 intent 处理程序和槽中调用。

参数
tts	string 用于提示用户输入预期预期信息的 TTS 字符串。
expectation	IntentHandler|Slot 要注册的 intent 处理程序或槽。
Answer<T>	object 用户针对提示提供的回答。

回答<T>

一个对象，表示用户提供的提示回答。

字段
value	boolean|number|string 用户提供的回答的值。
status	string 答案状态。 以下任一项： ANSWERED:用户在对提示进行回应时给出了回答。 NO_MATCH:系统提示用户输入答案，但其所提供的答案与预期答案或任何其他预期意图不符。 YIELD: 用户使用不同的 intent 来响应提示。

triggerScene

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

触发场景。

参数
sceneName	string 要触发的场景的名称。
TriggerSceneStatus	string 对 triggerScene() 的调用的状态。 以下任一项： SUCCESS:服务器已成功处理请求。 BLOCKED:请求已被执行中的现有查询阻止。 UNKNOWN:：请求的状态未知。

setUserParam

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

setUserParam(key, value) returns Promise<undefined>;

设置在对话之间传递和保留的键值对。

参数
key	string 参数键。
value	object|array|boolean|number|string 参数值。

getUserParam

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

getUserParam(key) returns Promise<object|array|boolean|number|string>;

获取指定键的参数值（如果存在）以及调用的状态。

参数
key	string 参数键。

resetUserParam

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

resetUserParam() returns Promise<void>;

清除所有用户参数。

setHomeParam

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

setHomeParam(key, value) returns Promise<undefined>;

设置在对话之间传递和保留的键值对。

参数
key	string 参数键。
value	object|array|boolean|number|string 参数值。

getHomeParam

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

getHomeParam(key) returns Promise<object|array|boolean|number|string>;

获取指定键的参数值（如果存在）以及调用的状态。

参数
key	string 参数键。

resetHomeParam

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

resetHomeParam() returns Promise<void>;

清除所有用户参数。

setCanvasState

setCanvasState(state) returns undefined

通知 Google 助理，画布 Web 应用已更新其状态。setCanvasState 方法不会返回值。您可以通过 conv.context.canvas.state 属性访问状态载荷。

注意 ：state 对象的字符串表示法的长度不得超过 50,000 个字符。如果字符串长度超过 50,000 个字符，系统会抛出错误。

参数
state	Object 更新后的 Canvas 应用状态（以 JSON 对象表示）。

InteractiveCanvasCallbacks

这些回调提供了一种方式来响应来自对话型 Action 的信息或请求，而这些方法则提供了一种向对话型 Action 发送信息或请求的方法。

onUpdate

onUpdate(data) returns Promise|undefined

从对话型 Action 发送 Canvas 响应时调用。TTS 将在返回的 Promise 得到解析或超时 10 秒后启动。

参数
data	Object 网络钩子发送的已更新数据。

onTtsMark

onTtsMark(markName) returns undefined

在 TTS 播放期间调用的回调。

始终触发的特殊标记：

• START 表示 TTS 的开始。
• END 表示 TTS 的结束。
• ERROR 表示播放 TTS 时发生错误。

您还可以使用 SSML 和 <mark> 标记（例如 <mark name="custom"/>）定义自定义标记。

注意：出现以下情况时，系统不会调用 SSML 标记：

• 在 TTS 开始前，用户点按麦克风，或者 Interactive Canvas 客户端会调用 sendTextQuery。系统会取消 TTS，并忽略 TTS 中的所有 SSML 标记。
• 在 TTS 期间，用户点按麦克风，或者 Interactive Canvas 客户端会调用 sendTextQuery。TTS 会中断，并且 TTS 中的任何剩余 SSML 标记都会被忽略。

参数
markName	string 将名称标记为在 TTS 播放期间调用。

onInputStatusChanged

注意：此 API 目前为开发者预览版。您可以在模拟器中测试此 API，但不要将使用此功能的 Action 部署到 Alpha 版、Beta 版或正式版渠道。使用此功能部署的操作在最终用户设备上将无法正常运行。

onInputStatusChanged(inputStatus) returns undefined

通知 Canvas 应用 Google 助理输入状态已更改。

参数
inputStatus	Enum 设备上的语音和/或文字输入处理状态。可以是： LISTENING：麦克风已打开。 IDLE：麦克风已关闭。 PROCESSING：Google 助理当前正在执行查询（麦克风已关闭）。