Kể từ ngày 13 tháng 6 năm 2023, Hành động trò chuyện không còn được dùng nữa. Để biết thêm thông tin, hãy xem phần Hành động trò chuyện ngừng hoạt động.

Trang này được dịch bởi Cloud Translation API.

Câu lệnh trên Canvas

Để chuyển tiếp thông tin đến ứng dụng web, bạn phải gửi một phản hồi Canvas dựa trên logic trò chuyện. Phản hồi Canvas có thể thực hiện một trong những việc sau:

Hiển thị ứng dụng web toàn màn hình trên thiết bị của người dùng
Truyền dữ liệu để cập nhật ứng dụng web

Các phần sau đây mô tả cách trả về phản hồi Canvas cho mỗi lần truy cập trong trường hợp này.

Bật Canvas tương tác

Bạn phải định cấu hình Hành động của mình theo cách cụ thể để sử dụng Canvas tương tác. Để tạo một Hành động sử dụng Canvas tương tác, bạn cần bổ sung thêm cấu hình trong Bảng điều khiển Actions (và đối với SDK Actions, các sửa đổi đối với tệp settings.yaml). Để xem toàn bộ quy trình tạo và định cấu hình Thao tác Canvas tương tác bằng SDK Actions, xem Tạo một dự án.

Khi sử dụng Trình tạo hành động, hãy làm theo các bước bổ sung sau để bật chế độ Tương tác Canvas:

Nếu bạn không chọn thẻ Trò chơi trong mục Loại hành động nào bạn có muốn tạo không?, hãy nhấp vào Triển khai trong thanh điều hướng trên cùng. Trong Thông tin bổ sung, chọn Trò chơi và thú vị. Nhấp vào Lưu.
Nhấp vào Phát triển trong thanh điều hướng trên cùng của Bảng điều khiển Actions.
Nhấp vào Canvas tương tác trong điều hướng bên trái.
Trong phần Bạn có muốn Hành động của mình sử dụng Canvas tương tác?, hãy chọn một trong như sau:
- Bật Canvas tương tác bằng phương thức thực hiện webhook của máy chủ. Lựa chọn này dựa vào webhook để truy cập một số tính năng nhất định và thường xuyên sử dụng onUpdate() để truyền dữ liệu vào ứng dụng web. Khi được bật, các kết quả trùng khớp về ý định sẽ được xử lý trong cảnh và bạn có thể chọn gọi webhook trước khi chuyển đổi sang một cảnh khác hoặc kết thúc cuộc trò chuyện.
- Bật Canvas tương tác với phương thức thực hiện cho ứng dụng. Tùy chọn này cho phép bạn chuyển logic phương thức thực hiện webhook sang ứng dụng web và giới hạn chỉ gọi đến các tính năng trò chuyện yêu cầu webhook chẳng hạn như liên kết tài khoản. Khi được bật, bạn có thể sử dụng expect() để đăng ký trình xử lý ý định ở phía máy khách.
Không bắt buộc: Nhập URL ứng dụng web của bạn vào mục Đặt URL ứng dụng web mặc định . Thao tác này sẽ thêm phản hồi Canvas mặc định có trường URL vào lệnh gọi Chính của bạn.
Nhấp vào Lưu.

Khi sử dụng SDK hành động, hãy thực hiện theo các bước bổ sung sau để bật chế độ Tương tác Canvas:

Đặt trường category trong tệp settings.yaml thành GAMES_AND_TRIVIA để mô tả chính xác nhất và giúp người dùng khám phá Hành động của bạn.
Đặt trường usesInteractiveCanvas trong tệp settings.yaml thành true.

Kiểm tra khả năng của bề mặt

