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

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

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

במקרים מסוימים, כדאי להודיע למשתמשים על שגיאה, במיוחד במקרה של פונקציות שמשתמשים מצפים להשלים באופן אוטומטי. ב-traits שתומכות בהתראות יזומות, אפשר להודיע למשתמש באופן יזום על כל שגיאה שמוטמעת בה smart home התראות יזומות.

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

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