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

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

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