使用 Actions Builder 為 Google 助理建構互動式畫布動作

1. 總覽

警告：對話動作已於 2023 年 6 月 13 日淘汰。詳情請參閱「 對話動作停用」一節。

Actions on Google 是一個開發人員平台，可讓您製作軟體來擴充 Google 助理 (Google 的虛擬個人助理) 的功能，在超過 10 億部裝置，包括智慧音箱、手機、汽車、電視和耳機等。使用者會在對話中與 Google 助理互動，以便處理生活大小事，例如購買食品雜貨或預訂乘車。如需目前可以新增的完整清單，請參閱動作目錄。開發人員可以使用 Actions on Google，輕鬆建立及管理使用者和第三方服務之間令人愉快且實用的對話體驗。

本程式碼研究室是進階模組，適合具備建構 Google 助理 Actions for Google 助理的經驗的讀者。如果您未曾使用過 Actions on Google 開發經驗，請先前往入門程式碼研究室 ( 第 1 級和第 2 級)，熟悉這個平台。這些單元將引導你學習一系列功能，協助你擴充動作功能並吸引更多目標對象。

在本程式碼研究室中，您將使用互動式畫布 (建構於 Google 助理的架構)，在對話動作中新增全螢幕遊戲。這款遊戲是互動式網頁應用程式，Google 助理會在對話中回應使用者。接著，使用者可以在智慧螢幕和 Android 行動裝置上，使用語音或文字輸入功能玩遊戲。

您無須自行建構整個遊戲，而是部署名為 Snow Pal 的部分預先建構遊戲，並逐步加入遊戲的邏輯。雪花白是傳統漢曼遊戲的變化版本；遊戲會提供多個用來代表某個字詞的空白空格，然後猜測您認為可能是該字詞中的字母。每猜錯的話，Snow Pal 就會稍微融化一點。只要在 Snow Pal 融化之前就找出這個字詞，即可贏得遊戲勝利。

圖 1. 完結的雪球遊戲

建構項目

在本程式碼研究室中，您將建構使用互動式畫布的動作。您的動作具備下列功能：

• 全螢幕文字遊戲使用者可透過語音指令玩遊戲
• 使用者可按下的按鈕開始玩遊戲
• 使用者只要按下按鈕，即可再玩一次遊戲

完成本程式碼研究室後，您完成的動作將具有以下對話流程：

Google 助理： Welcome to Snow Pal! Would you like to start playing the game?

使用者： Yes.

Google 助理： Try guessing a letter in the word or guessing the word.

使用者： I guess the letter E.

Google 助理： Let's see if your guess is there...E is right. Right on! Good guess.

在遊戲結束之前，使用者會持續猜測字母或猜測未知的字詞。

課程內容

• 如何建構及部署互動式畫布動作
• 如何根據使用者的語音和觸控輸入更新文字遊戲
• 如何使用不同方法將資料傳送至網頁應用程式
• 如何偵錯互動式畫布動作

軟硬體需求

使用本程式碼研究室的必備條件包括：

• 使用 Google Chrome 等網路瀏覽器
• 自選的 IDE 或文字編輯器
• 已在機器上安裝 Node.js、npm 和 git

強烈建議您熟悉 JavaScript (ES6)，協助您瞭解本程式碼研究室所用的程式碼。

選用：取得完整程式碼範例

在本程式碼研究室中，您將透過不完整的版本逐步建構範例。如有需要，您也可以從 GitHub 存放區取得完整範例。

2. 互動式畫布簡介

互動式畫布是建構於 Google 助理的架構，可讓你在對話動作中加入全螢幕視覺效果和動畫。

重要字詞：

• 對話動作：使用對話介面完成使用者要求的動作。

使用互動式畫布的動作的運作方式與一般對話動作類似。不過，互動畫布動作還提供一項額外功能，可將回應傳送至開啟全螢幕網頁應用程式的裝置。

重要字詞：

• 網頁應用程式：這類應用程式使用 HTML、CSS 和 JavaScript 等網路技術，打造互動性視覺體驗 (例如遊戲)。在本程式碼研究室中，網頁應用程式是 Snow Pal 遊戲的圖像和動畫。

使用者透過語音或觸控的方式為網頁應用程式提供內容，直到對話結束為止。

圖 2. 使用互動式畫佈建構的動作。

在本程式碼研究室中，您的專案分為下列三個主要部分：

• 網頁應用程式：網頁應用程式檔案，包含網頁應用程式影像和動畫的程式碼，以及根據使用者輸入內容更新網頁應用程式的邏輯。
• Conversational Action：對話動作包含您的對話邏輯，可識別、處理及回應使用者的輸入內容。
• Webhook：Webhook 會處理遊戲的邏輯。在本程式碼研究室中，您可以將 Webhook 視為遊戲伺服器。

重要字詞：

• Webhook：HTTP 回呼，可處理情境或意圖的要求，通常用於動態建構對話回應 (通常透過發出 API 呼叫)。

