1. Tổng quan
Actions on Google là một nền tảng dành cho nhà phát triển, cho phép bạn tạo phần mềm để mở rộng chức năng của Trợ lý Google (trợ lý ảo cá nhân của Google) trên hơn 1 tỷ thiết bị, bao gồm cả loa thông minh, điện thoại, ô tô, TV, tai nghe và nhiều thiết bị khác. Người dùng trò chuyện với Trợ lý Google để hoàn thành các việc cần làm, chẳng hạn như mua hàng tạp hoá hoặc đặt xe; để xem danh sách đầy đủ những việc có thể làm hiện tại, hãy xem Thư mục hành động. Là nhà phát triển, bạn có thể sử dụng Actions on Google để dễ dàng tạo và quản lý trải nghiệm đàm thoại thú vị và hữu ích giữa người dùng và dịch vụ bên thứ ba của riêng bạn.
Lớp học lập trình này là một mô-đun nâng cao dành cho những độc giả đã có kinh nghiệm xây dựng các Thao tác cho Trợ lý Google. Nếu bạn chưa có kinh nghiệm phát triển nào với Actions on Google, hãy làm quen với nền tảng này bằng cách làm theo các lớp học lập trình giới thiệu ( Cấp 1 và Cấp 2). Các mô-đun này sẽ hướng dẫn bạn tìm hiểu một loạt tính năng có thể giúp bạn mở rộng chức năng của Thao tác và tăng lượng khán giả.
Trong lớp học lập trình này, bạn sẽ sử dụng Interactive Canvas (Canvas tương tác) (một khung được xây dựng trên Trợ lý Google) để thêm một trò chơi toàn màn hình vào một Hành động trò chuyện. Trò chơi này là một ứng dụng web tương tác mà Trợ lý gửi cho người dùng dưới dạng phản hồi trong cuộc trò chuyện. Sau đó, người dùng có thể chơi trò chơi thông qua giọng nói hoặc văn bản trên màn hình thông minh và thiết bị di động Android.
Thay vì tự xây dựng toàn bộ trò chơi, bạn sẽ triển khai một trò chơi được tạo sẵn một phần có tên là Snow Pal và thêm logic của trò chơi khi thực hiện lớp học lập trình này. Snow Pal là một biến thể của trò chơi truyền thống Hangman (Người treo cổ); trò chơi này đưa ra một số khoảng trống đại diện cho một từ và bạn đoán các chữ cái mà bạn cho là có thể có trong từ đó. Với mỗi lần đoán sai, người bạn tuyết của bạn sẽ tan chảy thêm một chút. Bạn sẽ thắng trò chơi nếu đoán được từ trước khi Người bạn tuyết tan chảy hoàn toàn.

Hình 1. Một trò chơi Snow Pal đã hoàn tất một phần
Sản phẩm bạn sẽ tạo ra
Trong lớp học lập trình này, bạn sẽ tạo một Thao tác sử dụng Canvas tương tác. Thao tác của bạn sẽ có các tính năng sau:
- Một trò chơi chữ toàn màn hình mà người dùng có thể chơi bằng giọng nói
- Một nút mà người dùng có thể nhấn để bắt đầu trò chơi
- Một nút mà người dùng có thể nhấn để chơi lại trò chơi
Khi bạn hoàn tất lớp học lập trình này, Thao tác đã hoàn thành sẽ có quy trình trò chuyện như sau:
Trợ lý: Welcome to Snow Pal! Would you like to start playing the game?
Người dùng: Yes.
Trợ lý: Try guessing a letter in the word or guessing the word.
Người dùng: I guess the letter E.
Trợ lý: Let's see if your guess is there...E is right. Right on! Good guess.
Người dùng tiếp tục đoán chữ cái hoặc đoán từ chưa biết cho đến khi trò chơi kết thúc.
Kiến thức bạn sẽ học được
- Cách tạo và triển khai một Thao tác Interactive Canvas
- Cách cập nhật trò chơi chữ dựa trên giọng nói và thao tác chạm của người dùng
- Cách truyền dữ liệu đến ứng dụng web bằng nhiều phương thức
- Cách gỡ lỗi Thao tác Interactive Canvas
Bạn cần có
Các điều kiện tiên quyết cho lớp học lập trình này bao gồm:
- Một trình duyệt web, chẳng hạn như Google Chrome
- Một IDE hoặc trình chỉnh sửa văn bản mà bạn chọn
- Node.js, npm và git được cài đặt trên máy của bạn
Bạn nên có kiến thức về JavaScript (ES6) để hiểu rõ đoạn mã được dùng trong lớp học lập trình này.
Không bắt buộc: Nhận mã mẫu đầy đủ
Trong lớp học lập trình này, bạn sẽ tạo mẫu từng bước từ một phiên bản chưa hoàn chỉnh. Nếu muốn, bạn cũng có thể lấy mẫu hoàn chỉnh từ kho lưu trữ GitHub.
2. Giới thiệu về Interactive Canvas
Interactive Canvas là một khung được xây dựng trên Trợ lý Google, cho phép bạn thêm hình ảnh và ảnh động toàn màn hình vào Thao tác đàm thoại.
Một Hành động sử dụng Interactive Canvas hoạt động tương tự như một Hành động trò chuyện thông thường. Tuy nhiên, Thao tác trên Canvas tương tác có thêm khả năng gửi phản hồi đến thiết bị mở một ứng dụng web toàn màn hình.
Người dùng cung cấp thông tin đầu vào cho ứng dụng web thông qua giọng nói hoặc thao tác chạm cho đến khi cuộc trò chuyện kết thúc.

