عندما لا تعمل الأجهزة أو الطلبات على النحو المتوقع، من المهم توفير إمكانية التعامل مع الأخطاء والتواصل بشكلٍ جيد مع المستخدمين حتى يفهموا ما حدث، وكيفية تصحيحه كلما أمكن ذلك. تأكد من التفكير في سيناريوهات الفشل المحتملة وكيف سيستجيب جهازك: ماذا لو قاطع أحد المستخدمين مهمة قيد التقدم؟ ماذا لو طلب المستخدم إجراءً من جهاز عندما يكون غير متصل بالإنترنت؟ يمكن أن يؤدي التخطيط لهذه المشكلات ومساعدة المستخدم على التعافي منها إلى تجنب شعور المستخدم بالإحباط وإنشاء تجربة ذات جودة أعلى لأجهزتك.
يقدِّم هذا الدليل بعض الأمثلة لاستجابات النية التي تعالج الأخطاء. راجِع الأخطاء والاستثناءات لمراجعة قيم 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
، يمكنك الاطّلاع على المستندات المرجعية الأخطاء والاستثناءات.