Khung Canvas tương tác chỉ chạy trên các thiết bị có Trợ lý cung cấp một giao diện trực quan, nên Hành động của bạn cần kiểm tra INTERACTIVE_CANVAS chức năng trên thiết bị của người dùng. Khi bạn xác định lời nhắc trong Trình tạo thao tác, bạn có thể chỉ định danh sách khả năng của thiết bị trong trường selector của Đối tượng candidates. Bộ chọn câu lệnh sẽ chọn đề xuất câu lệnh phù hợp nhất phù hợp với khả năng thiết bị của người dùng.

Để trả về phản hồi Canvas, logic của Hành động phải thực hiện như sau:

Kiểm tra để đảm bảo rằng thiết bị của người dùng hỗ trợ chức năng INTERACTIVE_CANVAS. Nếu có, hãy gửi cho người dùng phản hồi Canvas.
Nếu không thể sử dụng tính năng Canvas tương tác, hãy kiểm tra xem thiết bị hỗ trợ tính năng RICH_RESPONSE. Nếu có, hãy gửi cho người dùng phản hồi đa dạng thức.
Nếu không có tính năng phản hồi nhiều định dạng, hãy gửi cho người dùng phản hồi đơn giản.

Các đoạn mã sau đây trả về phản hồi thích hợp dựa trên khả năng trên thiết bị của người dùng:

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.');
}

Kết xuất ứng dụng web

Một Hành động sử dụng Canvas tương tác bao gồm một ứng dụng web có hình ảnh mà bạn gửi cho người dùng dưới dạng phản hồi. Sau khi ứng dụng web hiển thị, người dùng tiếp tục tương tác với Gemini bằng giọng nói, văn bản hoặc bằng thao tác chạm cho đến khi cuộc trò chuyện đã kết thúc.

Phản hồi Canvas đầu tiên của bạn phải chứa URL của ứng dụng web. Loại Phản hồi của Canvas yêu cầu Trợ lý Google hiển thị ứng dụng web tại địa chỉ đó trên thiết bị của người dùng. Thông thường, bạn gửi Canvas phản hồi đầu tiên ngay sau khi người dùng gọi Hành động của bạn. Khi ứng dụng web tải, Thư viện Canvas tương tác sẽ tải, còn ứng dụng web đăng ký một trình xử lý gọi lại bằng Interactive Canvas API.

Bạn có thể chỉ định URL của ứng dụng web trong Trình tạo hành động, như minh hoạ trong ảnh chụp màn hình sau đây:

Nếu bạn tạo một câu lệnh có phản hồi Canvas sau khi chỉ định URL của ứng dụng web, Trình tạo thao tác sẽ tự động điền vào trường URL của phản hồi Canvas. Để biết thêm thông tin về cách đặt URL ứng dụng web trong bảng điều khiển, hãy xem Mục Enable Interactive Canvas (Bật Canvas tương tác).

Các đoạn mã sau đây cho biết cách tạo phản hồi Canvas sẽ hiển thị ứng dụng web trong cả Trình tạo hành động và webhook của bạn:

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"
    }
  }
}

Truyền dữ liệu để cập nhật ứng dụng web

Sau khi gửi phản hồi Canvas ban đầu, bạn có thể sử dụng Canvas bổ sung phản hồi để cung cấp nội dung cập nhật cho data mà logic tuỳ chỉnh của ứng dụng web sử dụng để thay đổi ứng dụng web của bạn. Khi bạn gửi một phản hồi Canvas đạt yêu cầu dữ liệu của bạn lên ứng dụng web, thì các bước sau đây sẽ diễn ra:

Khi ý định được so khớp trong một cảnh, ý định đó sẽ kích hoạt một sự kiện và phản hồi Canvas chứa trường data có tải trọng JSON sau đó được gửi lại dưới dạng phản hồi.
Trường data được chuyển đến lệnh gọi lại onUpdate và dùng để cập nhật ứng dụng web.
Hành động trò chuyện của bạn có thể gửi một phản hồi Canvas mới và cung cấp thông tin trong trường data để gửi nội dung cập nhật mới hoặc tải trạng thái mới.

