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