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