عندما لا تعمل الأجهزة أو الطلبات على النحو المتوقع، من المهم توفير معالجة جيدة للأخطاء والتواصل مع المستخدمين حتى يدركوا ما حدث وكيف يمكن تصحيحه كلما أمكن. تأكد من التفكير في سيناريوهات الفشل المحتملة وكيفية استجابة جهازك: ماذا لو قاطع أحد المستخدمين مهمة قيد التقدم؟ ماذا لو طلب أحد المستخدمين إجراءً من جهاز أثناء عدم اتصاله بالإنترنت؟ إن التخطيط لهذه المشكلات ومساعدة المستخدم على التعافي منها يمكن أن يؤدي إلى تجنب إحباط المستخدم ويخلق انطباعًا أعلى جودة لأجهزتك.
يقدِّم هذا الدليل بعض الأمثلة على الردود حسب النية بالشراء التي تعالج الأخطاء. راجِع الأخطاء والاستثناءات لمراجعة قيم errorCode
الصالحة بحثًا عن الخطأ والاستثناءات.
مثال 1: استجابة الخطأ لقصد EXECUTE
يمتلك المستخدم النهائي مصباحَين ذكيَين مثبتَين في غرفة المعيشة. يُصدر المستخدم
أمر "إضاءة مصابيح غرفة المعيشة" وأرسلت Google نية EXECUTE
إلى عنوان URL لتوصيل الطلب. وتبيّن لك أنّ أجهزة المستخدمين غير متصلة بالإنترنت ولا يمكن التحكّم فيها، لذلك تعرض عملية توصيل الطلب استجابة EXECUTE
مع
status
ERROR
وerrorCode
deviceOffline
.
يوضح هذا المثال كيفية عرض استجابة EXECUTE
مع
errorCode
من جهاز خفيف كما هو موضح سابقًا:
{ "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 will prompt the user with "the device are
not available right now" after receiving the response. Remember that you still
need to send offline state for devices in report state after sending
errorCode
deviceOffline
in EXECUTE
response.
مثال 2: استثناء لا يحظر نية EXECUTE
يحاول مستخدم قفل القفل الذكي على الباب الأمامي باستخدام الجهاز الذي يتضمّن
Assistant. يمكنك التحكم في القفل بنجاح، ولكنك تلاحظ أن طاقة بطارية الجهاز منخفضة، لذلك فإن تنفيذ الطلب يعرض استجابة EXECUTE
باستخدام status
SUCCESS
وexceptionCode
lowBattery
.
يوضح هذا المثال كيفية إرسال استجابة EXECUTE
باستخدام
exceptionCode
من جهاز قفل كما هو موضح سابقًا:
{ "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 بأن "البطارية منخفضة" في الجهاز بعد تلقي الاستجابة.
مثال 3: إشعارات الأخطاء الاستباقية
في بعض الحالات، قد يكون من المفيد تنبيه المستخدمين بحدوث خطأ، خاصةً بالنسبة إلى الوظائف التي يتوقع المستخدمون اكتمالها تلقائيًا. بالنسبة إلى السمات التي تتيح الإشعارات الاستباقية، يمكنك إشعار المستخدم مسبقًا في حال حدوث خطأ إذا كنت قد نفّذت smart home proactive notifications.
فِيهْ مُجَفِّفْ ذَكِي شَغَّالْ وِفَتْحْ شَخْصْ بَابِ الْبَابْ قَبْلِ انْتِهَاءِ الدَّوْرَة.
يمكنك الاتصال بـ Google Home Graph API
reportStateAndNotifications
method to send a proactive notification with an
errorCode
:.
يوضح هذا المثال كيفية إرسال إشعار استباقي باستخدام 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": { "dryer-device-id": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } }, "states": { "dryer-device-id": { "isRunning": false, "isPaused": true } } } } }
سيطالب Assistant المستخدم "بفتح باب الجهاز" بعد تلقّي الإشعار. يمكنك إرسال حالات الأجهزة المناظرة بجانب الإشعارات في الحمولة نفسها.
المثال 4: إشعار المتابعة
بالنسبة إلى أوامر السمات التي تتيح تلقّي إشعارات المتابعة، يمكنك إرسال إشعار متابعة إلى المستخدم عند حدوث خطأ أو استثناء، وذلك في حال تنفيذ smart home إشعارات المتابعة.
يصدر المستخدم أمرًا بإغلاق باب المرآب، ولكن يعلو الباب أثناء إغلاقه. يمكنك إرسال إشعار متابعة باستخدام 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 بالمستخدم الذي يواجه "الجهاز بالتشويش" بعد تلقي الإشعار. يمكنك إرسال حالات الجهاز المتطابقة مع الإشعارات في الحمولة نفسها.
للحصول على مزيد من المعلومات وعلى errorCodes
التفصيلية، يمكنك الاطّلاع على الوثائق المرجعية
الأخطاء والاستثناءات.