在本程式碼研究室的各節中，您必須修改網頁應用程式、對話動作和 Webhook，為互動式畫布動作新增功能。

大致來說，「雪花白」動作中的 Conversational Action、Webhook 和網頁應用程式會以下列方式運作：

1. 對話動作會提示使用者猜測字詞中的字母或猜測完整字詞。
2. 使用者在智慧螢幕上對 Snow Pal 網頁應用程式說出「我猜字母 i」。
3. 系統會將使用者的輸入內容轉送至您的 Conversational Action (在 Actions Builder 和/或 Actions SDK 專案中定義)。
4. 對話動作會處理使用者的輸入內容，並根據輸入內容觸發 Webhook 中的邏輯，以更新網頁應用程式或傳送中繼資料，藉此直接更新網頁應用程式。
5. 網頁應用程式會更新，顯示字母在文字中出現的位置，然後使用者再猜一次。

如要進一步瞭解互動式畫布的運作方式，請參閱「瞭解互動式畫布基礎架構」一節。瞭解基本概念後，現在可以開始為本程式碼研究室設定環境了。

3. 設定

檢查 Google 權限設定

如要測試您為本程式碼研究室建構的動作，您需啟用必要權限，才能執行動作控制台模擬工具。如要啟用權限，請按照下列步驟操作：

1. 前往活動控制項。
2. 如有需要，請使用你的 Google 帳戶登入。
3. 啟用下列權限：

• 網路和應用程式活動
• 包括「網頁和」「應用程式活動」，勾選「包括 Chrome 歷史記錄以及採用 Google 服務的網站、應用程式和裝置中的活動記錄」核取方塊。

安裝 gactions 指令列介面

在本程式碼研究室中，您將使用 gactions 指令列介面 (CLI) 工具，同步處理 Actions 主控台和本機檔案系統之間的 Actions 專案。

關鍵字詞：

• gactions CLI：這項工具可讓您初始化動作專案檔案、將更新內容推送至 Actions 主控台、部署 Actions 專案等等。

如要安裝 gactions CLI，請按照「Install the gactions 指令列工具」一節的指示操作。

安裝 Firebase 指令列介面

您可以利用 Firebase 指令列介面 (CLI)，將 Actions 專案部署至 Cloud Functions，並託管網頁應用程式。

如果您已安裝 Firebase CLI，可以略過這些步驟，並繼續進行下一部分。

本程式碼研究室會使用 npm 安裝 Firebase CLI。請務必安裝 npm，此 npm 通常隨附 Node.js。

1. 如要安裝或升級 CLI，請開啟終端機並執行下列 npm 指令：

npm install -g firebase-tools

仍然沒反應？你可能需要變更 npm 權限。

2. 如要確認是否已正確安裝 CLI，請執行下列指令：

firebase --version

確認 Firebase CLI 為 8 以上版本，以便具備 Cloud Functions 所需的所有最新功能。如果沒有，請執行 npm install -g firebase-tools 進行升級。

3. 如要登入 Firebase，請執行下列指令：

firebase login

登入 Firebase 時，請務必使用你建立 Actions 專案時所用的 Google 帳戶。

複製存放區

在本節中，您將複製本程式碼研究室所需的檔案。如要取得這些檔案，請按照下列步驟操作：

1. 開啟終端機，然後變更為您平常儲存程式設計專案的目錄。如果您沒有這類目錄，請變更為主目錄。
2. 如要複製這個存放區，請在終端機中執行下列指令：

git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

開啟 start/ 目錄。這個存放區包含以下重要目錄，您將使用：

• public/：這個目錄包含網頁應用程式的 HTML、CSS 和 JavaScript 程式碼。
• sdk/custom/：這個目錄包含對話動作 (場景、意圖和類型) 的邏輯。
• sdk/webhooks/：這個目錄是您的 Webhook，包含遊戲邏輯。

圖 3. start 目錄程式碼的結構。

注意：含有完成程式碼的檔案位於 complete/ 目錄中。

4. 設定 Actions 專案

在本節中，您將建立及設定 Actions 專案，使用 gactions CLI 將複製的存放區中的程式碼推送至 Actions 主控台，以及部署網頁應用程式和 Webhook。

建立 Actions 專案

Actions 專案是 Action 的容器。如要為本程式碼研究室建立 Actions 專案，請按照下列步驟操作：

1. 開啟動作控制台。
2. 按一下 [新專案]。
3. 在「Project name」輸入專案名稱，例如 canvas-codelab。這個名稱僅供內部參考。您稍後可以為專案設定外部名稱。

4. 按一下 [Create Project]。
5. 在「您想建構哪種動作？」畫面中，選取「遊戲」資訊卡。
6. 點選「下一步」。
7. 選取「空白專案」資訊卡。
8. 按一下「開始建構」。

儲存動作的專案 ID

專案 ID 是動作的專屬 ID。在本程式碼研究室中，您需要用到專案 ID 的幾個步驟。