Hình 2. Một Hành động được tạo bằng Interactive Canvas.
Trong lớp học lập trình này, dự án của bạn được sắp xếp thành 3 phần chính sau:
- Ứng dụng web: Các tệp ứng dụng web chứa mã cho hình ảnh và ảnh động của ứng dụng web, cũng như logic để cập nhật ứng dụng web dựa trên thông tin đầu vào của người dùng.
- Hành động đàm thoại: Hành động đàm thoại chứa logic đàm thoại của bạn, giúp nhận dạng, xử lý và phản hồi thông tin đầu vào của người dùng.
- Webhook: Webhook xử lý logic của trò chơi. Trong lớp học lập trình này, bạn có thể coi webhook là máy chủ trò chơi của mình.
Đối với mỗi phần của lớp học lập trình này, bạn sẽ sửa đổi ứng dụng web, Thao tác đàm thoại và webhook để thêm chức năng vào Thao tác trên Canvas tương tác.
Nhìn chung, Thao tác đàm thoại, webhook và ứng dụng web trong Thao tác Snow Pal hoạt động theo cách sau:
- Thao tác đàm thoại sẽ nhắc người dùng đoán một chữ cái trong từ hoặc đoán toàn bộ từ.
- Người dùng nói "Tôi đoán chữ i" với ứng dụng web Snow Pal trên màn hình thông minh.
- Đầu vào của người dùng được chuyển đến Hành động trò chuyện của bạn, được xác định trong dự án Actions Builder và/hoặc Actions SDK.
- Thao tác trò chuyện sẽ xử lý thông tin đầu vào của người dùng và tuỳ thuộc vào thông tin đầu vào đó, thao tác này sẽ kích hoạt logic trong webhook để cập nhật ứng dụng web hoặc gửi siêu dữ liệu để cập nhật trực tiếp ứng dụng web.
- Ứng dụng web cập nhật để cho biết vị trí của chữ cái trong từ và người dùng được yêu cầu đoán lại.
Bạn sẽ tìm hiểu thêm về cách hoạt động của Canvas tương tác trong phần Tìm hiểu cơ sở hạ tầng của Canvas tương tác. Giờ đây, khi đã biết các kiến thức cơ bản, bạn có thể bắt đầu thiết lập môi trường cho lớp học lập trình này.
3. Thiết lập
Kiểm tra chế độ cài đặt quyền của bạn trên Google
Để kiểm thử Hành động mà bạn tạo cho lớp học lập trình này, bạn cần bật các quyền cần thiết để trình mô phỏng Bảng điều khiển Actions có thể truy cập vào Hành động của bạn. Để bật quyền, hãy làm theo các bước sau:
- Chuyển đến phần Kiểm soát hoạt động.
- Nếu cần, hãy đăng nhập bằng Tài khoản Google của bạn.
- Bật các quyền sau:
- Hoạt động trên web và ứng dụng
- Trong mục Hoạt động trên web và ứng dụng, hãy chọn hộp đánh dấu Bao gồm cả nhật ký duyệt web trên Chrome cũng như hoạt động trên những trang web, ứng dụng và thiết bị sử dụng các dịch vụ của Google.
Cài đặt giao diện dòng lệnh gactions
Trong lớp học lập trình này, bạn sẽ sử dụng công cụ giao diện dòng lệnh (CLI) gactions để đồng bộ hoá dự án Actions giữa Actions Console và hệ thống tệp cục bộ.
Để cài đặt gactions CLI, hãy làm theo hướng dẫn trong phần Cài đặt công cụ dòng lệnh gactions.
Cài đặt giao diện dòng lệnh của Firebase
Giao diện dòng lệnh (CLI) của Firebase cho phép bạn triển khai dự án Actions lên Cloud Functions và lưu trữ ứng dụng web của mình.
Lớp học lập trình này sử dụng npm để cài đặt Firebase CLI. Đảm bảo bạn đã cài đặt npm (thường đi kèm với Node.js).
- Để cài đặt hoặc nâng cấp CLI, hãy mở một cửa sổ dòng lệnh rồi chạy lệnh
npmsau:
npm install -g firebase-tools
- Để xác minh rằng bạn đã cài đặt CLI đúng cách, hãy chạy lệnh sau:
firebase --version
Đảm bảo phiên bản Firebase CLI là 8 trở lên để có tất cả các tính năng mới nhất cần thiết cho Cloud Functions. Nếu không, hãy chạy npm install -g firebase-tools để nâng cấp.
- Để đăng nhập vào Firebase, hãy chạy lệnh sau:
firebase login
Khi đăng nhập vào Firebase, hãy nhớ dùng cùng một Tài khoản Google mà bạn đã dùng để tạo dự án Actions.
Sao chép kho lưu trữ
Trong phần này, bạn sẽ sao chép các tệp cần thiết cho lớp học lập trình này. Để lấy các tệp này, hãy làm theo các bước sau:
- Mở cửa sổ dòng lệnh rồi chuyển sang thư mục nơi bạn thường lưu trữ các dự án mã hoá. Nếu bạn không có thư mục gốc, hãy chuyển đến thư mục gốc.
- Để sao chép kho lưu trữ này, hãy chạy lệnh sau trong thiết bị đầu cuối:
git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs
Mở thư mục start/. Kho lưu trữ này chứa các thư mục quan trọng sau đây mà bạn sẽ làm việc:
public/: Thư mục này chứa mã HTML, CSS và JavaScript cho ứng dụng web của bạn.sdk/custom/: Thư mục này chứa logic cho Thao tác đàm thoại của bạn (cảnh, ý định và loại).sdk/webhooks/: Thư mục này là webhook của bạn và chứa logic của trò chơi.

Hình 3. Cấu trúc của mã thư mục start.
4. Thiết lập dự án Actions
Trong phần này, bạn sẽ tạo và định cấu hình dự án Actions, đẩy mã từ kho lưu trữ được sao chép sang Actions Console bằng gactions CLI, đồng thời triển khai ứng dụng web và webhook.
Tạo một dự án Actions
Dự án Actions là một vùng chứa cho Hành động của bạn. Để tạo dự án Actions cho lớp học lập trình này, hãy làm theo các bước sau:
- Mở Bảng điều khiển Actions.
- Nhấp vào Dự án mới.
- Nhập Tên dự án, chẳng hạn như
canvas-codelab. Tên này chỉ để bạn tham khảo nội bộ. Sau đó, bạn có thể đặt tên bên ngoài cho dự án của mình.

- Nhấp vào Tạo dự án.
- Trong màn hình Bạn muốn tạo loại Thao tác nào?, hãy chọn thẻ Trò chơi.
- Nhấp vào Tiếp theo.
- Chọn thẻ Dự án trống.
- Nhấp vào Bắt đầu xây dựng.
Lưu mã dự án cho Thao tác của bạn
Mã dự án là giá trị nhận dạng duy nhất cho Thao tác của bạn. Bạn sẽ cần có mã dự án cho một số bước trong lớp học lập trình này.
Để truy xuất mã dự án, hãy làm theo các bước sau:
- Trong bảng điều khiển Actions, hãy nhấp vào biểu tượng ba dấu chấm dọc > Cài đặt dự án.

