畫布提示

如要將資訊轉發至您的網頁應用程式，則必須從對話邏輯傳送 Canvas 回應。Canvas 回應可以執行下列其中一項操作：

  • 在使用者的裝置上顯示全螢幕網頁應用程式
  • 傳送資料以便更新網頁應用程式

以下各節說明如何傳回每個情境的 Canvas 回應。

啟用互動式畫布

你必須以特定方式設定動作才能使用互動式畫布。如要建立使用互動式畫布的動作，您必須在 Actions 主控台進行其他設定 (以及針對 SDK SDK 修改 settings.yaml 檔案)。如要查看使用 Actions SDK 建立及設定互動式 Canvas 動作的完整程序，請參閱建立專案。

使用 Actions Builder 時，請按照下列步驟啟用互動式畫布：

  1. 如果您未在「您想建構的動作類型」畫面中選取「遊戲」資訊卡，請在頂端導覽列中按一下「部署」。 在「其他資訊」下方，選取「遊戲與娛樂」類別。 按一下 [Save] (儲存)。
  2. 按一下「動作」控制台頂端導覽選單的「開發」。
  3. 按一下左側導覽列中的 [互動式畫布]。
  4. 在「是否您希望動作使用互動式畫布？」下方，選取下列其中一個選項：
    • 透過伺服器 Webhook 執行要求啟用互動式畫布。這個選項需要使用 Webhook 來存取特定功能，並且經常使用 onUpdate() 將資料傳送至網頁應用程式。啟用後，系統會在背景處理意圖比對事件，您可以選擇在轉換至其他場景或結束對話之前呼叫 Webhook。
    • 啟用含有用戶端執行要求的互動式畫布。這個選項可讓您將 Webhook 執行要求邏輯移至網頁應用程式，並限制 Webhook 呼叫僅適用於需要此功能的對話功能，例如帳戶連結。啟用後，您可以使用 expect() 在用戶端上註冊意圖處理常式。
  5. 選用：在「設定預設網頁應用程式網址」欄位中輸入網頁應用程式的網址。這個動作會在主要叫用中加入預設含有網址欄位的 Canvas 回應。
  6. 按一下「儲存」。

使用 Actions SDK 時，請按照下列步驟啟用互動式畫布：

  1. 在 settings.yaml 檔案中，將 category 欄位設為 GAMES_AND_TRIVIA 來描述並讓使用者發現您的動作。
  2. 將 settings.yaml 檔案中的 usesInteractiveCanvas 欄位設為 true。

檢查表面功能

互動式 Canvas 架構只會在提供視覺介面的 Google 助理裝置上運作，因此動作必須檢查使用者裝置上的 INTERACTIVE_CANVAS 功能。在 Actions Builder 中定義提示時，您可以在 candidates 物件的 selector 欄位中指定裝置功能清單。提示選取器會選取最適合使用者裝置功能的提示候選選項。

如要傳回 Canvas 回應，動作的邏輯應執行以下操作：

  1. 檢查使用者的裝置是否支援 INTERACTIVE_CANVAS 功能。如果支援，請將 Canvas 回應傳送給使用者。
  2. 如果無法使用互動式畫布，請檢查使用者的裝置是否支援 RICH_RESPONSE 功能。如果可以，請改將複合式回應傳送給使用者。
  3. 如果無法使用複合式回應功能，請將簡易回應傳送給使用者。

以下程式碼片段會根據使用者的裝置功能傳回適當的回應：

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 程式庫會載入，網頁應用程式則會使用 Interactive Canvas API 註冊回呼處理常式。

您可以在 Action Builder 中指定網頁應用程式的網址，如以下螢幕截圖所示：

如果您在建立網頁應用程式網址後建立包含 Canvas 回應的提示，動作建構工具會自動填入 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 回應將資料傳送至網頁應用程式時，請按照下列步驟操作：

  1. 當意圖在場景中相符時，就會觸發事件，並回傳 Canvas 回應，其中含有 JSON 酬載的 data 欄位做為回應。
  2. data 欄位會傳遞至 onUpdate 回呼，並用於更新網頁應用程式。

  3. 對話動作可傳送新的 Canvas 回應，並在 data 欄位中提供相關資訊，以便傳送新更新或載入新狀態。

你可以透過下列兩種方式將資料傳送至網頁應用程式：

  • 使用 Actions Builder。Actions Builder 會在 Canvas 回應中自動填入 data 欄位，並提供更新網頁應用程式所需的中繼資料。
  • 使用 Webhook。如果您有 Webhook，可以設定自訂資料酬載以更新 Canvas 回應中的網頁應用程式。

以下各節將說明如何透過 Actions 建構工具和 Webhook 傳遞資料。

使用 Actions Builder 傳遞資料

使用 Actions Builder 時，您不必定義 Webhook 即可管理傳送至網頁應用程式的中繼資料。在動作建構工具 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。