如要擷取專案 ID，請按照下列步驟操作：

1. 在動作控制台中，按一下垂直排列的三個點 >專案設定。

2. 複製專案 ID。

連結帳單帳戶

如要在本程式碼研究室中使用 Cloud Functions 部署執行要求，您必須將帳單帳戶與 Google Cloud 中的專案建立關聯。如果您已有帳單帳戶，可以略過下列步驟。

如要將帳單帳戶與專案建立關聯，請按照下列步驟操作：

1. 前往 Google Cloud Platform 帳單頁面。
2. 按一下「新增帳單帳戶」或「建立帳戶」。
3. 填寫付款資訊。
4. 按一下「開始免費試用」或「提交並啟用計費功能」。
5. 前往 Google Cloud 帳單頁面。
6. 按一下「My Projects」分頁標籤。
7. 按一下三個點圖示 >變更帳單資訊。
8. 在下拉式選單中，選取您設定的帳單帳戶。
9. 按一下 [設定帳戶]。

如要避免支付費用，請按照「清除專案」一節的步驟操作。

部署網頁應用程式

在本節中，您將使用 Firebase CLI 部署網頁應用程式 (「雪花白」遊戲)。部署完成後，您可以擷取網頁應用程式的網址，並查看遊戲在瀏覽器中呈現的樣貌。

您可以選擇使用 Firebase 指令 firebase deploy 定義動作，允許部署執行要求檔案和網頁應用程式檔案。在本程式碼研究室中，您會分別部署網頁應用程式和執行要求。

如要部署網頁應用程式，請按照下列步驟操作：

1. 在終端機中，前往 start/ 目錄。
2. 執行下列指令，並將 {PROJECT_ID} 改成您的專案 ID：

firebase deploy --project {PROJECT_ID} --only hosting

幾分鐘後，畫面會顯示 "Deploy complete!"，表示您已成功將 Snow Pal 網頁應用程式部署至 Firebase。

如要在瀏覽器中觀看雪花白遊戲，請按照下列步驟操作：

1. 擷取終端機輸出內容中提供的代管網址。網址格式如下：https://<PROJECT_ID>.web.app

如果網址未顯示在終端機輸出內容中，請按照下列步驟擷取網頁應用程式網址：

1. 開啟 Firebase 控制台。
2. 從選項清單中選取 Actions 專案。
3. 按一下「開發」>代管：
4. 「Dashboard」(資訊主頁) 分頁下應會顯示專案的網域清單。複製網址。格式如下：https://<PROJECT_ID>.web.app

2. 在瀏覽器中貼上網址。您應該會看到「雪花白」遊戲的開始畫面，以及「Start Game」按鈕：

在 Actions 專案中加入網頁應用程式網址和專案 ID

接著，請將網頁應用程式網址和專案 ID 加進 actions.intent.MAIN.yaml 檔案。新增網頁應用程式網址後，Conversational Action 就會知道要傳送資料至哪個網址；在 settings.yaml 中新增專案 ID，則可讓您將下載的檔案推送至 Actions Console 中的正確專案。

如要新增網頁應用程式網址和專案 ID，請按照下列步驟操作：

1. 在文字編輯器中開啟 start/sdk/custom/global/actions.intent.MAIN.yaml 檔案。
2. 將「URL」欄位中的預留位置字串替換成網頁應用程式的網址。
3. 在文字編輯器中開啟 start/sdk/settings/settings.yaml 檔案。
4. 在 projectId 欄位中，將預留位置字串替換為您的專案 ID。

將專案推送至 Actions 主控台

如要使用本機專案更新 Actions 主控台，您必須將 Actions 專案推送到 Actions 主控台。步驟如下：

1. 切換至 sdk 目錄：

cd sdk/

2. 如要將本機檔案系統的設定複製到 Actions 主控台，請執行下列指令：

gactions push 

部署 Webhook

執行 gactions push 時，您已將起始的 Webhook 程式碼匯入 Actions 主控台。在本程式碼研究室的其他章節中，您可以在 Actions 控制台中編輯 Webhook 程式碼。此時，您就可以透過 Actions 主控台部署 Webhook。

如要部署 Webhook，請按照下列步驟操作：

1. 在 Actions 主控台，按一下導覽列中的「Develop」。
2. 按一下導覽列中的「Webhook」分頁標籤。
3. 按一下「Deploy Fulfillment」(部署執行要求)。

注意：點選「Deploy Fulfillment」(部署執行要求) 後，系統會顯示「Deploy Fulfillment」(需要帳單帳戶) 的訊息。如要部署 Webhook，您必須將帳單帳戶與 Google Cloud 中的專案建立關聯。如要設定帳單帳戶，請按一下「開啟 Cloud 控制台」，然後按照步驟連結帳單帳戶。您可以在本程式碼研究室的結尾處刪除這項專案，以免產生費用。詳情請參閱清除所用資源一節。