Lưu ý: Nếu giá trị của trường url thay đổi trong phương thức thực hiện tiếp theo phản hồi, ứng dụng web sẽ tải lại. Nếu bạn cung cấp cùng một giá trị cho url hoặc nếu url bị loại trừ như một phần của phản hồi tiếp theo, thì ứng dụng web hiện có được lưu trên thiết bị.

Bạn có thể chuyển dữ liệu đến ứng dụng web theo hai cách:

Bằng Trình tạo hành động. Trình tạo hành động sẽ tự động điền trường data trong phản hồi của Canvas kèm theo siêu dữ liệu cần thiết để cập nhật ứng dụng web.
Bằng webhook. Nếu có webhook, bạn có thể định cấu hình dữ liệu tuỳ chỉnh để cập nhật ứng dụng web trong phản hồi Canvas.

Các phần sau đây mô tả cách chuyển dữ liệu thông qua Trình tạo hành động và webhook.

Sử dụng Trình tạo thao tác để truyền dữ liệu

Nhờ Trình tạo hành động, bạn không cần xác định webhook để quản lý siêu dữ liệu được gửi đến ứng dụng web của bạn. Thay vào đó, khi bạn định cấu hình trình xử lý ý định trong giao diện người dùng Trình tạo thao tác, bạn có thể đưa vào phản hồi Canvas. Đáp Trường data được tự động điền siêu dữ liệu cần thiết để cập nhật ứng dụng web của bạn, chẳng hạn như tên ý định, bất kỳ tham số nào được thu thập từ hoạt động đầu vào của người dùng, và cảnh hiện tại.

Ví dụ: trình xử lý ý định Guess sau đây cho biết rằng bạn muốn thêm Canvas trả lời:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true

JSON

{
  "candidates": [
    {
      "canvas": {
        "send_state_data_to_canvas_app": true
      }
    }
  ]
}

Bạn có thể tuỳ ý thêm đoạn mã sau vào trình xử lý ý định để gửi một Tin nhắn TTS:

...
  - first_simple:
      variants:
        - speech: Optional message.

Trình tạo thao tác tự động mở rộng phản hồi Canvas có siêu dữ liệu sang hãy cập nhật ứng dụng web như minh hoạ trong các đoạn mã sau đây. Trong trường hợp này, người dùng đã đoán chữ cái "a" trong trò chơi đoán từ:

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
      }
    }
  ]
}

Phản hồi này sẽ cập nhật ứng dụng web của bạn với câu trả lời của người dùng và chuyển đổi sang cảnh phù hợp.

Sử dụng webhook của bạn để chuyển dữ liệu

Bạn có thể thiết lập trường data gồm Canvas phản hồi theo cách thủ công trong webhook với thông tin trạng thái cần thiết để cập nhật ứng dụng web của bạn. Phương pháp này được đề xuất nếu bạn cần đưa một tải trọng data tuỳ chỉnh vào phản hồi Canvas thay vì chỉ chuyển siêu dữ liệu thông thường cần thiết để cập nhật ứng dụng web.

Các đoạn mã sau đây cho biết cách truyền dữ liệu trong phản hồi Canvas trong webhook:

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": ""
    }
  }
}

Nguyên tắc và quy định hạn chế

Hãy ghi nhớ các nguyên tắc và quy định hạn chế sau đây đối với Canvas câu trả lời khi xây dựng Hành động:

Mỗi trình xử lý webhook trong phương thức thực hiện của bạn phải bao gồm Canvas. Nếu webhook phản hồi không bao gồm Canvas, ứng dụng web của bạn sẽ đóng.
Bạn chỉ cần bao gồm URL ứng dụng web của mình trong Canvas phản hồi đầu tiên mà bạn gửi cho người dùng.
URL phản hồi Canvas phải hợp lệ và giao thức của URL phải là https.
Phản hồi của Canvas phải có kích thước từ 50 KB trở xuống.