Interactive Canvas API 参考文档

Interactive Canvas API 是一个 JavaScript 库，用于接口 在 Web 应用中使用 interactiveCanvas 对象与对话型 Action 搭配使用。

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

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

方法

警告：某些 Interactive Canvas API 目前为开发者预览版。您可以在 但不要在 Alpha 版、Beta 版或正式版中部署使用这些功能的 Action 渠道。使用这些特性部署的操作将无法对最终用户执行 设备。

准备好了

ready(callbacks) returns undefined

在 Interactive Canvas Web 应用加载后调用此方法，以便注册回调。

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

注意 ：在网页加载完毕后，您必须立即在 Web 应用中调用 ready API 。否则，相应 Action 会关闭。

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) 用于获取匹配意图的 intent 参数的方法。

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 系统确定要填充哪个位置的字词列表。

预计

注意：此 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: 用户以不同的意图响应提示。

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 助理 Canvas Web 应用已更新其状态。通过 setCanvasState 方法不会返回值。状态载荷可通过 conv.context.canvas.state 属性。

注意 ：state 对象的字符串表示形式的长度必须为 不超过 5 万个字符。如果字符串超过 5 万个字符 如果过长，则会抛出错误。

参数
state	Object 画布应用的更新状态，作为 JSON 对象。

InteractiveCanvasCallbacks

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

onUpdate

onUpdate(data) returns Promise|undefined

在对话型 Action 发送 Canvas 响应时调用。TTS 将在以下时间后启动： 返回的 Promise 进行解析，或者在 10 秒后超时。

参数
data	Object 已更新 Webhook 发送的数据。

onTtsMark

onTtsMark(markName) returns undefined

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

始终触发的特殊标记：

• START 表示 TTS 的开头。
• END 表示 TTS 的结束。
• ERROR 表示播放 TTS 时出错。

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

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

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

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

onInputStatusChanged

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

onInputStatusChanged(inputStatus) returns undefined

通知 Canvas 应用 Google 助理输入状态已发生变化。

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