Khi thiết bị hoặc yêu cầu không hoạt động như mong đợi, điều quan trọng là bạn phải cung cấp tính năng xử lý lỗi và thông báo hiệu quả cho người dùng để họ hiểu được điều gì đã xảy ra và cách khắc phục khi có thể. Hãy đảm bảo bạn đã suy nghĩ kỹ về các tình huống có thể xảy ra và cách thiết bị 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ừ thiết bị khi thiết bị đó đang ở trạng thái ngoại tuyến? Việc lập kế hoạch cho những vấn đề này và giúp người dùng khắc phục các vấn đề đó có thể giúp người dùng không cảm thấy thất vọng và mang lại trải nghiệm chất lượng cao hơn cho 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 lại 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 hai đè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 một ý định EXECUTE đến URL thực hiện của bạn. Bạn nhận thấy thiết bị của người dùng đang ở chế độ ngoại tuyến và không thể kiểm soát được, vì vậy, phương thức thực hiện của bạn sẽ trả về một phản hồi EXECUTE với status ERROR và errorCode deviceOffline.
Ví dụ này minh hoạ cách trả về phản hồi EXECUTE bằng errorCode từ thiết bị ánh sáng như mô tả trước đó:
{ "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" } ] } }
Google Assistant nhắc người dùng "thiết bị hiện không hoạt động" sau khi nhận được phản hồi. 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: Trường hợp ngoại lệ không chặn cho ý định EXECUTE
Người dùng cố gắng khoá khoá thông minh trên cửa trước bằng cách sử dụng Assistant. Bạn có thể điều khiển thành công khoá của họ nhưng phát hiện pin thiết bị sắp hết, vì vậy, phương thức thực hiện sẽ trả về phản hồi EXECUTE với status SUCCESS và exceptionCode lowBattery.
Ví dụ này minh hoạ cách gửi phản hồi EXECUTE bằng exceptionCode từ thiết bị khoá như mô tả trước đó:
{ "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" } }] } }
Assistant nhắc người dùng "thiết bị sắp hết pin" sau khi nhận được phản hồi.
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 hàm 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 trong khi lỗi xảy ra nếu đã triển khai smart home thông báo chủ động.
Máy sấy thông minh đang chạy và có người mở cửa trước khi chu kỳ kết thúc.
Bạn có thể gọi phương thức reportStateAndNotifications của API Google Home Graph để gửi thông báo chủ động bằng errorCode:
Ví dụ này minh hoạ cách gửi thông báo chủ động bằng errorCode từ thiết bị máy sấy như mô tả trước đó:
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 } } } } }
Assistant nhắc người dùng "cửa thiết bị đã mở" sau khi nhận được thông báo. Bạn có thể gửi các 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 theo
Đối với các lệnh thuộc tính hỗ trợ thông báo tiếp theo, bạn có thể gửi thông báo tiếp theo cho người dùng trong khi lỗi hoặc ngoại lệ xảy ra, nếu bạn đã triển khai smart home thông báo tiếp theo.
Người dùng đưa ra lệnh đóng cửa gara, nhưng cửa bị kẹt trong khi đóng. Bạn có thể gửi thông báo tiếp theo bằng 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 } } } } }
Assistant nhắc người dùng rằng "thiết bị bị kẹt" sau khi nhận được thông báo. Bạn có thể gửi các 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ệ.