טיפול בשגיאות ובחריגים

כאשר המכשירים או הבקשות לא פועלים כמצופה, חשוב לספק תקשורת טובה וטיפול בשגיאות עם המשתמשים, כדי שהם יבינו ואיך לתקן את המצב ככל האפשר. אל תשכחו לחשוב תרחישי כשל אפשריים ואיך המכשיר שלך יגיב: מה קורה אם משתמש מפריע למשימה שלא מתבצעת כרגע? מה אם משתמש מבקש פעולה ממכשיר במצב אופליין? תכנון הבעיות האלה ועזרה למשתמשים שלך להתאושש מידע זה יכול למנוע את תסכול המשתמש וליצור חוויה באיכות גבוהה יותר למכשירים שלך.

במדריך הזה מפורטות כמה דוגמאות לתגובות של Intent שמטפלות בשגיאות. צפייה שגיאות וחריגים לבדוק את הערכים התקינים של errorCode כדי לאתר שגיאות וחריגים.

דוגמה 1: תגובת שגיאה עבור Intent של EXECUTE

למשתמש הקצה יש שתי נורות חכמות מותקנות בסלון. המשתמש/ת מנפיקה פקודה "Turn on living room lights" ו-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: חריג לא חוסם ל-Intent מסוג 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 התראות יזומות.

מייבש כביסה חכם פועל, ומישהו פותח את הדלת לפני שהמחזור מסתיים. אפשר לשלוח קריאה ל-API של Google Home Graph 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 יציג הודעה כשדלת המכשיר היא נפתח" לאחר קבלת ההתראה. אפשר לשלוח את המסמכים המתאימים את המכשיר לצד התראות באותו מטען ייעודי (payload).

דוגמה 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 תציג למשתמש הודעה ש"המכשיר הוא תקוע" לאחר קבלת ההתראה. אפשר לשלוח את המסמכים המתאימים למצבים של המכשיר עם התראות באותו מטען ייעודי (payload).

לקבלת מידע נוסף וerrorCodes מפורט, שגיאות וחריגים מסמכי עזר.