Để chuyển tiếp thông tin đến ứng dụng web, bạn phải gửi phản hồi Canvas
từ logic trò chuyện. Phản hồi Canvas
có thể thực hiện một trong những thao tá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 từng trường hợp.
Bật Canvas tương tác
Bạn phải định cấu hình Hành động của mình theo một cách cụ thể để sử dụng Canvas tương tác.
Việc tạo một Hành động sử dụng Canvas tương tác yêu cầu phải định cấu hình bổ sung trong bảng điều khiển Actions (và đối với SDK Hành động, hãy sửa đổi tệp settings.yaml
). Để xem quy trình đầy đủ để tạo và định cấu hình Thao tác Canvas tương tác bằng SDK Thao tác, hãy xem phần Tạo dự án.
Khi sử dụng Trình tạo thao tác, hãy làm theo các bước bổ sung sau để bật Canvas tương tác:
- Nếu bạn không chọn thẻ Trò chơi trên màn hình Bạn muốn xây dựng loại hành động nào?, hãy nhấp vào Deploy (Triển khai) trong thanh điều hướng trên cùng. Trong Thông tin bổ sung, hãy chọn danh mục 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 bảng đ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 không?, hãy chọn một trong các tuỳ chọn sau:
- Bật Canvas tương tác với phương thức thực hiện webhook của máy chủ. Tuỳ 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 sử dụng
onUpdate()
để truyền dữ liệu vào ứng dụng web. Khi được bật, các lượt so khớp ý định sẽ được xử lý trong các cảnh và bạn có thể chọn gọi webhook trước khi chuyển 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 ứng dụng. Tuỳ chọn này cho phép bạn di chuyển logic thực hiện webhook sang ứng dụng web và giới hạn lệnh gọi webhook chỉ ở các tính năng trò chuyện cần đến nó, chẳng hạn như liên kết tài khoản. Khi bật, bạn có thể sử dụng
expect()
để đăng ký trình xử lý ý định ở phía máy khách.
- Bật Canvas tương tác với phương thức thực hiện webhook của máy chủ. Tuỳ 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 sử dụng
- Không bắt buộc: Nhập URL ứng dụng web vào trường Đặ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 với trường URL vào lệnh gọi chính. - Nhấp vào Lưu.
Khi sử dụng SDK Hành động, hãy làm theo các bước bổ sung sau để bật Canvas tương tác:
- Đặt trường
category
trong tệpsettings.yaml
thànhGAMES_AND_TRIVIA
để mô tả và giúp người dùng khám phá Hành động của bạn một cách chính xác nhất. - Đặt trường
usesInteractiveCanvas
trong tệpsettings.yaml
thànhtrue
.
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ý có cung cấp giao diện trực quan, vì vậy, Hành động của bạn cần kiểm tra chức năng INTERACTIVE_CANVAS
trên thiết bị của người dùng. Khi xác định lời nhắc trong Trình tạo hành động, bạn có thể chỉ định danh sách các chức năng của thiết bị trong trường selector
của đối tượng candidates
. Bộ chọn lời nhắc sẽ chọn đề xuất lời nhắc phù hợp nhất với khả năng của thiết bị của người dùng.
Để trả về phản hồi Canvas
, logic của Hành động phải hoạt động như sau:
- Kiểm tra để đảm bảo rằng thiết bị của người dùng có hỗ trợ tính năng
INTERACTIVE_CANVAS
. Nếu có, hãy gửi cho người dùng phản hồiCanvas
. - Nếu tính năng Canvas tương tác không hoạt động, hãy kiểm tra xem thiết bị của người dùng có hỗ trợ tính năng
RICH_RESPONSE
hay không. Nếu có, hãy gửi cho người dùng một phản hồi chi tiết. - Nếu không có tính năng phản hồi đa dạng thức, hãy gửi cho người dùng một phản hồi đơn giản.
Các đoạn mã sau đây trả về phản hồi phù hợp dựa trên khả năng của thiết bị của người dùng:
Hàm 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
Hành động sử dụng Canvas tương tác bao gồm một ứng dụng web có hình ảnh tuỳ chỉ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 sẽ tiếp tục tương tác với ứng dụng đó thông qua giọng nói, văn bản hoặc 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 phải chứa URL của ứng dụng web. Loại phản hồi Canvas
này sẽ 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 sẽ gửi phản hồi Canvas
đầu tiên ngay sau khi người dùng gọi Hành động. Khi ứng dụng web tải, thư viện Canvas tương tác sẽ tải và ứng dụng web sẽ đă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ư trong ảnh chụp màn hình sau:
Nếu bạn tạo một lời nhắc chứa phản hồi Canvas
sau khi chỉ định URL của ứng dụng web, Trình tạo hành động sẽ tự động điền sẵn trường URL của phản hồi Canvas
. Để biết thêm thông tin về cách thiết lập URL của ứng dụng web trong bảng điều khiển, hãy xem phần Bật Canvas tương tác.
Các đoạn mã sau đây cho biết cách tạo các phản hồi Canvas
để hiển thị ứng dụng web trong cả Trình tạo hành động và webhook của bạn:
Hàm 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 các phản hồi Canvas
bổ sung để cung cấp nội dung cập nhật cho data
. Logic tuỳ chỉnh của ứng dụng web sẽ dùng để thực hiện các thay đổi đối với ứng dụng web. Khi bạn gửi phản hồi Canvas
để truyền dữ liệu đến ứng dụng web, các bước sau sẽ diễn ra:
- Khi được so khớp trong một cảnh, ý định sẽ kích hoạt một sự kiện, rồi phản hồi
Canvas
chứa trườngdata
có tải trọng JSON sẽ được gửi lại dưới dạng phản hồi. - Trường
data
được truyền đến lệnh gọi lạionUpdate
và dùng để cập nhật ứng dụng web. Hành động trò chuyện có thể gửi một phản hồi
Canvas
mới và cung cấp thông tin trong trườngdata
để gửi nội dung cập nhật mới hoặc tải trạng thái mới.
Bạn có thể chuyển dữ liệu đến ứng dụng web của mình theo 2 cách:
- Với 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ồiCanvas
bằng siêu dữ liệu cần thiết để cập nhật ứng dụng web. - Khi có webhook. Nếu có một webhook, bạn có thể định cấu hình một tải trọng dữ liệu tuỳ chỉnh để cập nhật ứng dụng web trong phản hồi của
Canvas
.
Các phần sau đây mô tả cách truyền dữ liệu thông qua Trình tạo hành động và thông qua webhook.
Sử dụng Trình tạo hành động để truyền dữ liệu
Với 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 gửi đến ứng dụng web. Thay vào đó, khi định cấu hình trình xử lý ý định trong Giao diện người dùng Trình tạo hành động, bạn có thể thêm phản hồi Canvas
. Trường data
được tự động điền sẵn siêu dữ liệu cần thiết để cập nhật ứng dụng web, chẳng hạn như tên ý định, mọi tham số đượ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 đưa vào một phản hồi Canvas
:
Hàm 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 đây vào trình xử lý ý định để gửi tin nhắn TTS:
...
- first_simple:
variants:
- speech: Optional message.
Trình tạo hành động sẽ tự động mở rộng phản hồi Canvas
bằng siêu dữ liệu để cập nhật ứng dụng web, như minh hoạ trong các đoạn mã sau. Trong trường hợp này, người dùng đã đoán chữ cái "a" trong một trò chơi đoán từ:
Hàm 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 cập nhật ứng dụng web của bạn bằng câu trả lời của người dùng và chuyển đổi sang cảnh thích hợp.
Sử dụng webhook của bạn để chuyển dữ liệu
Bạn có thể tự thiết lập trường data
của phản hồi Canvas
trong webhook với thông tin trạng thái cần thiết để cập nhật ứng dụng web. Bạn nên sử dụng phương pháp này nếu cần đưa một tải trọng data
tuỳ chỉnh vào phản hồi Canvas
thay vì chỉ truyề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à hạn chế
Hãy lưu ý các nguyên tắc và quy định hạn chế sau đây đối với phản hồi Canvas
khi tạo 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 phản hồi webhook không bao gồmCanvas
, ứng dụng web của bạn sẽ đóng lại. - Bạn chỉ cần đưa URL của ứng dụng web vào phản hồi
Canvas
đầu tiê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
Canvas
phải có kích thước từ 50 KB trở xuống.