Cloud Functions 可能需要幾分鐘來佈建及部署執行要求。您應該會看到「Cloud Function deployment in progress...」訊息。程式碼部署成功時，訊息會更新為「Your Cloud Function deployment is the updated」。

在模擬工具中測試

此時，你的動作已連結至網頁應用程式。您可以使用動作控制台模擬工具，確保在叫用動作時能顯示網頁應用程式。

如要測試動作，請按照下列步驟操作：

1. 按一下 Actions 主控台導覽列中的「測試」。
2. 在「Input」欄位中輸入 Talk to Snow Pal sample，然後按下 Enter 鍵。
3. 在「Input」欄位中輸入 Yes，然後按下 Enter 鍵。或者，您也可以按一下「開始遊戲」。

您尚未設定猜測字母或猜測字詞的邏輯，因此如果您猜測字詞或字母，會收到「...答錯了。繼續嘗試！我們似乎必須新增更多功能，才能正常運作。」

5. 瞭解互動式畫布基礎架構

這項專案的功能分為三個主要元件：對話動作、網頁應用程式和 Webhook。請注意，這個模式用於說明動作的設定方法，並以這種方式強調互動畫布的核心功能。

以下各節將進一步說明 Conversational Action、Webhook 和網頁應用程式如何搭配運作，以及其他重要的互動式畫布元素。

對話動作

動作的 Conversational Action 元件會處理及處理使用者輸入內容，然後傳送至合適的情境，也就是建立回應給使用者。舉例來說，如果使用者在「雪花白」遊戲中說出「我猜到字母 e」，您的對話動作會擷取該字母做為意圖參數，並傳遞至適當的遊戲邏輯，藉此判斷猜測是否正確，並據此更新網頁應用程式。您可以在 Actions Builder 這個網頁式 IDE 中查看及修改這個對話邏輯。以下螢幕截圖顯示 Actions Builder 中的對話動作部分：

圖 4. 動作建構工具中的 Main invocation 視覺化效果。

這張螢幕截圖顯示動作的 Main invocation，使用者說出「Ok Google，與 Snow Pal 交談」等詞組時會進行比對。使用者叫用動作時，Main invocation 會傳送含有 canvas 回應的提示，其中包含網頁應用程式的網址。

關鍵字詞：

• Canvas：回應包含網頁應用程式網址和/或要傳送的資料。您可以在 Webhook 或 Actions Builder 中設定 Canvas 回應。詳情請參閱「Canvas 提示」。

動作中的第一個 canvas 回應必須包含網頁應用程式網址。這項回應會指示 Google 助理在使用者裝置上，以該位址轉譯網頁應用程式。動作建構工具中的其他 canvas 回應可包含設為 true 的欄位 send_state_data_to_canvas_app。這個欄位會在比對出意圖時，將意圖名稱和任何參數值傳送至網頁應用程式，網頁應用程式會根據使用者輸入內容更新相關資料。

Webhook

在本程式碼研究室中，您的 Webhook 包含遊戲邏輯 (您可以將 Webhook 視為遊戲伺服器)。遊戲邏輯包含多種元素，例如判斷使用者猜測的字詞是否正確或使用者是否成功，以及根據結果建構回應。您可以在 Actions Builder 中修改 Webhook。

當您的動作需要執行遊戲邏輯時，動作建構工具會呼叫 Webhook。舉例來說，Game 場景中的 guess 意圖會向 guess 處理常式發出 Webhook 呼叫，然後由該處理常式執行邏輯，判斷使用者的猜測是否正確。Webhook 可以在對應於網頁應用程式檔案的處理常式內納入 Canvas 回應，並適當更新網路。

網頁應用程式

圖 5. 以視覺化方式呈現互動式畫布動作中 Conversational Action、Webhook 和網頁應用程式的互動情形。

網頁應用程式檔案包含網頁應用程式影像和動畫的程式碼，以及根據使用者輸入內容更新網頁應用程式的邏輯。您可以在文字編輯器中修改網頁應用程式檔案，並使用 Firebase CLI 部署這些變更。

在 Conversational Action 和網頁應用程式之間進行通訊

您需要啟用 Conversational Action 與網頁應用程式之間的通訊，網頁應用程式才能根據使用者輸入內容進行更新。例如，如果使用者說「我猜字母 f」，

Conversational Action 必須提供英文字母 f 給網頁應用程式，才能讓網頁應用程式據此更新。如要將使用者輸入內容從對話動作傳遞至網頁應用程式，您必須透過 Interactive Canvas API 載入。

重要字詞：

• 互動畫布 API：將 JavaScript API 加入網頁應用程式，就能讓網頁應用程式和對話動作相互通訊。

/public/index.html 是這個 API 的指令碼，該指令碼是 Snow Pal 遊戲的主要 HTML 檔案。這個檔案定義了 UI 在幾個指令碼中的外觀和載入方式：

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

