Thông tin chung
Hỏi: Chúng tôi nên triển khai cơ sở hạ tầng thực hiện Actions on Google ở đâu và bằng ngôn ngữ nào?
Đáp: Miễn là API này hỗ trợ SSL (TLS) và OAuth 2.0 hiện đại, bạn có thể triển khai cơ sở hạ tầng của mình trên mọi nền tảng và bằng bất kỳ ngôn ngữ nào mà bạn chọn. Bạn nên triển khai càng gần càng tốt phần cơ sở hạ tầng còn lại để cải thiện độ tin cậy và giảm độ trễ khi thực thi trên thiết bị thực tế của người dùng.
Hỏi: Mã thiết bị có cần phải duy nhất không?
Đáp: Các mã nhận dạng phải khác nhau. Nếu bạn không có mã nhận dạng duy nhất trên dịch vụ, thì các mã nhận dạng này ít nhất phải là duy nhất ở cấp độ mỗi người dùng. Hãy tưởng tượng một người dùng có nhiều nhà, trong đó cả hai nhà đều có tích hợp với cùng một người dùng. Yêu cầu bật đèn trong một nhà không được bật đèn có cùng mã nhận dạng ở một nhà khác.
Hỏi: Tên thiết bị có cần phải là duy nhất không?
Đáp: Tên không nhất thiết phải là duy nhất, mặc dù theo thời gian, chúng tôi có thể khuyến khích mọi người cải thiện cách đặt tên không đúng sau khi thiết lập để có trải nghiệm người dùng tốt hơn.
Dưới đây là hướng dẫn đặt tên nhanh:
- Tên phải là nội dung mà mọi người thực sự có thể nói.
- Chúng tôi nhận ra các tập hợp con của chuỗi, vì vậy, nếu bạn có "acme colorlight" (đèn màu acme), chúng tôi cũng sẽ trả lời là "acmelight" (ánh sáng acme).
- Bạn nên đặt cả tên mô tả cho sản phẩm và một hoặc nhiều tên do người dùng xác định.
- Người dùng không cần đặt tên phòng cho đèn vì chúng tôi có các không gian cho việc đó; chúng nên có tên riêng cho từng phòng, nhưng luôn có thể sử dụng số nhiều để chỉ định mọi thứ (ví dụ: 2 bóng đèn trong màn hình văn phòng là "đèn bắc" và "đèn đông", nhưng có thể được gọi là "đèn sáng").
Hỏi: Trạng thái thiết bị được cập nhật bao lâu một lần?
Đáp: Trạng thái tạm thời được truy xuất khi QUERY hoặc EXECUTE, đây là các hành động do người dùng khởi tạo. Nếu người dùng hỏi "đèn đang bật chưa?" hoặc muốn tăng độ sáng, chúng ta sẽ cần thực hiện một truy vấn để tìm ra trạng thái hiện tại.
Hỏi: Có thể trực tiếp cập nhật Home Graph theo trạng thái hiện tại của thiết bị không?
Đáp: Có, hãy sử dụng lệnh gọi API Report State.
Liên kết tài khoản và OAuth
Hỏi: Chúng tôi có cần liên kết tài khoản không?
Đáp: Có, việc liên kết tài khoản là bắt buộc để có thể kết nối thiết bị của người dùng với dịch vụ đám mây của nhà cung cấp.
Hỏi: Đối với OAuth, mã thông báo truy cập sẽ hết hạn sau mỗi 15.213 giờ. Như vậy có được không?
Đáp: Có, nhưng vui lòng thử nghiệm trong một thời gian hết hạn khá ngắn, chẳng hạn như 10-20 phút. Ứng dụng OAuth của chúng ta nên làm mới mã thông báo khi cần và việc kiểm thử trong thời gian hết hạn ngắn sẽ chứng minh rằng cách này đang hoạt động hiệu quả.
Ý định
Hỏi: Khi nào sự kiện SYNC diễn ra?
Đáp: SYNC diễn ra ngay sau khi hoàn tất OAuth và sau khi thực hiện lệnh gọi Request Sync (Yêu cầu đồng bộ hoá).
Hỏi: Tại sao SYNC không hoạt động?
Đáp: Có một số lý do phổ biến khiến việc này không thành công.
Bạn đang gửi sai loại thiết bị.
- Ví dụ: chúng tôi dự kiến là
action.devices.types.LIGHT, nhưng bạn gửiaction.devices.types.Light.
- Ví dụ: chúng tôi dự kiến là
Bạn đang gửi các loại thiết bị không được hỗ trợ.
- Ví dụ: bạn gửi
action.devices.types.FLASHLIGHT– đây không phải là tính năng chúng tôi hỗ trợ.
- Ví dụ: bạn gửi
Bạn đang gửi các trường không hợp lệ/không được hỗ trợ.
- Ví dụ: bạn có một trường phiên bản hoặc một số trường khác không có trong bản đặc tả của chúng tôi.
Có một số vấn đề về định dạng khác với phản hồi SYNC.
- Hãy đánh dấu ngoặc vuông!
Bạn đang gặp phải vấn đề khi liên kết tài khoản.
- Vui lòng xác minh rằng bạn đang nhận được mã truy cập hợp lệ trong tiêu đề Xác thực của yêu cầu SYNC.
Bạn mất quá nhiều thời gian để phản hồi yêu cầu SYNC.
- Vui lòng xác minh rằng bạn đang phản hồi yêu cầu SYNC trong vòng 5 giây.
Hỏi: Bạn có chấp nhận câu trả lời “đang chờ xử lý” không?
Đáp: Chúng tôi đặc biệt muốn nhận thông tin phản hồi thành công/không thành công thay vì đang chờ xử lý, nếu thiết bị của bạn có sẵn theo thời gian thực. Vui lòng liên hệ nếu bạn cảm thấy cần phản hồi "đang chờ xử lý" – chúng tôi nhận thấy rằng một số thiết bị tiết kiệm pin, không theo thời gian thực có thể yêu cầu phản hồi đang chờ xử lý và mô hình thực thi không đồng bộ.
Kiểm tra và gửi
Hỏi: Chúng tôi có thể thiết lập một môi trường thử nghiệm không?
Đáp: Có, vui lòng tạo một dự án riêng và tiến hành thiết lập cho dự án đó. Bạn có thể tạo số lượng dự án tuỳ theo nhu cầu để xác định các quy trình phát triển và cơ sở hạ tầng của mình.
Hỏi: Bao lâu thì tôi cần cập nhật dự án nháp của mình một lần?
Đáp: Dự án nháp cần được làm mới 3 ngày một lần. Sau 3 ngày, tác nhân thử nghiệm sẽ biến mất khỏi phần cài đặt HomeControl của thiết bị di động. Nếu bạn gặp sự cố này, hãy nhấp vào nút KIỂM TRA BẢN NHÁP cho dự án của bạn trong Actions on Google Console.
Hỏi: Tôi có thể thử nghiệm trên nhiều thiết bị cùng lúc không?
Đáp: Actions on Google chỉ hỗ trợ một AP "thử trên thiết bị" tại một thời điểm. Nếu bạn sử dụng KIỂM TRA BẢN NHÁP lần đầu trên "ap1" và các thiết bị đồng bộ hoá, thì (mà không huỷ liên kết ap1) trực tiếp chạy BẢN THẢO THỬ NGHIỆM "ap2", "ap1" sẽ biến mất khỏi cài đặt HomeControl-thiết bị di động. Để khắc phục điều này, hãy chạy KIỂM TRA BẢN NHÁP trên "ap1" một lần nữa và bạn có thể hủy liên kết "ap1" trong cài đặt.
Xin lưu ý rằng Gói hành động duy nhất này sẽ được cung cấp cho người dùng trên tất cả thiết bị Google Assistant của bạn – ví dụ: bạn có thể kiểm thử việc tích hợp phần cứng mới trên cả loa kích hoạt bằng giọng nói và Android.
Hỏi: Dự án Hành động của tôi bị từ chối do tên hoặc cách phát âm. Tôi cần thay đổi gì?
Đáp: Chúng tôi kiểm tra cách phát âm tên để đảm bảo rằng Tên cách phát âm không bị một Hành động khác sử dụng trong tương lai và khớp với tên hiển thị (để ngăn những thông tin không khớp ảnh hưởng đến các hoạt động đăng ký tên trong tương lai).
Để tiếp tục sử dụng cùng một tên, vui lòng liên hệ với nhóm hỗ trợ để nhờ nhóm phụ trách lời nói thêm tên hiển thị vào Assistant.
Hỏi: Hành động của tôi không xuất hiện trong phần Điều khiển nhà trong ứng dụng Google Home, có vấn đề gì vậy?
Đáp: Vấn đề này có thể là một trong những nguyên nhân sau:
- Bạn chưa nhấp vào nút KIỂM TRA BẢN NHÁP cho dự án của bạn trong Actions Console.
- Mỗi lần, bạn chỉ có thể có một Hành động trong Thử nghiệm trên thiết bị.
- Trong Actions Console, hãy truy cập thẻ Trình mô phỏng cho dự án Hành động của bạn, đồng thời chuyển nút bật/tắt Hoạt động/Không hoạt động thành Không hoạt động rồi chọn Hoạt động trở lại.
- Nếu đây là một Hành động được chia sẻ với bạn, hãy đảm bảo bạn đã làm theo tất cả hướng dẫn chia sẻ.
- Thời gian thử nghiệm trên thiết bị sẽ hết hạn sau 3 ngày. Nhấp vào nút KIỂM TRA BẢN NHÁP cho dự án của bạn trong Actions Console.
Hỏi: Tại sao tôi gặp lỗi khi nhập "trò chuyện với <my agent name>" trong Trình mô phỏng?
Đáp: Hành động trong nhà thông minh không sử dụng tên lệnh gọi. Để kiểm thử trong trình mô phỏng, bạn phải chạy tính năng liên kết tài khoản trên điện thoại Android hoặc iOS đã cài đặt Google Home app (GHA). Bạn cũng phải liên kết các thiết bị với tài khoản của mình trước khi chạy liên kết tài khoản.
Hỏi: Tại sao tôi gặp lỗi khi cố gắng sử dụng Trình mô phỏng?
Đáp: Bạn không thể sử dụng trình mô phỏng để kiểm thử Hành động smart home đã triển khai. Nếu muốn dùng trình mô phỏng cho một dự án tự động hoá nhà đang trong quá trình sản xuất, thì bạn cần tạo một dự án mới cho mục đích thử nghiệm.
Trạng thái báo cáo
Hỏi: Có điều kiện tiên quyết nào để triển khai Trạng thái báo cáo không?
Đáp: Dự án cần sử dụng Smart Home API, hỗ trợ OAuth2 và cần có các đặc điểm có(các) trạng thái được báo cáo.
Hỏi: Chúng tôi cần Báo cáo trạng thái trên một thiết bị bao lâu một lần?
Đáp: Google quan tâm đến quá trình chuyển đổi và trạng thái thiết bị đầu cuối. Tuy nhiên, nếu có nhiều thay đổi về trạng thái trong một khoảng thời gian ngắn (chẳng hạn như người dùng mở và đóng tủ lạnh 3 lần trong một phút hoặc trượt độ giảm độ sáng), thì chúng ta chỉ cần báo cáo trạng thái cuối cùng.
Hỏi: Có cần gửi trạng thái thiết bị đầy đủ khi thực hiện lệnh gọi Trạng thái báo cáo không?
Đáp: Chúng tôi không hỗ trợ việc cập nhật một phần trạng thái, vì vậy, các lệnh gọi Report State phải luôn bao gồm tất cả dữ liệu cho một đặc điểm cụ thể đã được cập nhật. Nếu 2 đặc điểm tạo ra sự không nhất quán, thì chúng phải được báo cáo lại cùng nhau.
Hỏi: Google có thể truy vấn thiết bị của tôi để nhận trạng thái (nghĩa là thăm dò thiết bị) không?
Đáp: Đây là cơ chế dự phòng mà chúng tôi không khuyên dùng. Nếu cần thường xuyên quay lại thăm dò ý kiến trên một thiết bị cho những người dùng đó, chúng tôi không thể đảm bảo mức tải bổ sung sẽ là gì. Nhu cầu xuất phát từ các giao diện trực quan mới. Ngoài vấn đề tải không xác định, trải nghiệm người dùng sẽ bị giảm chất lượng. Chúng tôi cảm thấy Report State rất quan trọng đối với nền tảng này.
Hỏi: Những đặc điểm nào hỗ trợ Trạng thái báo cáo hiện tại?
Đáp: Tất cả trait công khai có trạng thái liên kết đều được hỗ trợ. Bạn cũng nên báo cáo mọi thay đổi về trạng thái Online của thiết bị.
Lưu ý rằng Cảnh không có trạng thái. Tuy nhiên, chúng có thể dẫn đến thay đổi về trạng thái của (các) thiết bị. Nếu bất kỳ thiết bị nào trong Google Home Graph có trạng thái thay đổi, thì bạn cần báo cáo lại trạng thái đó.
Hỏi: Trạng thái báo cáo có yêu cầu gửi dấu thời gian không?
Đáp: Chúng tôi không yêu cầu dấu thời gian; trạng thái mới nhất được gửi sẽ ghi đè các lệnh gọi trước đó.
Hỏi: Tôi có cần báo cáo riêng trạng thái nếu tôi đã gửi trạng thái trong Truy vấn và/hoặc Thực thi không?
Đáp: Home Graph chỉ lưu trữ trạng thái được gửi qua Report State. Trạng thái được trả về dưới dạng phản hồi cho các ý định EXECUTE và QUERY chỉ được dùng cho phản hồi bằng giọng nói của người dùng và không được lưu trữ. Do đó, Report State sẽ được gọi ngay cả khi trạng thái mới của thiết bị đã được trả về dưới dạng phản hồi cho một ý định EXECUTE hoặc QUERY.
Hỏi: Các hậu quả của việc không triển khai hoàn chỉnh Trạng thái báo cáo trong thời hạn nhất định là gì?
Đáp: Điều này sẽ dẫn đến trải nghiệm người dùng kém, chẳng hạn như trong GHA và các giao diện trực quan. Như vậy có nghĩa là nhiều ý định QUERY sẽ được gửi để thăm dò ý kiến cho trạng thái và chúng tôi không thể đảm bảo ý định này sẽ tương ứng với lượt tải bổ sung trên đám mây của đối tác.
Hỏi: Làm cách nào để kiểm tra việc triển khai Trạng thái báo cáo?
Đáp: Sử dụng Home Graph Viewer (Trình xem biểu đồ trang chủ) – một công cụ kiểm tra tự phục vụ cho bạn biết trạng thái hiện tại của thiết bị được lưu trữ trong Home Graph.
Hỏi: Chúng tôi có thể sử dụng mã yêu cầu ngẫu nhiên cho Trạng thái báo cáo không?
Đáp: Các đối tác nên sử dụng cùng một mã yêu cầu mà họ nhận được từ yêu cầu EXECUTE nếu Report State được kích hoạt bởi yêu cầu EXECUTE. Nếu không, bạn chỉ cần sử dụng mã yêu cầu ngẫu nhiên.
Hỏi: Nếu người dùng có nhiều thiết bị và một trong số đó bị thay đổi trạng thái, thì chúng tôi có phải báo cáo trạng thái mới nhất của tất cả thiết bị không?
Đáp: Không. Bạn chỉ phải báo cáo trạng thái của thiết bị cụ thể đó.
Những phương pháp hay nhất
Hỏi: Loại độ trễ nào được chấp nhận?
Đáp: Lý tưởng nhất là dưới 200 mili giây, từ 2 đến 5 giây là hợp lý. Nếu thời gian chờ của bạn kéo dài khoảng 5 giây, hãy liên hệ với chúng tôi.
Hỏi: Làm cách nào để loa kích hoạt bằng giọng nói phản hồi đúng cách khi thiết bị không có kết nối mạng?
Đáp: Trả về trạng thái ngoại tuyến cho thiết bị không kết nối mạng. Đối với lỗi này, chúng tôi trả về giá trị "không có sẵn ngay bây giờ" dưới dạng TTS. Để biết thêm thông tin, hãy xem phần Lỗi và ngoại lệ.