- Sao chép mã dự án.
Liên kết tài khoản thanh toán
Để triển khai yêu cầu thực hiện sau này trong lớp học lập trình này bằng Cloud Functions, bạn phải liên kết một tài khoản thanh toán với dự án của mình trong Google Cloud. Nếu đã có tài khoản thanh toán, bạn có thể bỏ qua các bước sau.
Để liên kết tài khoản thanh toán với dự án, hãy làm theo các bước sau:
- Truy cập vào trang thanh toán của Google Cloud Platform.
- Nhấp vào Thêm tài khoản thanh toán hoặc Tạo tài khoản.
- Điền thông tin thanh toán của bạn.
- Nhấp vào Bắt đầu dùng thử miễn phí hoặc Gửi và bật tính năng thanh toán.
- Truy cập vào trang thanh toán của Google Cloud.
- Nhấp vào thẻ Dự án của tôi.
- Nhấp vào biểu tượng ba dấu chấm > Thay đổi thông tin thanh toán.
- Trong trình đơn thả xuống, hãy chọn tài khoản thanh toán mà bạn đã thiết lập.
- Nhấp vào Thiết lập tài khoản.
Để tránh phát sinh các khoản phí, hãy làm theo các bước trong phần Dọn dẹp dự án.
Triển khai ứng dụng web
Trong phần này, bạn sẽ triển khai ứng dụng web (trò chơi Snow Pal) bằng Giao diện dòng lệnh (CLI) của Firebase. Sau khi triển khai, bạn có thể truy xuất URL cho ứng dụng web và xem giao diện của trò chơi trong trình duyệt.
Để triển khai ứng dụng web, hãy làm theo các bước sau:
- Trong cửa sổ dòng lệnh, hãy chuyển đến thư mục
start/. - Chạy lệnh sau, thay thế
{PROJECT_ID}bằng mã dự án của bạn:
firebase deploy --project {PROJECT_ID} --only hosting
Sau vài phút, bạn sẽ thấy "Deploy complete!". Điều này cho biết bạn đã triển khai thành công ứng dụng web Snow Pal lên Firebase.
Để xem trò chơi Snow Pal trong trình duyệt, hãy làm theo các bước sau:
- Truy xuất URL lưu trữ có trong đầu ra của thiết bị đầu cuối. URL phải có dạng như sau: https://<PROJECT_ID>.web.app
- Dán URL đó vào trình duyệt. Bạn sẽ thấy màn hình bắt đầu trò chơi Snow Pal (Người bạn tuyết) có nút Start Game (Bắt đầu trò chơi):

Thêm URL ứng dụng web và mã dự án vào dự án Actions
Tiếp theo, hãy thêm URL ứng dụng web và mã dự án vào tệp actions.intent.MAIN.yaml. Khi thêm URL của ứng dụng web, Thao tác đàm thoại sẽ biết URL nào cần gửi dữ liệu đến, còn khi thêm mã dự án vào settings.yaml, bạn có thể đẩy các tệp đã tải xuống vào đúng dự án trong Bảng điều khiển Actions.
Để thêm URL ứng dụng web và mã dự án, hãy làm theo các bước sau:
- Mở tệp
start/sdk/custom/global/actions.intent.MAIN.yamltrong trình chỉnh sửa văn bản. - Trong trường URL, hãy thay thế chuỗi giữ chỗ bằng URL ứng dụng web của bạn.
- Mở tệp
start/sdk/settings/settings.yamltrong trình chỉnh sửa văn bản. - Trong trường projectId, hãy thay thế chuỗi giữ chỗ bằng mã dự án của bạn.
Đẩy dự án lên Bảng điều khiển Actions
Để cập nhật Bảng điều khiển Actions bằng dự án cục bộ, bạn cần đẩy dự án Actions lên Bảng điều khiển Actions. Để thực hiện việc này, hãy làm theo các bước sau:
- Thay đổi thành thư mục
sdk:
cd sdk/
- Để sao chép cấu hình của hệ thống tệp cục bộ vào bảng điều khiển Actions, hãy chạy lệnh sau:
gactions push
Triển khai webhook
Khi chạy gactions push, bạn đã nhập mã webhook bắt đầu vào Actions Console. Trong phần còn lại của lớp học lập trình này, bạn có thể chỉnh sửa mã webhook trong bảng điều khiển Actions. Tại thời điểm này, bạn có thể triển khai webhook từ bảng điều khiển Actions.
Để triển khai webhook, hãy làm theo các bước sau:
- Trong bảng điều khiển Actions, hãy nhấp vào Phát triển trong thanh điều hướng.
- Nhấp vào thẻ Webhook trong thanh điều hướng.
- Nhấp vào Triển khai tính năng thực hiện đơn hàng.
Cloud Functions có thể mất vài phút để cung cấp và triển khai yêu cầu thực hiện của bạn. Bạn sẽ thấy thông báo Đang triển khai Cloud Functions.... Khi mã triển khai thành công, thông báo sẽ cập nhật thành Your Cloud Function deployment is up to date (Việc triển khai Cloud Functions của bạn đã được cập nhật).
Kiểm thử trong trình mô phỏng
Tại thời điểm này, Thao tác của bạn được liên kết với ứng dụng web. Bạn có thể dùng trình mô phỏng Bảng điều khiển Actions để đảm bảo ứng dụng web xuất hiện khi bạn gọi Thao tác.
Để kiểm thử Thao tác, hãy làm theo các bước sau:
- Trong thanh điều hướng của Actions Console, hãy nhấp vào Kiểm thử.
- Nhập
Talk to Snow Pal samplevào trường Đầu vào rồi nhấnEnter. - Nhập
Yesvào trường Đầu vào rồi nhấnEnter. Hoặc nhấp vào Bắt đầu trò chơi.