如要根據使用者的輸入內容更新網頁應用程式，您還必須在網頁應用程式檔案中註冊並設定回呼。「回呼」功能可讓網頁應用程式回應對話動作的資訊或要求。

/public/js/action.js 中有一個名為 Action 的預設類別，用於宣告及註冊回呼。Action 類別是互動式畫布 API 的包裝函式。使用 scene.js 中的 create() 函式建立網頁應用程式時，系統會建立新的 Action 執行個體並呼叫 setCallbacks()，如以下程式碼片段所示：

scene.js

// Set Assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register Assistant Action callbacks.
this.assistant.setCallbacks();

setCallbacks() 函式是在 /public/js/action.js 的 Action 類別中定義。這個函式會宣告回呼，並在遊戲建立時，透過互動式畫布 API 註冊回呼：

  setCallbacks() {
    // Declare the Interactive Canvas Action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

setCallbacks() 函式會宣告 onUpdate() 回呼，每當您傳送 Canvas 回應時，系統都會呼叫回呼。

重要字詞：

• onUpdate()：每次傳送 Canvas 回應時執行的回呼。onUpdate() 可對應至會更新網頁應用程式的自訂邏輯。

下一節將說明這項專案的特定程式碼如何設定，以便將資料從對話動作傳送至網頁應用程式。

根據使用者輸入內容更新網頁應用程式

在本程式碼研究室中，您將使用指令對應，根據使用者輸入內容更新網頁應用程式。例如，當 start_game 意圖在 Welcome 場景中相符時，提示中的 canvas 回應就會傳送至網頁應用程式。onUpdate() 剖析 canvas 回應的中繼資料並呼叫 START_GAME 指令，而這個指令會呼叫 scene.js 中的 start() 函式，並更新網頁應用程式，開始新的遊戲工作階段。

scene.js 中的 start() 函式也會呼叫函式 updateCanvasState()，該函式使用名為 setCanvasState() 的方法，新增 Webhook 可存取的狀態資料。

重要字詞：

• setCanvasState()：這個方法可讓您將狀態資料從互動式畫布網頁應用程式傳送至 Webhook。網頁應用程式會以 JSON 物件的形式傳送更新狀態。

系統會在每個指令的結尾呼叫 updateCanvasState() 方法 (您會在程式碼研究室中一次新增這些指令)，並更新網頁應用程式的狀態。每次呼叫 updateCanvasState() 時，displayedWord 和 incorrectGuesses 的值都會根據目前的狀態更新：

scene.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

下次對話回合時，就能使用更新後的狀態。您可以在 Webhook 中透過 conv.context.canvas.state 存取此狀態，如以下程式碼片段所示：

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

6. 新增猜測功能

在本節中，您將新增 guess 功能至動作，讓使用者猜測字詞中的字母或字詞本身。

對話動作

在「Test in the Emulator」(模擬工具中) 部分中，您收到了一則回應內容，其中說明：「It like we need to add more features to which you't working」(我應該新增更多功能，才能正常運作)。現在，您可以在 Actions 主控台刪除該提示，確保您只呼叫 Webhook (在 Game 場景中，guess 意圖已設為在相符時發出 Webhook 呼叫)。

如要在 guess 意圖相符時移除靜態提示，請按照下列步驟操作：

1. 在「Actions」控制台中，按一下導覽列的「Scenes」。
2. 按一下「遊戲」，前往 Game 場景。
3. 在「User intent handle」(使用者意圖處理) 下方，按一下「When let is match」(在猜測時相符)。清除「傳送提示」即可移除提示。
4. 按一下 [儲存]。

Webhook

在本節中，您將使用邏輯將 Webhook 更新為將使用者正確或錯誤的猜測值對應到網頁應用程式檔案中的邏輯，接著即可依此更新網頁應用程式。我們已在 Webhook 中為您設定 guess 意圖處理常式，因此您只需在這個意圖中加入 Canvas 回應，即可觸發更新網頁應用程式的邏輯。

如要更新 Webhook，請按照下列步驟操作：

1. 在「Actions」主控台中，按一下導覽列中的「Webhook」。
2. 將下列程式碼新增至 guess 處理常式下的 index.js：

注意：在本程式碼研究室中，您新增的程式碼片段會分為按字母順序排列的區段。您修改的檔案會包含註解，指明每個程式碼片段應加入的位置 (例如 // Add section F } here)。在註解行後方新增對應的程式碼片段。

index.js (第 A 部分)：

// Add Section A `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (第 B 部分)：

// Add Section B `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));

3. 按一下「Save Fulfillment」(儲存執行要求)。
4. 按一下「Deploy Fulfillment」(部署執行要求)。部署完成後，系統會顯示「Your Cloud Function deploy is up is the date」(您的 Cloud 函式部署為最新版本) 的訊息。

網頁應用程式

您現在可以設定網頁應用程式來處理 CORRECT_ANSWER 和 INCORRECT_ANSWER 指令。

1. 在文字編輯器中開啟 public/js/action.js。
2. 更新網頁應用程式以處理 CORRECT_ANSWER 和 INCORRECT_ANSWER 指令：

action.js (第 C 節)：

// Add Section C `CORRECT_ANSWER: (params) => {` content here.
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },

3. 執行下列指令來更新網頁應用程式：

firebase deploy --project {PROJECT_ID} --only hosting

在模擬工具中測試動作

此時，您的動作可以辨識猜測是否正確或不正確，並據此更新網頁應用程式。

如要測試動作，請按照下列步驟操作：

1. 按一下導覽列中的「測試」。
2. 在「Input」欄位中輸入 Talk to Snow Pal sample，然後按下 Enter 鍵。
3. 在「Input」欄位中輸入 Yes，然後按下 Enter 鍵。您也可以按一下「Yes」按鈕。
4. 在「Input」欄位中輸入要猜測的字母，然後按下 Enter 鍵。

瞭解程式碼

在上一節中，您已新增程式碼，讓使用者猜測遊戲中的字母，並看到「Snow Pal」字詞或「Snow Pal」字樣的猜測結果。整體來說，如果符合 guess 意圖，您會在 Actions Builder 中發出 Webhook 呼叫，進而將資料傳送給網頁應用程式據此更新。舉例來說，如果使用者猜測「雪花白」遊戲中的字母「雪花白」這個字詞，那麼網頁應用程式就會更新，在字詞中的正確位置顯示字母。

針對使用互動式畫布的動作，以下是資料從 Webhook 傳送至網頁應用程式的一般流程：

1. 使用者的輸入內容與包含 Canvas 回應的意圖相符。
2. 對話動作或 Webhook 會傳送 Canvas 回應，進而觸發 onUpdate() 回呼。
3. onUpdate() 回呼會對應至可據此更新網頁應用程式的自訂邏輯。

重要字詞：

• onUpdate()：每次執行要求傳送 Canvas 回應. onUpdate() 時，都會執行的回呼可對應至會更新網頁應用程式的自訂邏輯。

在這個特定專案中，程式碼的運作方式如下：

1. 當使用者符合 guess 意圖時，動作建構工具會從使用者輸入內容中擷取字母做為參數。
2. 動作建構工具會呼叫 Webhook 中的 guess 處理常式，該處理常式含有的邏輯，用於判斷使用者猜測的字母是否出現在字詞中。
3. guess 處理常式包含兩個 Canvas 回應，一個在字母正確時執行，一個在字母不正確時執行。每個 Canvas 回應都會將適當的資料 (CORRECT_ANSWER 或 INCORRECT_ANSWER 指令) 傳遞至網頁應用程式。
4. Canvas 回應 data 欄位包含的資料會傳遞到 action.js 中的 onUpdate() 方法。onUpdate() 會在 scene.js 的指令對應中呼叫適當的指令。
5. 指令對應對應至 scene.js 中的 correctAnswer() 和 incorrectAnswer() 函式。這些函式可妥善更新網頁應用程式，反映使用者的猜測結果，並呼叫 setCanvasState()，將狀態資料從網頁應用程式傳送至 Webhook。

7. 新增獲勝/失敗功能

在本節中，您將新增獲勝和失去的功能至動作動作，包括決定使用者是否贏得或失敗的邏輯，以及根據使用者結果更新網頁應用程式圖片的邏輯。

對話動作

系統會在 guess 意圖內設定可處理使用者勝利或落敗遊戲的功能，因此您不必在 Actions Builder 中進行任何其他設定。

Webhook

在本節中，您將使用邏輯來更新 Webhook，以處理使用者贏得遊戲或遺失遊戲的情況，並對應至網頁應用程式邏輯，讓應用程式邏輯可用適當的勝出或遺失畫面來更新遊戲。

如要更新 Webhook，請按照下列步驟操作：

1. 在「Actions」主控台中，按一下導覽列中的「Webhook」。
2. 將下列程式碼新增至 guess 處理常式下的 index.js：

index.js (第 D 節)：

// Add Section D `if (userHasWon)` content here.
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!  
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (E 部分)：

注意：在本節中，您將新增右括弧來關閉程式碼區塊。

// Add Section E `}` here.
}

