Khi thiết bị hoặc yêu cầu không hoạt động như mong đợi, bạn cần phải cung cấp giao tiếp và xử lý lỗi hiệu quả cho người dùng để họ biết đã xảy ra và cách khắc phục bất cứ khi nào có thể. Hãy đảm bảo bạn suy nghĩ kỹ càng tình huống có thể xảy ra lỗi và cách thiết bị của bạn sẽ phản hồi: Điều gì xảy ra nếu người dùng làm gián đoạn một công việc đang thực hiện? Điều gì sẽ xảy ra nếu người dùng yêu cầu hành động trên một thiết bị khi thiết bị không có kết nối mạng? Lập kế hoạch cho các sự cố này và giúp người dùng của bạn khôi phục từ đó có thể tránh gây khó chịu cho người dùng và tạo ra trải nghiệm có 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 giúp xử lý lỗi. Xem
Lỗi và ngoại lệ thành
xem lại các giá trị errorCode hợp lệ để tìm 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ó 2 đèn thông minh và được lắp đặt 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 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 không kết nối mạng
và không kiểm soát được, vì vậy, phương thức thực hiệ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 bằng một
errorCode từ một thiết bị nhẹ 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" } ] } }
Google Assistant sẽ nhắc người dùng "thiết bị đang
hiện không thể truy cập" 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 EXECUTE phản hồi.
Ví dụ 2: Ngoại lệ không chặn đối với ý định EXECUTE
Một người dùng cố gắng khoá khoá thông minh ở cửa trước bằng thiết bị có
Assistant. Bạn có thể kiểm soát thành công khoá của thiết bị nhưng
bạn thấy pin thiết bị yếu, nên phương thức thực hiện sẽ trả về một EXECUTE
phản hồi bằng status SUCCESS và exceptionCode lowBattery.
Ví dụ này minh hoạ cách gửi phản hồi EXECUTE bằng một
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" } }] } }
Assistant sẽ nhắc người dùng "thiết bị có pin yếu 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 thông báo lỗi cho người dùng, đặc biệt là đối với mà người dùng mong muốn hoàn tất tự động. Đối với những đặ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 sẽ xảy ra lỗi nếu bạn đã 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 sẽ mở cửa trước khi chu kỳ kết thúc.
Bạn có thể gọi API Google Home Graph
Phương thức reportStateAndNotifications để 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 kèm theo
errorCode 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 } } } } }
Assistant sẽ nhắc người dùng "cửa thiết bị đang đã mở" sau khi nhận được thông báo. Bạn có thể gửi trạng thái thiết bị 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 về trait có 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 khi xảy ra lỗi hoặc ngoại lệ, nếu bạn đã triển khai smart home thông báo tiếp theo.
Một người dùng ra lệnh đóng cửa nhà xe nhưng cửa bị kẹt
trong khi đóng. Bạn có thể gửi thông báo tiếp theo kèm theo 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 sẽ nhắc người dùng "thiết bị đang bị kẹt" sau khi nhận được thông báo. Bạn có thể gửi trạng thái thiết bị có thông báo trong cùng một tải trọng.
Để biết thêm thông tin và chi tiết về errorCodes, hãy xem
Lỗi và ngoại lệ
tài liệu tham khảo.