Gdy urządzenia lub żądania nie działają zgodnie z oczekiwaniami, ważne jest, aby użytkownicy byli w stanie odpowiednio obsługiwać błędy i komunikować się ze sobą. Dzięki temu będą oni wiedzieć, co się stało, i jeśli to możliwe, jak rozwiązać ten problem. Przemyśl możliwe scenariusze awarii i przemyśl, jak zareaguje urządzenie: „Co się stanie, jeśli użytkownik przerwie zadanie? Co się stanie, gdy użytkownik poprosi o działanie z urządzenia, gdy jest offline? Zaplanowanie takich problemów i pomoc w ich rozwiązaniu pozwala uniknąć frustracji użytkowników i poprawić komfort korzystania z urządzeń.
Ten przewodnik zawiera kilka przykładów odpowiedzi intencji, które obsługują błędy. Zajrzyj do sekcji Błędy i wyjątki, aby sprawdzić prawidłowe wartości errorCode
pod kątem błędów i wyjątków.
Przykład 1: odpowiedź o błędzie w przypadku intencji EXECUTE
Użytkownik ma w salonie 2 inteligentne żarówki. Użytkownik wykonuje polecenie „włącz światło w salonie”, a Google wysyła zamiar EXECUTE
na Twój adres URL realizacji zamówień. Okazuje się, że urządzenia użytkownika są offline i nie można ich kontrolować, więc realizacja zwraca odpowiedź EXECUTE
z wartością status
ERROR
i errorCode
deviceOffline
.
Ten przykład pokazuje, jak w opisany wcześniej sposób zwrócić odpowiedź EXECUTE
z elementem errorCode
z urządzenia lekkiego:
{ "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" } ] } }
Po otrzymaniu odpowiedzi Google Assistant wyświetli użytkownikowi komunikat „urządzenie jest teraz niedostępne”. Pamiętaj, że nadal musisz wysyłać informacje o stanie offline w przypadku urządzeń w stanie raportu po wysłaniu errorCode
deviceOffline
w odpowiedzi EXECUTE
.
Przykład 2: wyjątek nieblokujący dla intencji EXECUTE
Użytkownik próbuje zamknąć inteligentny zamek na drzwiach wejściowych, używając urządzenia z funkcją Assistant. Możesz kontrolować blokadę urządzenia, ale okazuje się, że bateria w urządzeniu jest słaba, więc realizacja zwraca odpowiedź EXECUTE
z wartościami status
SUCCESS
i exceptionCode
lowBattery
.
Ten przykład pokazuje, jak wysłać z urządzenia blokady odpowiedź EXECUTE
z elementem exceptionCode
w sposób opisany wcześniej:
{ "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" } }] } }
Po otrzymaniu odpowiedzi Assistant wyświetli użytkownikowi komunikat „urządzenie ma niski poziom baterii”.
Przykład 3. Aktywne powiadomienia o błędach
W niektórych przypadkach warto ostrzec użytkowników o błędzie, zwłaszcza w przypadku funkcji, które użytkownicy spodziewają się wykonać automatycznie. W przypadku cech, które obsługują aktywne powiadomienia, możesz aktywnie powiadomić użytkownika o błędzie, jeśli masz zaimplementowane smart home powiadomienia proaktywne.
Inteligentna suszarka jest włączona, a ktoś otwiera drzwi przed zakończeniem cyklu.
Możesz wywołać metodę reportStateAndNotifications
interfejsu Google Home Graph API, aby wysłać aktywne powiadomienie z errorCode
:
Ten przykład pokazuje, jak wysłać z suszarki aktywne powiadomienie za pomocą polecenia errorCode
w sposób opisany wcześniej:
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 } } } } }
Po otrzymaniu powiadomienia Assistant wyświetli użytkownikowi komunikat „Drzwi urządzenia jest otwarte”. W tym samym ładunku możesz wysyłać odpowiednie stany urządzeń razem z powiadomieniami.
Przykład 4. Dalsze powiadomienie
W przypadku poleceń cechy, które obsługują kolejne powiadomienia, możesz wysłać użytkownikowi powiadomienie o błędzie lub wyjątku, jeśli masz zaimplementowane smart home powiadomienia o dalszych czynnościach.
Użytkownik wydaje polecenie zamknięcia bramy garażowej, ale podczas zamykania się zacinają. Możesz wysłać kolejne powiadomienie za pomocą urządzenia 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 } } } } }
Po otrzymaniu powiadomienia Assistant wyświetli użytkownikowi komunikat „urządzenie jest zacięte”. W tym samym ładunku możesz wysyłać odpowiednie stany urządzeń z powiadomieniami.
Więcej informacji i szczegółowe informacje na temat errorCodes
znajdziesz w dokumentacji dotyczącej błędów i wyjątków.