index.js (第 F 節)：

// Add Section F `Check if the user has exceeded the maximum` content here.
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (G 部分)：

注意：在本節中，您將新增右括弧來關閉程式碼區塊。

// Add Section G `}` here.
}

3. 按一下「Save Fulfillment」(儲存執行要求)。
4. 按一下「Deploy Fulfillment」(部署執行要求)。部署完成後，系統會顯示「Your Cloud Function deploy is up is the date」(您的 Cloud 函式部署為最新版本) 的訊息。

在這裡，您已使用 WIN_GAME 和 LOSE_GAME 指令新增兩個 Canvas 回應，用於處理使用者獲勝或失敗遊戲的時間。在下一節中，您將新增功能，根據使用者能否贏得遊戲更新，以更新網頁應用程式。

網頁應用程式

您現在可以設定網頁應用程式，根據使用者是否獲勝或失敗更新。如要更新網頁應用程式，請按照下列步驟操作：

1. 在文字編輯器中開啟 public/js/action.js。
2. 更新網頁應用程式，以便處理 WIN_GAME 和 LOSE_GAME 指令：

action.js (第 H 節)：

// Add Section H `WIN_GAME: (params) => {` content here.
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },

3. 執行下列指令來更新網頁應用程式：

firebase deploy --project {PROJECT_ID} --only hosting

