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

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

במדריך הזה מפורטות כמה דוגמאות לתשובות לכוונות שמטפלות בשגיאות. במאמר שגיאות וחריגות מפורטים הערכים התקינים של 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

משתמש מנסה לנעול את מנעול Smart Lock בדלת הראשית באמצעות מכשיר עם 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 ההתראות היזומות.

מייבש חכם פועל ומישהו פותח את הדלת לפני שהמחזור מסתיים. אפשר להפעיל את ה-method reportStateAndNotifications של ה-API Google Home Graph כדי לשלוח התראה יזומה עם 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, עיינו במסמכי העזרה בנושא שגיאות וחריגות.