互動式 Canvas API 參考資料

互動式 Canvas API 是一個 JavaScript 程式庫，可用於在網頁應用程式中使用 interactiveCanvas 物件與對話動作互動。

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

方法

已就緒

ready(callbacks) returns undefined

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

參數
callbacks InteractiveCanvasCallbacks

包含方法回呼的物件。

sendTextQuery

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() 註冊。

MatchedIntent

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

方法
getIntentArg(parameterName) function(string)

取得相符意圖意圖參數的方法。

createNumberSlot

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

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

參數
callback function(FilledSlot)

版位填入時要執行的函式。
hints Hints

使用者填入運算單元時可能會說的簡短字詞。hints 協助 NLU 系統決定要填入的插槽。
Slot object

可使用 prompt() 註冊的運算單元物件。

createTextSlot

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

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

expect(expectation) returns HandlerRegistration

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

參數
expectation IntentHandler|Slot

要註冊的意圖處理常式或運算單元。
HandlerRegistration object

已註冊的意圖處理常式或運算單元。

HandlerRegistration

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

方法
deleteHandler() function

取消註冊預期的意圖處理常式。

clearExpectations

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

resetUserParam() returns Promise<void>;

清除所有使用者參數。

setHomeParam

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

參數鍵。

resetHomeParam

resetHomeParam() returns Promise<void>;

清除所有使用者參數。

setCanvasState

setCanvasState(state) returns undefined

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

參數
state Object

Canvas 應用程式的更新狀態，以 JSON 物件表示。

InteractiveCanvasCallbacks

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

onUpdate

onUpdate(data) returns Promise|undefined

從對話動作傳送 Canvas 回應時呼叫。TTS 會在傳回的 Promise 解決時啟動，或在 10 秒後逾時。

參數
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 助理目前正在執行查詢 (麥克風已關閉)。