Quando i dispositivi o le richieste non funzionano come previsto, è importante fornire una buona gestione degli errori e una buona comunicazione agli utenti in modo che comprendano cosa è successo e, se possibile, come correggere il problema. Assicurati di pensare ai possibili scenari di errore e a come risponderà il tuo 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 questi problemi e aiutare l'utente a risolverli può evitare frustrazioni e creare un'esperienza di qualità superiore per i tuoi dispositivi.
Questa guida fornisce alcuni esempi di risposte all'intent che gestiscono gli errori. Consulta la sezione Errori ed eccezioni per esaminare i valori errorCode validi per errori ed eccezioni.
Esempio 1: risposta di errore per l'intent EXECUTE
Un utente finale ha installato due lampadine smart in salotto. L'utente
esegue il comando "accendi le luci in salotto" e Google ha inviato un'EXECUTE
intenzione al tuo URL di evasione. Hai scoperto che i dispositivi dell'utente sono offline
e non controllabili, quindi 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 di illuminazione, 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 "il dispositivo non è disponibile al momento". Ricorda che devi comunque inviare lo stato offline per i dispositivi in stato di report dopo aver inviato errorCode deviceOffline nella risposta EXECUTE.
Esempio 2: eccezione non di blocco per l'intent EXECUTE
Un utente tenta di chiudere la serratura smart della porta d'ingresso utilizzando un dispositivo conAssistant. Puoi controllare la serratura, ma la batteria del dispositivo è in esaurimento, pertanto il completamento 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 chiusura 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 di confermare che la batteria del dispositivo è in esaurimento.
Esempio 3: notifiche di errori proattive
In alcuni casi, può essere utile avvisare gli utenti di un errore, in particolare per le funzioni che si aspettano di completare automaticamente. Per i trait che supportano le notifiche proattive, puoi informare in modo proattivo l'utente quando si verifica un errore se hai implementato le smart home notifiche proattive.
Un'asciugatrice smart è in funzione e qualcuno apre la porta prima del termine del ciclo.
Puoi chiamare il metodo reportStateAndNotifications
Google Home Graph dell'API per inviare una notifica proattiva con un
errorCode:
Questo esempio mostra come inviare una notifica proattiva con un
errorCode da un dispositivo asciugatrice 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 "la porta del dispositivo è aperta". Puoi inviare gli stati del dispositivo corrispondenti insieme alle notifiche nello stesso payload.
Esempio 4: notifica di follow-up
Per i comandi dei tratti che supportano le notifiche di follow-up, puoi inviare una notifica di follow-up all'utente quando si verifica un errore o un'eccezione, se hai implementato le smart home notifiche di follow-up.
Un utente emette un comando per chiudere la porta del garage, ma la porta si blocca 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 di confermare che il dispositivo è bloccato. Puoi inviare gli stati del dispositivo corrispondenti con le notifiche nello stesso payload.
Per ulteriori informazioni e dettagli su errorCodes, consulta la documentazione di riferimento su Errori ed eccezioni.