在模擬工具中測試動作

此時，您的動作可以處理使用者勝利或輸掉遊戲的情況，並且針對每項結果顯示適當的畫面。

如要測試動作，請按照下列步驟操作：

1. 按一下 Actions 主控台導覽列中的「測試」。
2. 在「Input」欄位中輸入 Talk to Snow Pal sample，然後按下 Enter 鍵。
3. 在「Input」欄位中輸入 Yes，然後按下 Enter 鍵。您也可以按一下「開始遊戲」按鈕。
4. 會猜出字母和單字，直到你贏取或輸掉。

如果你要求再播放一次，系統會顯示訊息，指出尚未新增再次播放所需的必要功能。您將在下一節新增此功能。

瞭解程式碼

勝出和損失功能的運作方式與猜測功能相同：使用者符合 guess 意圖，Webhook 就會評估使用者的猜測字詞。如果猜對，程式碼會檢查使用者是否贏了。如果已設定，WIN_GAME 指令就會傳送至網頁應用程式。如果猜錯，程式碼會確認他們是否已遺失。如果有的話，LOSE_GAME 指令就會傳送至網頁應用程式。這些指令會觸發 scene.js 中的 winGame() 和 loseGame() 函式，這會更新網頁應用程式，以顯示獲勝或遺失畫面，並更新遊戲狀態。

8. 新增「再玩一次」功能

在本節中，您可以新增功能，讓使用者說出「再玩一次」，或是在網頁應用程式中點選「再玩一次」按鈕，開始新遊戲。您修改了動作建構工具中的 play_again 意圖，以傳送可適當更新網頁應用程式的 canvas 回應，並新增會在使用者點選「Play Again」按鈕時觸發 play_again 意圖的邏輯。

對話動作

在上一節測試動作動作時，如果嘗試再玩一次遊戲，系統會顯示以下提示：「太好了，但我們會在後續章節建構這項功能。但現在只要重設動作即可。"您現在可以刪除這個提示，並替換成使用者要求其他遊戲時回覆的提示 (「好吧，那場遊戲！」)，並加入 canvas 回應，藉此觸發網頁應用程式開始新遊戲。

如要在使用者要再玩一次時更新提示，請按照下列步驟操作：

1. 在「Actions」控制台中，按一下「Scene」下拉式選單。
2. 按一下「遊戲」場景。
3. 在「User intent handle」(使用者意圖處理) 下方，按一下「When if play_again is match」(當 Play_again 相符時)。
4. 將提示替換成以下內容：

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here''s another game!' 
    canvas:
      sendStateDataToCanvasApp: true

5. 按一下 [儲存]。

Webhook

在本程式碼研究室中，Webhook 會管理遊戲邏輯。因為 Play-Play 功能不需要任何類型的邏輯驗證，因此您不需要呼叫 Webhook。您可以直接從 Actions Builder 傳送 canvas 回應，將必要資料傳送至網頁應用程式 (已於上一節進行設定)。

網頁應用程式

您現在可以修改網頁應用程式檔案，在使用者要求再次播放時適當更新。如要新增這項功能，請按照下列步驟操作：

1. 在文字編輯器中開啟 public/js/action.js。
2. 更新網頁應用程式以處理 PLAY_AGAIN 指令：

action.js (第 I 節)：

// Add Section I `PLAY_AGAIN: (params) => {` content here.
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },

3. 在文字編輯器中開啟 public/js/scene.js。
4. 更新網頁應用程式，在使用者點選「再玩一次」時啟動新的遊戲工作階段按鈕：

show.js (第 J 節)：

// Add Section J `sendTextQuery` content here.
     window.interactiveCanvas.sendTextQuery('Play again');

5. 執行下列指令來更新網頁應用程式：

firebase deploy --project {PROJECT_ID} --only hosting

在模擬工具中測試動作

現在使用者說出「再玩一次」或點選「再玩一次」按鈕後，動作就能開始新的遊戲工作階段。

如要測試動作，請按照下列步驟操作：

1. 按一下導覽列中的「測試」。
2. 在「Input」欄位中輸入 Talk to Snow Pal sample，然後按下 Enter 鍵。
3. 在「Input」欄位中輸入 Yes，然後按下 Enter 鍵。您也可以按一下「開始遊戲」按鈕。
4. 會猜出字母和單字，直到你贏取或輸掉。
5. 在「Input」欄位中輸入 Play again，然後按下 Enter 鍵。或者，您也可以按一下「再玩一次」按鈕。