Bạn chưa định cấu hình logic để đoán một chữ cái hoặc đoán từ, vì vậy nếu đoán một từ hoặc chữ cái, bạn sẽ nhận được phản hồi "...Không chính xác. Hãy tiếp tục thử! Có vẻ như chúng ta cần thêm chức năng để tính năng này hoạt động đúng cách."
5. Tìm hiểu cơ sở hạ tầng Interactive Canvas
Đối với dự án này, chức năng được sắp xếp thành 3 thành phần chính: Thao tác đàm thoại, ứng dụng web và webhook. Xin lưu ý rằng đây là một mô hình về cách bạn có thể thiết lập Thao tác và được sắp xếp theo cách này để làm nổi bật chức năng cốt lõi của Canvas tương tác.
Các phần sau đây sẽ trình bày chi tiết hơn về cách Hoạt động đàm thoại, webhook và ứng dụng web phối hợp với nhau, cũng như các phần tử quan trọng khác của Canvas tương tác.
Hành động trò chuyện
Thành phần Thao tác đàm thoại của Thao tác sẽ xử lý việc nhận dạng thông tin đầu vào của người dùng, xử lý thông tin đó và gửi đến cảnh thích hợp, nơi phản hồi cho người dùng được tạo. Ví dụ: nếu người dùng nói "Tôi đoán chữ e" trong trò chơi Snow Pal, Hành động đàm thoại của bạn sẽ trích xuất chữ cái đó làm tham số ý định và truyền đến logic trò chơi thích hợp. Logic này sẽ xác định xem lượt đoán có chính xác hay không và cập nhật ứng dụng web cho phù hợp. Bạn có thể xem và sửa đổi logic trò chuyện này trong Actions Builder, một IDE dựa trên web trong Actions Console. Ảnh chụp màn hình sau đây cho thấy một phần của Thao tác đàm thoại trong Actions Builder:

Hình 4. Hình ảnh minh hoạ Main invocation trong Trình tạo hành động.
Ảnh chụp màn hình này cho thấy Main invocation cho Hành động của bạn. Người dùng sẽ khớp với Main invocation này khi họ nói một cụm từ như "Ok Google, nói chuyện với Snow Pal sample". Khi người dùng gọi Hành động của bạn, Main invocation sẽ gửi một lời nhắc kèm theo phản hồi canvas, trong đó có URL của ứng dụng web.
Phản hồi canvas đầu tiên trong Thao tác của bạn phải bao gồm URL của ứng dụng web. Phản hồi này yêu cầu Trợ lý hiển thị ứng dụng web tại địa chỉ đó trên thiết bị của người dùng. Các phản hồi canvas bổ sung trong Actions Builder có thể bao gồm một trường send_state_data_to_canvas_app được đặt thành true. Trường này sẽ gửi tên ý định và mọi giá trị tham số đến ứng dụng web khi ý định được so khớp, đồng thời ứng dụng web sẽ cập nhật dựa trên dữ liệu này từ thông tin đầu vào của người dùng.
Webhook
Trong lớp học lập trình này, webhook của bạn chứa lôgic trò chơi (bạn có thể coi webhook của mình như một máy chủ trò chơi). Logic của trò chơi bao gồm các yếu tố như xác định xem người dùng đoán đúng hay sai, hoặc người dùng đã thắng hay thua và xây dựng phản hồi dựa trên kết quả. Bạn có thể sửa đổi webhook trong Actions Builder.
Khi Thao tác của bạn cần thực thi logic trò chơi, Trình tạo thao tác sẽ gọi webhook. Ví dụ: ý định guess trong cảnh Game sẽ gọi webhook đến trình xử lý guess, sau đó trình xử lý này sẽ thực thi logic để xác định xem người dùng đoán đúng hay không. Webhook có thể bao gồm Canvas phản hồi trong các trình xử lý ánh xạ đến tệp ứng dụng web và cập nhật web một cách thích hợp.
Ứng dụng web

