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

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

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

דוגמה 1: תגובה עם שגיאה לכוונת EXECUTE

למשתמש קצה יש שתי נורות חכמות בסלון. המשתמש מנפיק פקודה 'הדלקת האורות בסלון' ו-Google שולחת EXECUTE intent לכתובת ה-URL של ה-fulfillment. הגעת למסקנה שהמכשירים של המשתמש לא מחוברים לאינטרנט ואי אפשר לשלוט בהם, ולכן התשובה שמוחזרת מההזמנה היא 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. הצלחתם לשלוט בנעילה, אבל הסוללה של המכשיר חלשה. לכן, התגובה של ה-fulfillment היא 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‏ Google Home Graph של reportStateAndNotifications API כדי לשלוח התראה יזומה עם 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 זמינים במאמרי העזרה שגיאות וחריגים.