Khi các 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 khả năng xử lý lỗi và giao tiếp tốt cho người dùng để họ hiểu được điều gì đã xảy ra và cách khắc phục (nếu có thể). Hãy đảm bảo bạn suy nghĩ thấu đáo về 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ì xảy ra nếu người dùng yêu cầu một thao tác trên thiết bị khi thiết bị đang ở trạng thái ngoại tuyến? Việc lên kế hoạch cho những vấn đề này và giúp người dùng khắc phục có thể tránh được sự thất vọng của người dù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ề các phản hồi theo ý định xử lý lỗi. Hãy xem phần Lỗi và trường hợp ngoại lệ để xem các giá trị errorCode hợp lệ cho lỗi và trường hợp ngoại lệ.
Ví dụ 1: Phản hồi lỗi cho ý định EXECUTE
Người dùng cuối đã lắp đặ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 một ý định EXECUTE đến URL thực hiện của bạn. Bạn nhận thấy các thiết bị của người dùng đang ở chế độ ngoại tuyến và không thể điều khiển được, vì vậy, yêu cầu thực hiện của bạn sẽ trả về một phản hồi EXECUTE có status ERROR và errorCode deviceOffline.
Ví dụ này minh hoạ cách trả về một phản hồi EXECUTE có errorCode từ một thiết bị đơn giản 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 sẽ nhắc người dùng rằng "thiết bị hiện không dùng được" sau khi nhận được phản hồi. Xin lưu ý 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 đang 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 thấy pin thiết bị yếu, vì vậy, yêu cầu thực hiện của bạn sẽ trả về một 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 sẽ nhắc người dùng rằng "thiết bị có pin yếu" 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, việc cảnh báo cho người dùng về lỗi có thể hữu ích, đặc biệt là đối với những chức năng mà người dùng mong đợi sẽ 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 khi xảy ra lỗi 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 trình 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 một thông báo chủ động bằng errorCode từ mộ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 sẽ nhắc người dùng bằng thông báo "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 nối
Đối với các lệnh đặc điểm 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.
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 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 sẽ 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à trường hợp ngoại lệ.