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

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

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

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