Quando i dispositivi o le richieste non funzionano come previsto, è importante offrire agli utenti una buona gestione degli errori e una buona comunicazione, in modo che capiscano cosa è successo e, quando possibile, come correggerlo. Assicurati di considerare i possibili scenari di errore e la risposta del dispositivo: cosa succede se un utente interrompe un'attività in corso? Che cosa succede se un utente richiede un'azione da un dispositivo mentre è offline? Pianificare per risolvere questi problemi e aiutare l'utente a riprendersi può evitarne la frustrazione e creare un'esperienza di qualità superiore per i tuoi dispositivi.
Questa guida fornisce alcuni esempi di risposte di intent che gestiscono gli errori. Consulta Errori ed eccezioni per esaminare i valori errorCode
validi per individuare errori ed eccezioni.
Esempio 1: risposta di errore per l'intent EXECUTE
Un utente finale ha due luci smart installate in salotto. L'utente
emette un comando "accendi le luci in salotto" e Google ha inviato un intent EXECUTE
all'URL di evasione degli ordini. Hai riscontrato che i dispositivi dell'utente sono offline e non controllabili, pertanto il tuo fulfillment restituisce una risposta EXECUTE
con status
ERROR
e errorCode
deviceOffline
.
Questo esempio mostra come restituire una risposta EXECUTE
con un errorCode
da un dispositivo leggero, come descritto in precedenza:
{ "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" } ] } }
Dopo aver ricevuto la risposta, Google Assistant chiederà all'utente che ha ricevuto la risposta "il dispositivo non è disponibile al momento". Ricorda che devi comunque inviare lo stato offline per i dispositivi in stato di report dopo l'invio di errorCode
deviceOffline
nella risposta EXECUTE
.
Esempio 2: eccezione che non comporta alcun blocco per l'intent EXECUTE
Una utente prova a chiudere la serratura smart della porta principale utilizzando il dispositivo con
Assistant. Puoi controllare correttamente il blocco, ma ti accorgi che la batteria del dispositivo è in esaurimento, quindi l'evasione degli ordini restituisce una risposta EXECUTE
con status
SUCCESS
e exceptionCode
lowBattery
.
Questo esempio mostra come inviare una risposta EXECUTE
con un exceptionCode
da un dispositivo di blocco, come descritto in precedenza:
{ "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" } }] } }
Dopo aver ricevuto la risposta, Assistant chiederà all'utente che "il dispositivo ha la batteria in esaurimento".
Esempio 3: notifiche di errore proattive
In alcuni casi, può essere utile avvisare gli utenti di un errore, in particolare per le funzioni che gli utenti si aspettano di completare automaticamente. Per i trait che supportano le notifiche proattive, se hai implementato le smart home notifiche proattive, puoi notificare proattivamente l'utente quando si verifica un errore.
Una smart asciugatrice è in funzione e qualcuno apre la porta prima del termine del ciclo.
Puoi chiamare il metodo Google Home Graph API reportStateAndNotifications
per inviare una notifica proattiva con un errorCode
:
Questo esempio mostra come inviare una notifica proattiva con errorCode
da un dispositivo di asciugatura, come descritto in precedenza:
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 } } } } }
Dopo aver ricevuto la notifica, Assistant chiederà all'utente che lo sportello del dispositivo è aperto. Puoi inviare gli stati del dispositivo corrispondenti insieme alle notifiche nello stesso payload.
Esempio 4: notifica di follow-up
Per i comandi dei trait che supportano le notifiche di follow-up, puoi inviare una notifica di follow-up all'utente mentre si verifica un errore o un'eccezione, se hai implementato le smart home notifiche di follow-up.
Un utente invia un comando per chiudere la porta del garage, ma la porta è bloccata durante la chiusura. Puoi inviare una notifica di follow-up con un 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 } } } } }
Dopo aver ricevuto la notifica, Assistant chiederà all'utente che "il dispositivo è bloccato". Puoi inviare gli stati del dispositivo corrispondenti con notifiche nello stesso payload.
Per ulteriori informazioni e i dettagli di errorCodes
, consulta la documentazione di riferimento Errori ed eccezioni.