當裝置或要求未正常運作時,請務必為使用者提供適當的錯誤處理和通訊方式,協助他們瞭解發生的狀況,並視情況修正問題。請務必考量所有可能的失敗情境,以及裝置的回應方式:如果使用者中斷進行中的工作,會發生什麼事?如果使用者離線時透過裝置要求動作,該怎麼辦?規劃這些問題並協助使用者順利復原這些問題,可用於避免使用者感到困擾,並為裝置建立更優質的使用體驗。
本指南提供幾個處理錯誤的意圖回應範例。請參閱錯誤和例外狀況一文,瞭解有效的 errorCode
錯誤和例外狀況。
範例 1:EXECUTE
意圖錯誤回應
一位使用者在客廳安裝了兩盞智慧型燈具。使用者發出「開啟客廳燈具」的指令,而 Google 將 EXECUTE
意圖傳送至執行要求網址。您發現使用者的裝置處於離線狀態,且無法控制,因此您的執行要求會傳回含有 status
ERROR
和 errorCode
deviceOffline
的 EXECUTE
回應。
以下範例說明如何從淺色裝置使用 errorCode
傳回 EXECUTE
回應,如前文所述:
{ "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 會在收到回應後提示使用者「目前無法使用裝置」。請記得,在 EXECUTE
回應中傳送 errorCode
deviceOffline
後,您仍需要傳送裝置狀態的離線狀態。
範例 2:EXECUTE
意圖的非封鎖例外狀況
使用者嘗試使用 Assistant 鎖定裝置,將前門鎖上鎖。您可以成功控制這些鎖定,但發現裝置電力不足,因此您的執行要求會傳回含有 status
SUCCESS
和 exceptionCode
lowBattery
的 EXECUTE
回應。
以下範例說明如何從鎖定裝置,利用 exceptionCode
傳送 EXECUTE
回應:
{ "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 主動通知,可以在錯誤發生時主動通知使用者。
一個智慧型乾燥機正在運行,有人在車子結束前就開啟車門。
您可以呼叫 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 會在顯示通知後提示使用者「裝置開啟」畫面。您可以在相同的酬載中傳送對應的裝置狀態及通知。
範例 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
,請參閱錯誤和例外狀況參考說明文件。