對話動作將於 2023 年 6 月 13 日淘汰。詳情請參閱對話動作停用。

畫布提示

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

如要傳送資訊至網頁應用程式，您必須從對話邏輯傳送 Canvas 回應。Canvas 回應可採取下列任一做法：

  • 在使用者的裝置上轉譯全螢幕網路應用程式
  • 傳遞資料以更新網頁應用程式

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

啟用互動式畫布

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

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

  1. 如果您未在「What do you want to build?」畫面中選取「Game」資訊卡。請按一下頂端導覽中的「Deploy」。在「其他資訊」之下，選取 [遊戲和娛樂] 類別。 按一下 [Save] (儲存)。
  2. 按一下動作控制台頂端導覽列中的 [開發]。
  3. 在左側導覽面板中按一下 [互動式畫布]。
  4. 在「要讓動作使用互動式畫布嗎？」下方，選取下列其中一個選項：
    • 透過伺服器 Webhook 執行功能啟用互動式畫布。這個選項依賴 Webhook 來存取特定功能，且經常使用 onUpdate() 將資料傳送至網頁應用程式。啟用之後，系統會在場景中處理意圖比對，您可以選擇在轉換到其他場景或結束對話之前呼叫 Webhook。
    • 透過用戶端執行功能啟用互動式畫布。這個選項可讓您將 Webhook 出貨邏輯移至網路應用程式，並將 Webhook 呼叫限制為僅限需要該對話的對話功能，例如帳戶連結。啟用後，您可以使用 expect() 在用戶端註冊意圖處理常式。
  5. 選用：在「Set your default web app URL」(設定您的預設網路應用程式網址) 欄位中，輸入網頁應用程式網址。這個動作會將預設的網址欄位 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 回應必須包含網頁應用程式的網址。這種 Canvas 回應會指示 Google 助理在使用者裝置上以該地址顯示網頁應用程式。一般而言，您會在使用者叫用動作後立即傳送第一個 Canvas 回應。載入網路應用程式時，互動式 Canvas 程式庫會載入，而網路應用程式會使用互動式 Canvas API 註冊回呼處理常式。

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

如果您在指定網路應用程式網址後，建立了包含 Canvas 回應的提示，動作製作工具就會自動填入 Canvas 回應的網址欄位。如要進一步瞭解如何在主控台中設定網頁應用程式網址，請參閱啟用互動式畫布一節。

下列程式碼片段說明如何建構 Canvas 回應，在 Action 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. 當意圖在情境中相符時，就會觸發事件，並將包含 JSON 酬載的 data 欄位的 Canvas 回應做為回應傳回。
  2. data 欄位會傳遞到 onUpdate 回呼，並用於更新網頁應用程式。

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

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

  • 使用動作建立工具。Actions Builder 會在 Canvas 回應的 data 回應中自動填入必要的中繼資料，以更新網路應用程式。
  • 使用 Webhook。如果您有 Webhook，可以設定自訂資料酬載，以更新 Canvas 回應中的網頁應用程式。

以下各節說明如何透過 Actions Builder 和 Webhook 傳遞資料。

使用動作建立工具傳送資料

有了 Actions Builder，您不需要定義 Webhook 來管理傳送至網路應用程式的中繼資料，而是透過 Actions Builder 使用者介面設定意圖處理常式，改為加入 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 中，使用必要的狀態資訊在 Webhook 中手動設定 data 回應的 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。