عندما لا تعمل الأجهزة أو الطلبات على النحو المتوقّع، من المهم توفير معالجة جيدة للأخطاء وتواصل جيد مع المستخدمين لكي يفهموا ما حدث، وكيفية تصحيحه كلما أمكن ذلك. احرص على التفكير في سيناريوهات الأعطال المحتملة وكيفية استجابة جهازك لها: ماذا لو أوقف المستخدم مهمة قيد التنفيذ؟ ماذا يحدث إذا طلب مستخدم إجراءً من جهاز في حين أنّه غير متصل بالإنترنت؟ يمكن أن يساعد التخطيط لهذه المشاكل ومساعدة المستخدم على استعادة البيانات في تجنُّب إحباط المستخدمين وتقديم تجربة أفضل على أجهزتهم.
يقدّم هذا الدليل بعض الأمثلة على ردود النية التي تعالج الأخطاء. راجِع الأخطاء والاستثناءات للاطّلاع على قيم 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 للمستخدم الرسالة "الجهاز غير متاح حاليًا" بعد تلقّي الردّ. يُرجى العِلم أنّه سيظل عليك إرسال حالة عدم الاتصال بالإنترنت للأجهزة التي تكون في حالة إعداد التقارير بعد إرسال errorCode
deviceOffline
في ردّ EXECUTE
.
المثال 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 الإشعارات الاستباقية.
إذا كانت النشّافة الذكية قيد التشغيل وفتح أحدهم الباب قبل انتهاء دورة التجفيف
يمكنك استدعاء طريقة Google Home Graph API
reportStateAndNotifications
لإرسال إشعار استباقي مع
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
، راجِع مستندات الأخطاء والاستثناءات المرجعية.