Hình 5. Hình ảnh minh hoạ mối tương tác giữa Thao tác đàm thoại, webhook và ứng dụng web trong một Thao tác Interactive Canvas.
Các tệp ứng dụng web chứa mã cho hình ảnh và ảnh động của ứng dụng web, cũng như logic để cập nhật ứng dụng web dựa trên thông tin đầu vào của người dùng. Bạn sửa đổi các tệp ứng dụng web trong trình chỉnh sửa văn bản và triển khai những thay đổi này bằng Firebase CLI.
Giao tiếp giữa Hành động đàm thoại và ứng dụng web
Bạn cần bật tính năng giao tiếp giữa Thao tác đàm thoại và ứng dụng web để ứng dụng web có thể cập nhật dựa trên hoạt động đầu vào của người dùng. Ví dụ: nếu người dùng nói "Tôi đoán chữ f",
Thao tác đàm thoại cần cung cấp cho ứng dụng web chữ cái f để ứng dụng web có thể cập nhật cho phù hợp. Để truyền thông tin đầu vào của người dùng từ Thao tác đàm thoại sang ứng dụng web, bạn phải tải trong Interactive Canvas API.
Tập lệnh cho API này có trong /public/index.html, đây là tệp HTML chính cho trò chơi Snow Pal. Tệp này xác định giao diện người dùng của bạn và cách tải trong một số tập lệnh:
index.html
<!-- Load Assistant Interactive Canvas API -->
<script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>
Để cập nhật ứng dụng web dựa trên thông tin đầu vào của người dùng, bạn cũng phải đăng ký và định cấu hình lệnh gọi lại trong tệp ứng dụng web. Lệnh gọi lại cho phép ứng dụng web của bạn phản hồi thông tin hoặc yêu cầu từ Thao tác đàm thoại.
Trong /public/js/action.js, có một lớp được định cấu hình sẵn có tên là Action để khai báo và đăng ký lệnh gọi lại. Lớp Action là một trình bao bọc xung quanh Interactive Canvas API. Khi ứng dụng web được tạo bằng hàm create() trong scene.js, một phiên bản Action mới sẽ được tạo và setCallbacks() sẽ được gọi, như minh hoạ trong đoạn mã sau:
scene.js
// Set Assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register Assistant Action callbacks.
this.assistant.setCallbacks();
Hàm setCallbacks() được xác định trong lớp Action của /public/js/action.js. Hàm này khai báo các lệnh gọi lại và đăng ký chúng với Interactive Canvas API khi tạo trò chơi:
setCallbacks() {
// Declare the Interactive Canvas Action callbacks.
const callbacks = {
onUpdate: (data) => {
...
// Called by the Interactive Canvas web app once web app has loaded to
// register callbacks.
this.canvas.ready(callbacks);
}
Hàm setCallbacks() khai báo lệnh gọi lại onUpdate(). Lệnh gọi lại này được gọi mỗi khi bạn gửi một phản hồi Canvas.
Phần tiếp theo mô tả cách định cấu hình mã cụ thể cho dự án này để truyền dữ liệu từ Thao tác trò chuyện đến ứng dụng web.
Cập nhật ứng dụng web dựa trên thông tin đầu vào của người dùng
Trong lớp học lập trình này, bạn sẽ sử dụng bản đồ lệnh để cập nhật ứng dụng web dựa trên thông tin đầu vào của người dùng. Ví dụ: khi ý định start_game được so khớp trong cảnh Welcome, phản hồi canvas có trong lời nhắc sẽ được gửi đến ứng dụng web. onUpdate() phân tích cú pháp siêu dữ liệu từ phản hồi canvas và gọi lệnh START_GAME. Lệnh này sẽ gọi hàm start() trong scene.js và cập nhật ứng dụng web để bắt đầu một phiên chơi trò chơi mới.
Hàm start() trong scene.js cũng gọi một hàm, updateCanvasState(), sử dụng một phương thức có tên là setCanvasState() để thêm dữ liệu trạng thái mà webhook của bạn có thể truy cập.
Phương thức updateCanvasState() được gọi ở cuối mỗi lệnh (bạn sẽ thêm các lệnh này trong suốt lớp học lập trình) và cập nhật trạng thái của ứng dụng web. Mỗi khi updateCanvasState() được gọi, các giá trị cho displayedWord và incorrectGuesses sẽ được cập nhật dựa trên trạng thái hiện tại:
scene.js
...
updateCanvasState() {
window.interactiveCanvas.setCanvasState({
correctWord: this.word.text,
displayedWord: this.word.displayText.text,
incorrectGuesses: this.incorrectGuesses,
});
Sau đó, trạng thái đã cập nhật sẽ có sẵn cho lượt trò chuyện tiếp theo. Bạn có thể truy cập trạng thái này trong webhook thông qua conv.context.canvas.state, như minh hoạ trong đoạn mã sau:
index.js
...
let displayedWord = conv.context.canvas.state.displayedWord;
...
6. Thêm chức năng đoán
Trong phần này, bạn sẽ thêm chức năng guess vào Thao tác của mình, cho phép người dùng đoán các chữ cái trong từ hoặc chính từ đó.
Hành động trò chuyện
Trong phần Kiểm thử trong trình mô phỏng, bạn nhận được một phản hồi có nội dung "Có vẻ như chúng ta cần thêm chức năng để tính năng này hoạt động đúng cách". Giờ đây, bạn có thể xoá lời nhắc đó trong bảng điều khiển Actions để chỉ gọi webhook (trong cảnh Game, ý định guess đã được định cấu hình để thực hiện lệnh gọi webhook khi được so khớp).
Để xoá câu lệnh tĩnh khi ý định guess được so khớp, hãy làm theo các bước sau:
- Trong bảng điều khiển Actions, hãy nhấp vào Cảnh trong thanh điều hướng.
- Nhấp vào Game (Trò chơi) để chuyển đến cảnh
Game. - Nhấp vào Khi dự đoán trùng khớp trong phần Xử lý ý định của người dùng. Xoá Gửi câu lệnh để xoá câu lệnh.
- Nhấp vào Lưu.
Webhook
Trong phần này, bạn sẽ cập nhật webhook bằng logic ánh xạ phỏng đoán đúng hoặc sai của người dùng với logic trong một tệp ứng dụng web, sau đó cập nhật ứng dụng web cho phù hợp. Trình xử lý ý định guess đã được định cấu hình cho bạn trong webhook, vì vậy, bạn chỉ cần thêm các phản hồi Canvas vào ý định này để kích hoạt logic cập nhật ứng dụng web.
Để cập nhật webhook, hãy làm theo các bước sau:
- Trong bảng điều khiển Actions, hãy nhấp vào Webhook trong thanh điều hướng.
- Thêm mã sau vào
index.jstrong trình xử lýguess:
index.js (Phần A):
// Add Section A `conv.add(new Canvas({` content here.
conv.add(new Canvas({
data: {
command: 'CORRECT_ANSWER',
displayedWord: displayedWord
},
}));
index.js (Phần B):
// Add Section B `conv.add(new Canvas({` content here.
conv.add(new Canvas({
data: {
command: 'INCORRECT_ANSWER',
},
}));
- Nhấp vào Lưu thông tin thực hiện đơn hàng.
- Nhấp vào Triển khai tính năng thực hiện đơn hàng. Khi quá trình triển khai hoàn tất, một thông báo sẽ xuất hiện với nội dung Việc triển khai Cloud Functions của bạn đã hoàn tất.
Ứng dụng web
Giờ đây, bạn có thể định cấu hình ứng dụng web để xử lý các lệnh CORRECT_ANSWER và INCORRECT_ANSWER.
- Mở
public/js/action.jstrong trình chỉnh sửa văn bản. - Cập nhật ứng dụng web để xử lý các lệnh
CORRECT_ANSWERvàINCORRECT_ANSWER:
action.js (Phần C):
// Add Section C `CORRECT_ANSWER: (params) => {` content here.
CORRECT_ANSWER: (params) => {
this.gameScene.correctAnswer(params);
},
INCORRECT_ANSWER: (params) => {
this.gameScene.incorrectAnswer();
},
- Chạy lệnh sau để cập nhật ứng dụng web:
firebase deploy --project {PROJECT_ID} --only hosting
Kiểm thử Hành động trong trình mô phỏng
Tại thời điểm này, Thao tác của bạn có thể nhận biết liệu một lượt đoán là đúng hay sai và cập nhật ứng dụng web cho phù hợp.
Để kiểm thử Thao tác, hãy làm theo các bước sau:
- Trong thanh điều hướng, hãy nhấp vào Kiểm thử.
- Nhập
Talk to Snow Pal samplevào trường Đầu vào rồi nhấnEnter. - Nhập
Yesvào trường Đầu vào rồi nhấnEnter. Hoặc bạn có thể nhấp vào nút Có. - Nhập chữ cái bạn muốn đoán vào trường Nhập rồi nhấn
Enter.

Tìm hiểu về mã
Ở phần trước, bạn đã thêm mã cho phép người dùng đoán các chữ cái trong trò chơi và xem những chữ cái đó xuất hiện trong từ hoặc Snow Pal. Ở cấp độ cao, bạn thực hiện một lệnh gọi webhook trong Actions Builder khi ý định guess được so khớp, lệnh gọi này sẽ truyền dữ liệu đến ứng dụng web của bạn để cập nhật ứng dụng web cho phù hợp. Ví dụ: nếu người dùng đoán một chữ cái trong trò chơi Snow Pal có trong từ, thì ứng dụng web sẽ cập nhật để cho thấy chữ cái đó ở đúng vị trí trong từ.
Đối với những Thao tác sử dụng Canvas tương tác, quy trình chung về cách dữ liệu được truyền từ webhook đến ứng dụng web như sau:
- Câu hỏi của người dùng khớp với một ý định có chứa phản hồi
Canvas. - Hành động trò chuyện hoặc webhook sẽ gửi phản hồi
Canvas, phản hồi này sẽ kích hoạt lệnh gọi lạionUpdate(). - Lệnh gọi lại
onUpdate()liên kết với logic tuỳ chỉnh để cập nhật ứng dụng web cho phù hợp.
Đối với dự án cụ thể này, mã hoạt động theo cách sau:
- Khi người dùng khớp với ý định
guess, Actions Builder sẽ trích xuất chữ cái từ thông tin đầu vào của người dùng dưới dạng một tham số. - Actions Builder gọi trình xử lý
guesstrong webhook của bạn, chứa logic để xác định xem chữ cái mà người dùng đoán có xuất hiện trong từ hay không. - Trình xử lý
guesschứa hai phản hồiCanvas: một phản hồi thực thi khi chữ cái chính xác và một phản hồi thực thi khi chữ cái không chính xác. Mỗi phản hồiCanvassẽ truyền dữ liệu thích hợp (lệnhCORRECT_ANSWERhoặcINCORRECT_ANSWER) đến ứng dụng web. - Dữ liệu có trong trường
datacủa phản hồiCanvasđược truyền đến phương thứconUpdate()trongaction.js.onUpdate()sẽ gọi lệnh thích hợp trong bản đồ lệnh trongscene.js. - Bản đồ lệnh ánh xạ đến các hàm
correctAnswer()vàincorrectAnswer()trongscene.js. Các hàm này sẽ cập nhật ứng dụng web một cách thích hợp để phản ánh phỏng đoán của người dùng và gọisetCanvasState()để gửi dữ liệu trạng thái từ ứng dụng web đến webhook của bạn.
7. Thêm chức năng thắng/thua
Trong phần này, bạn sẽ thêm chức năng thắng và thua vào Thao tác của mình, bao gồm cả logic xác định xem người dùng đã thắng hay thua và logic cập nhật hình ảnh ứng dụng web dựa trên kết quả của người dùng.
Hành động trò chuyện
Chức năng xử lý việc người dùng thắng hoặc thua trò chơi sẽ được định cấu hình trong ý định guess, vì vậy, bạn không phải thực hiện bất kỳ cấu hình bổ sung nào trong Actions Builder.
Webhook
Trong phần này, bạn sẽ cập nhật webhook bằng logic xử lý khi người dùng thắng hoặc thua trò chơi, đồng thời liên kết với logic ứng dụng web để cập nhật trò chơi bằng màn hình thắng hoặc thua thích hợp.
Để cập nhật webhook, hãy làm theo các bước sau:
- Trong bảng điều khiển Actions, hãy nhấp vào Webhook trong thanh điều hướng.
- Thêm mã sau vào
index.jstrong trình xử lýguess:
index.js (Mục D):
// Add Section D `if (userHasWon)` content here.
if (userHasWon) {
conv.add(`<speak>Let's see if your guess is there...<break
time='2500ms'/> ${guess} is right. That spells ${correctWord}!
${randomArrayItem(WIN_RESPONSES)}</speak>`);
conv.add(new Canvas({
data: {
command: 'WIN_GAME',
displayedWord: displayedWord
},
}));
conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
} else {
index.js (Phần E):
// Add Section E `}` here.
}
index.js (Phần F):
// Add Section F `Check if the user has exceeded the maximum` content here.
// Check if the user has exceeded the maximum amount of max guesses allowed.
const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
if (userHasLost) {
conv.add(`<speak>Let's see if your guess is there...<break
time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
conv.add(new Canvas({
data: {
command: 'LOSE_GAME',
},
}));
conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
} else {
index.js (Phần G):
// Add Section G `}` here.
}
- Nhấp vào Lưu thông tin thực hiện đơn hàng.
- Nhấp vào Triển khai tính năng thực hiện đơn hàng. Khi quá trình triển khai hoàn tất, một thông báo sẽ xuất hiện với nội dung Việc triển khai Cloud Functions của bạn đã hoàn tất.
Ở đây, bạn đã thêm 2 phản hồi Canvas bằng các lệnh WIN_GAME và LOSE_GAME để xử lý khi người dùng thắng hoặc thua trò chơi. Trong phần tiếp theo, bạn sẽ thêm chức năng cập nhật ứng dụng web dựa trên việc người dùng thắng hay thua.
Ứng dụng web
Giờ đây, bạn có thể định cấu hình ứng dụng web để cập nhật dựa trên việc người dùng thắng hay thua. Để cập nhật ứng dụng web, hãy làm theo các bước sau:
- Mở
public/js/action.jstrong trình chỉnh sửa văn bản. - Cập nhật ứng dụng web để xử lý các lệnh
WIN_GAMEvàLOSE_GAME:
action.js (Phần H):
// Add Section H `WIN_GAME: (params) => {` content here.
WIN_GAME: (params) => {
this.gameScene.winGame(params);
},
LOSE_GAME: (params) => {
this.gameScene.loseGame();
},
- Chạy lệnh sau để cập nhật ứng dụng web:
firebase deploy --project {PROJECT_ID} --only hosting
Kiểm thử Hành động trong trình mô phỏng
Tại thời điểm này, Thao tác của bạn có thể xử lý khi người dùng thắng hoặc thua trò chơi và trình bày màn hình phù hợp cho từng kết quả.
Để kiểm thử Thao tác, hãy làm theo các bước sau:
- Trong thanh điều hướng của Actions Console, hãy nhấp vào Kiểm thử.
- Nhập
Talk to Snow Pal samplevào trường Đầu vào rồi nhấnEnter. - Nhập
Yesvào trường Đầu vào rồi nhấnEnter. Hoặc nhấp vào nút Bắt đầu trò chơi. - Đoán chữ cái và từ cho đến khi bạn thắng hoặc thua.

Nếu yêu cầu phát lại, bạn sẽ nhận được thông báo cho biết chức năng cần thiết để phát lại chưa được thêm. Bạn sẽ thêm chức năng này trong phần tiếp theo.
Tìm hiểu về mã
Chức năng thắng và thua hoạt động giống như chức năng đoán – người dùng khớp với ý định guess và webhook của bạn đánh giá suy đoán của người dùng. Nếu người dùng đoán đúng, mã sẽ kiểm tra xem người dùng đã thắng chưa; nếu thắng, lệnh WIN_GAME sẽ được gửi đến ứng dụng web. Nếu người dùng đoán sai, mã sẽ kiểm tra xem người dùng đã thua chưa; nếu thua, lệnh LOSE_GAME sẽ được gửi đến ứng dụng web. Các lệnh này kích hoạt các hàm winGame() và loseGame() trong scene.js, giúp cập nhật ứng dụng web để trình bày màn hình thắng hoặc thua và cập nhật trạng thái của trò chơi.
8. Thêm chức năng chơi lại
Trong phần này, bạn sẽ thêm chức năng cho phép người dùng nói "Chơi lại" hoặc nhấp vào nút Chơi lại trong ứng dụng web để bắt đầu một trò chơi mới. Bạn sửa đổi ý định play_again trong Actions Builder để gửi một phản hồi canvas nhằm cập nhật ứng dụng web một cách thích hợp, đồng thời thêm logic kích hoạt ý định play_again khi người dùng nhấp vào nút Chơi lại.
Hành động trò chuyện
Khi kiểm thử Thao tác của bạn trong phần trước, bạn sẽ nhận được lời nhắc sau đây nếu cố gắng chơi lại trò chơi: "Điều đó thật tuyệt, nhưng chúng ta sẽ tạo chức năng này trong phần sau. Hiện tại, bạn chỉ cần đặt lại Thao tác." Giờ đây, bạn có thể xoá lời nhắc này và thay thế bằng một lời nhắc trả lời người dùng khi họ yêu cầu một trò chơi khác ("Được thôi, đây là một trò chơi khác!") và bao gồm một phản hồi canvas để kích hoạt ứng dụng web bắt đầu một trò chơi mới.
Để cập nhật lời nhắc khi người dùng muốn phát lại, hãy làm theo các bước sau:
- Trong bảng điều khiển Actions, hãy nhấp vào trình đơn thả xuống Cảnh.
- Nhấp vào cảnh Game (Trò chơi).
- Nhấp vào Khi play_again được so khớp trong phần Xử lý ý định của người dùng.
- Thay thế câu lệnh bằng nội dung sau:
candidates:
- first_simple:
variants:
- speech: 'Okay, here''s another game!'
canvas:
sendStateDataToCanvasApp: true
- Nhấp vào Lưu.
Webhook
Trong lớp học lập trình này, webhook sẽ quản lý logic trò chơi. Vì chức năng phát lại không yêu cầu bất kỳ loại xác thực logic nào, nên bạn không cần gọi webhook; thay vào đó, bạn có thể gửi phản hồi canvas trực tiếp từ Actions Builder để truyền dữ liệu cần thiết đến ứng dụng web (bạn đã định cấu hình dữ liệu này trong phần trước).
Ứng dụng web
Giờ đây, bạn có thể sửa đổi các tệp ứng dụng web để cập nhật một cách thích hợp khi người dùng yêu cầu phát lại. Để thêm chức năng này, hãy làm theo các bước sau:
- Mở
public/js/action.jstrong trình chỉnh sửa văn bản. - Cập nhật ứng dụng web để xử lý lệnh
PLAY_AGAIN:
action.js (Phần I):
// Add Section I `PLAY_AGAIN: (params) => {` content here.
PLAY_AGAIN: (params) => {
this.gameScene.start();
},
- Mở
public/js/scene.jstrong trình chỉnh sửa văn bản. - Cập nhật ứng dụng web để bắt đầu một phiên chơi trò chơi mới khi người dùng nhấp vào nút "Chơi lại":
scene.js (Mục J):
// Add Section J `sendTextQuery` content here.
window.interactiveCanvas.sendTextQuery('Play again');
- Chạy lệnh sau để cập nhật ứng dụng web:
firebase deploy --project {PROJECT_ID} --only hosting
Kiểm thử Hành động trong trình mô phỏng
Giờ đây, Thao tác của bạn có thể bắt đầu một phiên chơi trò chơi mới khi người dùng nói "Chơi lại" hoặc nhấp vào nút Chơi lại.
Để kiểm thử Thao tác, hãy làm theo các bước sau:
- Trong thanh điều hướng, hãy nhấp vào Kiểm thử.
- Nhập
Talk to Snow Pal samplevào trường Đầu vào rồi nhấnEnter. - Nhập
Yesvào trường Đầu vào rồi nhấnEnter. Hoặc nhấp vào nút Bắt đầu trò chơi. - Đoán chữ cái và từ cho đến khi bạn thắng hoặc thua.
- Nhập
Play againvào trường Đầu vào rồi nhấnEnter. Hoặc nhấp vào nút Phát lại.

Tìm hiểu về mã
Khi kiểm thử Thao tác, bạn có thể bắt đầu một trò chơi mới thông qua phương thức nhập bằng giọng nói ("Chơi lại") hoặc phương thức nhập bằng cách chạm (nhấp vào nút Chơi lại).
Đối với lựa chọn nhập bằng giọng nói, khi người dùng nói "Chơi lại" hoặc một biến thể nào đó của câu này, ý định play_again sẽ được so khớp và thêm một lời nhắc ("Được thôi, đây là một trò chơi khác!") vào hàng đợi lời nhắc. Phản hồi canvas có trong lời nhắc sẽ gửi tên ý định và siêu dữ liệu khác đến ứng dụng web. Tên ý định được truyền đến lệnh gọi lại onUpdate(), lệnh gọi này sẽ liên kết lệnh tương ứng (PLAY_AGAIN) với bản đồ lệnh trong action.js. Lệnh PLAY_AGAIN sẽ kích hoạt hàm start() trong scene.js và cập nhật ứng dụng web bằng một phiên trò chơi mới.
Đối với lựa chọn nhập bằng cách nhấn, bạn sử dụng sendTextQuery() (một Interactive Canvas API cho phép bạn kích hoạt ý định thông qua thao tác nhập bằng cách nhấn) để làm cho nút hoạt động.
Trong lớp học lập trình này, bạn sẽ dùng sendTextQuery() để gọi ý định play_again khi người dùng nhấp vào nút Chơi lại. Đối số Play again khớp với một cụm từ huấn luyện trong ý định play_again và kích hoạt ý định này theo cách tương tự như khi người dùng nói "Phát lại". Sau đó, ý định play_again sẽ kích hoạt logic cập nhật ứng dụng web và bắt đầu một phiên chơi trò chơi mới.
9. Cập nhật ý định tích hợp PLAY_GAME
Trong phần này, bạn sẽ cập nhật ý định tích hợp PLAY_GAME.
Ý định tích hợp PLAY_GAME cho phép người dùng gọi Hành động của bạn khi họ đưa ra một yêu cầu chung, chẳng hạn như "Tôi muốn chơi trò chơi".
Mã nguồn chứa ý định tích hợp PLAY_GAME, nằm tại /sdk/custom/global/actions.intent.PLAY_GAME.yaml. Điều này được thể hiện trong bảng điều khiển ở phần Invocation (Lời gọi) dưới dạng PLAY_GAME, như trong ảnh chụp màn hình sau:

Để cho phép người dùng gọi Hành động của bạn thông qua ý định tích hợp này, bạn cần thêm một phản hồi canvas có URL của ứng dụng web vào ý định tích hợp PLAY_GAME. Để thực hiện việc này, hãy làm theo các bước sau:
- Trong Actions Console, hãy nhấp vào PLAY_GAME trong thanh điều hướng.
- Cập nhật câu lệnh để thêm URL của ứng dụng web, như minh hoạ trong đoạn mã sau:
candidates:
- canvas:
url: 'https://<PROJECT_ID>.web.app'
- Nhấp vào Lưu.
Kiểm thử Hành động trong trình mô phỏng
Hành động của bạn hiện hỗ trợ ý định tích hợp sẵn PLAY_GAME.
Để kiểm thử Thao tác, hãy làm theo các bước sau:
- Trong thanh điều hướng, hãy nhấp vào Kiểm thử.
- Nhấp vào Kiểm thử tính năng xử lý ý định tích hợp.
- Nhấp vào Invoke Action (Gọi hành động).

Thao tác của bạn sẽ được gọi trong trình mô phỏng.
10. Phụ lục: Khắc phục sự cố về Thao tác Interactive Canvas
Trong phần này, bạn sẽ tìm hiểu cách gỡ lỗi Hành động trên Canvas tương tác khi Hành động đó không hoạt động đúng cách. Dự án Snow Pal đi kèm với một lớp gỡ lỗi mà bạn có thể bật. Lớp phủ này hiển thị tất cả đầu ra console.log() và console.error() ở dưới cùng bên phải màn hình, như trong ảnh chụp màn hình sau:

Để bật lớp phủ này, hãy mở tệp /public/css/main.css và nhận xét dòng display: none !important;, như minh hoạ trong đoạn mã sau:
main.css
.debug {
display: flex;
flex-direction: column;
/* Comment below to view debug overlay */
/* display: none !important; */
width: 500px;
height: 150px;
right: 0;
bottom: 0;
position: absolute;
}
Dọn dẹp dự án của bạn [nên dùng]
Để tránh phát sinh các khoản phí có thể có, bạn nên xoá những dự án mà bạn không định sử dụng. Để xoá các dự án mà bạn đã tạo trong lớp học lập trình này, hãy làm theo các bước sau:
- Để xoá Dự án và tài nguyên trên Google Cloud, hãy hoàn tất các bước được liệt kê trong phần Tắt (xoá) dự án.
- Không bắt buộc: Để xoá ngay dự án của bạn khỏi Actions Console, hãy hoàn tất các bước được liệt kê trong phần Xoá dự án. Nếu bạn không hoàn tất bước này, dự án của bạn sẽ tự động bị xoá sau khoảng 30 ngày.
11. Xin chúc mừng!
Bạn đã hoàn thành lớp học lập trình giới thiệu về Interactive Canvas và hiện đã có các kỹ năng cần thiết để tạo Thao tác Interactive Canvas của riêng mình.
Kiến thức bạn học được
- Cách tạo, triển khai và kiểm thử một Thao tác Interactive Canvas
- Cách sử dụng câu trả lời của
Canvasđể cập nhật ứng dụng web - Cách sử dụng nhiều phương thức để cải thiện Thao tác, chẳng hạn như
sendTextQuery()vàsetCanvasState() - Cách gỡ lỗi cho Thao tác
Tìm hiểu thêm
Hãy xem các tài nguyên sau đây để tìm hiểu thêm về Interactive Canvas:
- Tài liệu về Interactive Canvas: Tài liệu chính thức của Actions on Google về Interactive Canvas.
- Mẫu Interactive Canvas: Mã cho một trò chơi Interactive Canvas đơn giản, cho phép bạn xoay một hình tam giác và sửa đổi màu sắc của hình đó.
- Cổng trò chơi: Nguyên tắc xây dựng trò chơi trên Trợ lý Google.
Bài khảo sát nhận ý kiến phản hồi
Trước khi rời đi, vui lòng điền vào một bài khảo sát ngắn về trải nghiệm của bạn.