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

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

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

דוגמה 1: תגובת שגיאה ל-intent מסוג EXECUTE

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