Canvas 提示

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

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

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

啟用互動式畫布

您必須以特定方式設定動作，才能使用互動式畫布。如要建立使用互動式畫布的動作，您必須透過 Actions 主控台進行額外設定；而針對 Actions SDK，您必須修改 settings.yaml 檔案。如要查看使用 Actions SDK 建立及設定互動式畫布動作的完整程序，請參閱「建立專案」。

使用動作建構工具時，請按照下列額外步驟啟用互動式畫布：

  1. 如果您沒有在「What type of Action to build?」畫面中選取「Game」資訊卡，請按一下頂端導覽列的「Deploy」。 在「其他資訊」下方，選取「遊戲與娛樂」類別。按一下 [儲存]。
  2. 按一下動作主控台頂端導覽列中的「Develop」。
  3. 按一下左側導覽面板中的「互動畫布」。
  4. 在「Do you want your Action to use Interactive Canvas?」(您要讓動作使用互動式畫布嗎？) 下方，選取下列其中一個選項：
    • 啟用具備伺服器 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。

檢查介面功能

互動式畫布架構只會在提供視覺化介面的 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 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 回應時，會發生下列步驟：

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

  3. 對話動作可以傳送新的 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。