瞭解程式碼

測試動作時，您可以透過語音輸入 (「再玩一次」) 或觸控輸入 (按一下「再播放」按鈕) 開始新遊戲。

以語音輸入選項來說，當使用者說出「再玩一次」或其中一些變化形式時，系統會比對出 play_again 意圖，並在提示佇列中新增提示 (「Okay，歡迎使用另一個遊戲！」)。提示中包含的 canvas 回應會將意圖名稱和其他中繼資料傳送至網頁應用程式。意圖名稱會傳遞至 onUpdate() 回呼，後者會將對應的指令 PLAY_AGAIN 對應至 action.js 中的指令對應。PLAY_AGAIN 指令會在 scene.js 中觸發 start() 函式，並使用新的遊戲工作階段更新網頁應用程式。

針對觸控輸入選項，請使用 sendTextQuery() 這個互動式 Canvas API，可讓您透過觸控輸入來觸發意圖，讓按鈕正常運作。

重要字詞：

• sendTextQuery()：這個方法可將文字查詢傳送至對話動作，透過程式輔助方式叫用意圖。

在本程式碼研究室中，您將使用 sendTextQuery() 在使用者點選「再玩一次」按鈕時叫用 play_again 意圖。Play again 引數會比對 play_again 意圖中的訓練詞組，並以使用者說出「再玩一次」的方式觸發這項意圖。接著，play_again 意圖會觸發邏輯來更新網頁應用程式，並啟動新的遊戲工作階段。

9. 更新 PLAY_GAME 內建意圖

在本節中，您將更新 PLAY_GAME 內建意圖。

重要字詞：

• 內建意圖：這是一組專屬 ID，你可以指定這組專屬 ID，告訴 Google 助理動作能滿足特定類別的使用者要求。

PLAY_GAME 內建意圖可讓使用者在提出一般要求時叫用動作，例如「我想玩遊戲」。

原始碼包含位於 /sdk/custom/global/actions.intent.PLAY_GAME.yaml 的 PLAY_GAME 內建意圖。這項變更會反映在控制台的「Invocation」區段，如「PLAY_GAME」，如下方螢幕截圖所示：

如要讓使用者能透過這個內建意圖叫用動作，您需要將含有網頁應用程式網址的 canvas 回應新增至 PLAY_GAME 內建意圖。步驟如下：

1. 在動作控制台中按一下導覽列中的「PLAY_GAME」PLAY_GAME。
2. 更新提示，加入網頁應用程式網址，如以下程式碼片段所示：

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

3. 按一下 [儲存]。

在模擬工具中測試動作

您的動作現在支援 PLAY_GAME 內建意圖。

如要測試動作，請按照下列步驟操作：

1. 按一下導覽列中的「測試」。
2. 按一下「測試內建意圖處理」。
3. 按一下「叫用動作」。

請在模擬器中叫用您的動作。

10. 附錄：排解互動式畫布動作的問題

本節將說明如何在互動畫布動作無法正常運作時進行偵錯。Snow Pal 專案已預先封裝偵錯疊加層，您可視需要啟用。疊加畫面會在螢幕右下方顯示所有 console.log() 和 console.error() 輸出內容，如以下螢幕截圖所示：

如要啟用這個疊加層，請開啟 /public/css/main.css 檔案，在 display: none !important; 行加上註解，如以下程式碼片段所示：

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

清理專案 [建議]

如要避免產生可能產生的費用，建議您移除不想使用的專案。如要刪除您在本程式碼研究室中建立的專案，請按照下列步驟操作：

1. 如要刪除 Google Cloud 專案和資源，請完成「關閉 (刪除) 專案」一節所列的步驟。

注意：請務必在 Google Cloud Platform 的「設定」頁面中，選取正確的要刪除的專案。

2. 選用：如要立即將專案從 Actions 主控台中移除，請完成「刪除專案」一節中列出的步驟。如未完成這個步驟，系統將在約 30 天後自動移除專案。

11. 恭喜！

您已完成互動式畫布入門程式碼研究室，現在具備建構互動式畫布動作所需的技能。

目前所學內容

• 如何建構、部署及測試互動式畫布動作
• 如何使用 Canvas 回應更新網頁應用程式
• 如何透過不同方法強化動作，例如 sendTextQuery() 和 setCanvasState()
• 如何偵錯動作

瞭解詳情

如要進一步瞭解互動式畫布，請參閱下列資源：

• 互動式畫布說明文件：互動式畫布的官方 Actions on Google 說明文件。
• 互動式畫布範例：這個互動式畫布遊戲的程式碼可讓您旋轉三角形並修改顏色。
• 遊戲入口網站：在 Google 助理上建構遊戲的規範。

意見回饋問卷調查

離開前，請先填寫一份簡短的問卷調查，告訴我們你的使用體驗。