Khi thiết bị hoặc yêu cầu không hoạt động như mong đợi, bạn cần cung cấp thông tin liên lạc và xử lý lỗi tốt cho người dùng để họ hiểu rõ những gì đã xảy ra và cách khắc phục (nếu có thể). Hãy đảm bảo bạn cân nhắc các trường hợp có thể xảy ra lỗi và cách thiết bị của bạn nên phản hồi: Điều gì sẽ xảy ra nếu người dùng làm gián đoạn một tác vụ đang diễn ra? Điều gì sẽ xảy ra nếu người dùng yêu cầu một hành động từ một thiết bị khi thiết bị đó đang ở trạng thái ngoại tuyến? Việc lên kế hoạch cho các vấn đề này và giúp người dùng khắc phục có thể tránh được tình trạng người dùng cảm thấy thất vọng, đồng thời tạo ra trải nghiệm chất lượng cao hơn cho các thiết bị của bạn.
Hướng dẫn này cung cấp một số ví dụ về phản hồi ý định xử lý lỗi. Hãy xem
phần Lỗi và ngoại lệ để
xem xét các giá trị errorCode hợp lệ cho lỗi và ngoại lệ.
Ví dụ 1: Phản hồi lỗi cho ý định EXECUTE
Một người dùng cuối đã cài đặt 2 đèn thông minh trong phòng khách. Người dùng đưa ra lệnh "bật đèn phòng khách" và Google đã gửi ý định EXECUTE đến URL phương thức thực hiện của bạn. Bạn nhận thấy rằng các thiết bị của người dùng đang ở trạng thái ngoại tuyến và không thể điều khiển được, vì vậy, quá trình thực hiện của bạn sẽ trả về phản hồi EXECUTE có status ERROR và errorCode deviceOffline.
Ví dụ này minh hoạ cách trả về phản hồi EXECUTE có errorCode từ một thiết bị đèn như mô tả ở trên:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "light-device-id-1" ], "status": "ERROR", "errorCode": "deviceOffline" }, { "ids": [ "light-device-id-2" ], "status": "ERROR", "errorCode": "deviceOffline" } ] } }
Sau khi nhận được phản hồi, Google Assistant sẽ nhắc người dùng "hiện tại, thiết bị không
hoạt động". Hãy nhớ rằng bạn vẫn cần gửi trạng thái ngoại tuyến cho các thiết bị ở trạng thái báo cáo sau khi gửi errorCode deviceOffline trong phản hồi EXECUTE.
Ví dụ 2: Ngoại lệ không chặn cho ý định EXECUTE
Một người dùng cố gắng khoá khoá thông minh trên cửa trước bằng
Assistant. Bạn có thể điều khiển khoá của họ thành công nhưng nhận thấy pin của thiết bị đang yếu, vì vậy, quá trình thực hiện của bạn sẽ trả về phản hồi EXECUTE có status SUCCESS và exceptionCode lowBattery.
Ví dụ này minh hoạ cách gửi phản hồi EXECUTE có exceptionCode từ một thiết bị khoá như mô tả ở trên:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["lock-device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isLocked": true, "isJammed": false, "exceptionCode": "lowBattery" } }] } }
Sau khi nhận được phản hồi, Assistant sẽ nhắc người dùng "pin của thiết bị đang yếu".
Ví dụ 3: Thông báo lỗi chủ động
Trong một số trường hợp, bạn nên cảnh báo người dùng về lỗi, đặc biệt là đối với các chức năng mà người dùng mong đợi sẽ tự động hoàn tất. Đối với các đặc điểm hỗ trợ thông báo chủ động, bạn có thể chủ động thông báo cho người dùng khi xảy ra lỗi nếu đã triển khai smart home thông báo chủ động.
Một máy sấy thông minh đang chạy và có người mở cửa trước khi chu trình kết thúc.
Bạn có thể gọi phương thức của Google Home Graph API
reportStateAndNotifications để gửi thông báo chủ động có
errorCode:
Ví dụ này minh hoạ cách gửi thông báo chủ động có errorCode từ một thiết bị máy sấy như mô tả ở trên:
POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id", "eventId": "unique-event-id", "payload": { "devices": { "notifications": { "dryer-device-id": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } }, "states": { "dryer-device-id": { "isRunning": false, "isPaused": true } } } } }
Sau khi nhận được thông báo, Assistant sẽ nhắc người dùng "cửa thiết bị đã mở". Bạn có thể gửi trạng thái thiết bị tương ứng cùng với thông báo trong cùng một tải trọng.
Ví dụ 4: Thông báo tiếp nối
Đối với các lệnh đặc điểm hỗ trợ thông báo tiếp nối, bạn có thể gửi một thông báo tiếp nối cho người dùng khi xảy ra lỗi hoặc ngoại lệ, nếu đã triển khai smart home thông báo tiếp nối.
Một người dùng đưa ra lệnh đóng cửa nhà xe, nhưng cửa bị kẹt khi đóng. Bạn có thể gửi thông báo tiếp nối có errorCode:
POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id", "eventId": "unique-event-id", "payload": { "devices": { "notifications": { "door-device-id": { "LockUnlock": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "deviceJammingDetected", "followUpToken": "follow-up-token-1" } } } }, "states": { "door-device-id": { "openPercent": 70 } } } } }
Sau khi nhận được thông báo, Assistant sẽ nhắc người dùng "thiết bị bị kẹt". Bạn có thể gửi trạng thái thiết bị tương ứng cùng với thông báo trong cùng một tải trọng.
Để biết thêm thông tin và errorCodes chi tiết, hãy xem tài liệu tham khảo về
Lỗi và ngoại lệ.