如要將資訊轉發至網頁應用程式,您必須從對話邏輯傳送 Canvas
回應。Canvas
回應可以執行下列任一操作:
- 在使用者的裝置上顯示全螢幕網頁應用程式
- 傳遞資料以更新網頁應用程式
以下各節說明如何為每個情境傳回 Canvas 回應。
啟用互動式畫布
您必須以特定方式設定動作,才能使用互動式畫布。如要建立使用互動式畫布的動作,您必須透過 Actions 主控台進行額外設定;而針對 Actions SDK,您必須修改 settings.yaml
檔案。如要查看使用 Actions SDK 建立及設定互動式畫布動作的完整程序,請參閱「建立專案」。
使用動作建構工具時,請按照下列額外步驟啟用互動式畫布:
- 如果您沒有在「What type of Action to build?」畫面中選取「Game」資訊卡,請按一下頂端導覽列的「Deploy」。 在「其他資訊」下方,選取「遊戲與娛樂」類別。按一下 [儲存]。
- 按一下動作主控台頂端導覽列中的「Develop」。
- 按一下左側導覽面板中的「互動畫布」。
- 在「Do you want your Action to use Interactive Canvas?」(您要讓動作使用互動式畫布嗎?) 下方,選取下列其中一個選項:
- 啟用具備伺服器 Webhook 執行要求的互動畫布。這個選項會透過 Webhook 存取特定功能,並且經常使用
onUpdate()
將資料傳送至網頁應用程式。啟用後,系統會在場景中處理意圖比對作業,您可以選擇在轉換至其他場景或結束對話前呼叫 Webhook。 - 透過用戶端執行要求啟用互動式畫布。這個選項可讓您將 Webhook 執行要求邏輯移至網頁應用程式,並限制 Webhook 呼叫僅可執行需要這項權限的對話功能,例如帳戶連結。啟用後,您就可以使用
expect()
在用戶端註冊意圖處理常式。
- 啟用具備伺服器 Webhook 執行要求的互動畫布。這個選項會透過 Webhook 存取特定功能,並且經常使用
- 選用:在「Set your default web app URL」(設定預設網頁應用程式網址) 欄位中輸入網頁應用程式網址。這項操作會將含有網址欄位的預設
Canvas
回應新增至主要叫用。 - 點按「儲存」。
使用 Actions SDK 時,請按照下列額外步驟啟用互動式畫布:
- 將
settings.yaml
檔案中的category
欄位設為GAMES_AND_TRIVIA
,以充分描述並協助使用者發掘您的動作。 - 將
settings.yaml
檔案中的usesInteractiveCanvas
欄位設為true
。
檢查介面功能
互動式畫布架構只會在提供視覺化介面的 Google 助理裝置上執行,因此動作需要檢查使用者裝置上的 INTERACTIVE_CANVAS
功能。在 Actions Builder 中定義提示時,您可以在 candidates
物件的 selector
欄位中指定裝置功能清單。提示選取器會選取最適合使用者裝置功能的提示候選提示。
如要傳回 Canvas
回應,動作的邏輯應執行以下操作:
- 確認使用者的裝置支援
INTERACTIVE_CANVAS
功能。如果支援,請將Canvas
回應傳送給使用者。 - 如果無法使用互動式畫布功能,請檢查使用者的裝置是否支援
RICH_RESPONSE
功能。如果包含,請改為傳送複合式回應給使用者。 - 如果無法使用複合式回應功能,請將簡易回應傳送給使用者。
以下程式碼片段會根據使用者的裝置功能傳回適當的回應:
YAML
candidates: - selector: surface_capabilities: capabilities: - INTERACTIVE_CANVAS canvas: url: 'https://example.web.app' - selector: surface_capabilities: capabilities: - RICH_RESPONSE content: card: title: Card title text: Card Content image: url: 'https://example.com/image.png' alt: Alt text button: name: Link name open: url: 'https://example.com/' - first_simple: variants: - speech: Example simple response.
JSON
{ "candidates": [ { "selector": { "surface_capabilities": { "capabilities": [ "INTERACTIVE_CANVAS" ] } }, "canvas": { "url": "https://example.web.app" } }, { "selector": { "surface_capabilities": { "capabilities": [ "RICH_RESPONSE" ] } }, "content": { "card": { "title": "Card title", "text": "Card Content", "image": { "url": "https://example.com/image.png", "alt": "Alt text" }, "button": { "name": "Link name", "open": { "url": "https://example.com/" } } } } }, { "first_simple": { "variants": [ { "speech": "Example simple response." } ] } } ] }
Node.js
const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE"); const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS"); if (supportsInteractiveCanvas) { // Respond with a Canvas response conv.add(new Canvas({ url: 'https://example.web.app', })); } else if (supportsRichResponse) { // Respond with a rich response conv.add(new Card({ title: 'Card title', image: new Image({ url: 'https://example.com/image.png', alt: 'Alt text', }), button: new Link({ name: 'Link name', open: { url: 'https://example.com/', }, }), })); } else { // Respond with a simple response conv.add('Example simple response.'); }
轉譯網頁應用程式
使用互動式畫布的動作包含網頁應用程式,可將自訂視覺內容傳送給使用者做為回覆。網頁應用程式轉譯後,使用者會繼續透過語音、文字或輕觸功能與應用程式互動,直到對話結束為止。
您的第一個 Canvas
回應必須包含網頁應用程式的網址。這種 Canvas
回應會指示 Google 助理在使用者裝置上呈現該網址的網頁應用程式。一般而言,您會在使用者叫用動作後立即傳送第一個 Canvas
回應。網頁應用程式載入時,互動式畫布程式庫會載入,且網頁應用程式會使用互動式 Canvas API 註冊回呼處理常式。
您可以在 Actions Builder 中指定網頁應用程式的網址,如以下螢幕截圖所示:
如果您在指定網頁應用程式網址後,建立包含 Canvas
回應的提示,Actions Builder 就會自動填入 Canvas
回應的網址欄位。如要進一步瞭解如何在主控台中設定網頁應用程式網址,請參閱「啟用互動式畫布」一節。
下列程式碼片段說明如何建構 Canvas
回應,以便在 Actions Builder 和 Webhook 中轉譯網頁應用程式:
YAML
candidates: - first_simple: variants: - speech: >- Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later. canvas: url: 'https://your-web-app.com'
JSON
{ "candidates": [ { "first_simple": { "variants": [ { "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later." } ] }, "canvas": { "url": "https://your-web-app.com" } } ] }
Node.js
app.handle('welcome', (conv) => { conv.add('Welcome! Do you want me to change color or pause spinning? ' + 'You can also tell me to ask you later.'); conv.add(new Canvas({ url: `https://your-web-app.com`, })); });
JSON
{ "session": { "id": "session_id", "params": {} }, "prompt": { "override": false, "firstSimple": { "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later.", "text": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later." }, "canvas": { "data": [], "suppressMic": false, "url": "https://your-web-app.com" } } }
傳遞資料以更新網頁應用程式
傳送初始 Canvas
回應後,您可以使用額外的 Canvas
回應來為 data
提供更新,您應用程式的自訂邏輯會使用該回應來變更網頁應用程式。當您傳送將資料傳遞至網頁應用程式的 Canvas
回應時,會發生下列步驟:
- 當場景中比對相符的意圖時,就會觸發事件,而包含含有 JSON 酬載的
data
欄位的Canvas
回應然後再做為回應傳回。 data
欄位會傳遞至onUpdate
回呼,並用於更新網頁應用程式。對話動作可以傳送新的
Canvas
回應,並在data
欄位中提供資訊,以傳送新的更新或載入新狀態。
你可以透過下列兩種方式將資料傳遞至網頁應用程式:
- 使用動作建構工具。Actions Builder 會將更新網頁應用程式的必要中繼資料填入
Canvas
回應中的data
欄位。 - 使用 Webhook。如果您有 Webhook,可以設定自訂資料酬載,以更新
Canvas
回應中的網頁應用程式。
以下各節將說明如何透過動作建構工具和 Webhook 傳遞資料。
使用動作建構工具傳送資料
使用 Actions Builder 時,您不需要定義 Webhook 來管理傳送至網頁應用程式的中繼資料。不過,當您在 Actions Builder UI 中設定意圖處理常式時,可以加入 Canvas
回應。data
欄位會自動填入用於更新網頁應用程式的必要中繼資料,例如意圖名稱、從使用者輸入內容中擷取的參數,以及目前場景。
舉例來說,下列 Guess
意圖處理常式表示您要加入 Canvas
回應:
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
您可以選擇將下列程式碼片段附加到意圖處理常式,以傳送 TTS 訊息:
...
- first_simple:
variants:
- speech: Optional message.
Actions Builder 會自動利用中繼資料擴充 Canvas
回應以更新網頁應用程式,如以下程式碼片段所示。在這個範例中,使用者猜猜字詞遊戲中的字母「a」如下:
YAML
candidates: - canvas: data: - google: intent: params: letter: resolved: a original: a name: guess scene: Game sendStateDataToCanvasApp: true
JSON
{ "candidates": [ { "canvas": { "data": [ { "google": { "intent": { "params": { "letter": { "resolved": "a", "original": "a" } }, "name": "guess" }, "scene": "Game" } } ], "sendStateDataToCanvasApp": true } } ] }
此回應會以使用者的答案更新網頁應用程式,並轉換至適當的情境。
使用 Webhook 傳送資料
您可以在 Webhook 中,使用必要的狀態資訊手動設定 Canvas
回應的 data
欄位。如果您需要在 Canvas
回應中加入自訂 data
酬載,則建議使用這個方法,而非只傳送更新網頁應用程式所需的一般中繼資料。
下列程式碼片段說明如何在 Webhook 的 Canvas
回應中傳遞資料:
Node.js
app.handle('start_spin', (conv) => { conv.add(`Ok, I'm spinning. What else?`); conv.add(new Canvas({ data: { command: 'SPIN', spin: true, }, })); });
JSON
{ "session": { "id": "session_id", "params": {} }, "prompt": { "override": false, "firstSimple": { "speech": "Ok, I'm spinning. What else?", "text": "Ok, I'm spinning. What else?" }, "canvas": { "data": { "command": "SPIN", "spin": true }, "suppressMic": false, "url": "" } } }
規範與限制
建構動作時,請留意下列 Canvas
回應的規範和限制:
- 執行要求中的每個 Webhook 處理常式都必須包含
Canvas
。如果 Webhook 回應不含Canvas
,網頁應用程式就會關閉。 - 您只需在傳送給使用者的第一個
Canvas
回應中加入網頁應用程式網址即可。 Canvas
回應網址必須是有效的網址,且通訊協定必須是 https。Canvas
回應的大小不得超過 50 KB。