互動式 Canvas API 參考資料

Interactive Canvas API 是一種 JavaScript 程式庫，可用於在網頁應用程式中使用 interactiveCanvas 物件與對話動作建立介面。

如要進一步瞭解互動式 Canvas，請參閱互動式 Canvas 說明文件。

方法

已就緒

ready(callbacks) returns undefined

互動式 Canvas 網頁應用程式載入後，會呼叫以註冊回呼。

參數
callbacks	InteractiveCanvasCallbacks 包含方法回呼的物件。

傳送文字查詢

sendTextQuery(textQuery) returns Promise<state>

傳送文字查詢至對話動作。

參數
textQuery	string 要傳送至對話動作的查詢。
state	string 系統會顯示以下其中一個值： READY:平台可以接受要求。 BLOCKED:有進行中的查詢，新查詢會遭到捨棄。 UNKNOWN:無法判斷目前的查詢狀態。

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

決定螢幕頂端的標題高度。

參數
height	number 以像素為單位的高度。

outputTts

outputTts(text, openMic) returns undefined;

播放 SSML 文字。

參數
text	string 要播放的 SSML 支援字串。
openMic	boolean 是否要在播放 TTS 後開啟麥克風。

createIntentHandler

createIntentHandler(intentId, callback) returns IntentHandler

為 NLU 自訂意圖建立意圖處理常式。

參數
intentId	string 在 Actions Builder 中定義的意圖名稱。
callback	function(MatchedIntent) 比對意圖時要執行的函式。
IntentHandler	object 可透過 expect() 註冊的意圖處理常式物件。

IntentHandler

代表意圖處理常式的物件。可以透過 expect() 或 prompt() 註冊。

相符意圖

包含相符意圖資料的物件。

方法
getIntentArg(parameterName)	function(string) 取得相符意圖意圖參數的方法。

建立運算單元

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

建立類型類型的運算單元。

參數
callback	function(FilledSlot) 填入版位時要執行的函式。
hints	Hints 使用者在填入運算單元時可能會說的簡短字詞。hints 協助 NLU 系統決定要填滿的版位。
Slot	object 可以使用 prompt() 註冊的運算單元物件。

建立文字版位

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

建立類型字串的版位。

參數
callback	function(FilledSlot) 填入版位時要執行的函式。
hints	Hints 使用者在填入運算單元時可能會說的簡短字詞。hints 協助 NLU 系統決定要填滿的版位。
Slot	object 可以使用 prompt() 註冊的運算單元物件。

createConfirmationSlot

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

建立類型布林值的運算單元。

參數
callback	function(FilledSlot) 填入版位時要執行的函式。
hints	Hints 使用者在填入運算單元時可能會說的簡短字詞。hints 協助 NLU 系統決定要填滿的版位。
Slot	object 可以使用 prompt() 註冊的運算單元物件。

建立運算單元

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 運算單元類型項目的專屬 ID。
synonyms	array<string> 用於選取版位選項的字詞清單。

提示

代表運算單元提示的提示的物件。

欄位
associatedWords	array<string> 協助 NLU 系統決定要填入的版位。

預期

expect(expectation) returns HandlerRegistration

針對用戶端註冊期望。可在意圖處理常式和運算單元中呼叫。

參數
expectation	IntentHandler|Slot 要註冊的意圖處理常式或運算單元。
HandlerRegistration	object 已註冊的意圖處理常式或運算單元。

Handler 註冊

代表已註冊意圖處理常式的物件。

方法
deleteHandler()	function 取消註冊預期的意圖處理常式。

Clearect

clearExpectations() returns undefined;

刪除所有之前註冊的意圖處理常式和運算單元，藉此移除所有期望目標。

提示

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

使用提供的 TTS 字串提示使用者，並在用戶端上註冊預期內容。可在意圖處理常式和運算單元中呼叫。

參數
tts	string 用於提示使用者提供的期望目標的 TTS 字串。
expectation	IntentHandler|Slot 要註冊的意圖處理常式或運算單元。
Answer<T>	object 針對提示使用者提供的答案。

接聽<T>

物件代表使用者提供的答案。

欄位
value	boolean|number|string 使用者所提供答案的值。
status	string 答案狀態。 系統會顯示以下其中一個值： ANSWERED:使用者以解答的方式回應提示。 NO_MATCH: 使用者收到答案，且回覆的內容與預期的答案或其他預期意圖不符。 YIELD:使用者以其他意圖回應提示。

triggerScene

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

觸發情境。

參數
sceneName	string 要觸發的情境名稱。
TriggerSceneStatus	string triggerScene() 的呼叫狀態， 系統會顯示以下其中一個值： SUCCESS: 伺服器已成功處理這項要求。 BLOCKED: 進行中的現有查詢封鎖了要求。 UNKNOWN:要求的狀態不明。

setUserParam (設定使用者參數)

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

設定要在兩個對話之間傳送及保留的鍵/值組合。

參數
key	string 參數鍵。
value	object|array|boolean|number|string 參數值。

getUserParam 參數

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

取得指定鍵的參數值 (如果有的話)，以及叫用狀態。

參數
key	string 參數鍵。

重設使用者參數

resetUserParam() returns Promise<void>;

清除所有使用者參數。

設定 HomeParam

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

設定要在兩個對話之間傳送及保留的鍵/值組合。

參數
key	string 參數鍵。
value	object|array|boolean|number|string 參數值。

getHomeParam 方法

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

取得指定鍵的參數值 (如果有的話)，以及叫用狀態。

參數
key	string 參數鍵。

重設 HomeParam

resetHomeParam() returns Promise<void>;

清除所有使用者參數。

setCanvasState

setCanvasState(state) returns undefined

通知 Google 助理 Canvas 網頁應用程式已更新狀態。setCanvasState 方法不會傳回值。狀態酬載可透過 conv.context.canvas.state 屬性存取。

參數
state	Object 更新 Canvas 應用程式的 JSON 物件狀態。

互動式畫布回呼

這些回呼可讓您回應對話動作中的資訊或要求，而方法則可傳送資訊或要求至對話動作。

onUpdate

onUpdate(data) returns Promise|undefined

當從對話動作傳送 Canvas 回應時呼叫。傳回傳回的 Promise 或是 10 秒後逾時，TT 會啟動。

參數
data	Object 已更新 Webhook 傳送的資料。

onTtsMark

onTtsMark(markName) returns undefined

在 TTS 播放期間叫用的回呼。

一律觸發的特殊標記：

• START 表示 TTS 的開始時間。
• END 表示 TTS 的結尾。
• ERROR 表示播放 TTS 時發生錯誤。

您也可以使用 SSML 和 <mark> 標記定義自訂標記，例如 <mark name="custom"/>。

參數
markName	string 在 TTS 播放期間叫用的名稱。

onInputStatusChanged

onInputStatusChanged(inputStatus) returns undefined

通知 Canvas 應用程式，說明 Google 助理輸入狀態已變更。

參數
inputStatus	Enum 裝置上的語音和/或文字輸入處理狀態。可能的狀態如下： LISTENING：麥克風已開啟。 IDLE：麥克風已關閉。 PROCESSING：Google 助理目前正在執行查詢 (麥克風已關閉)。