Quando i dispositivi o le richieste non funzionano come previsto, è importante fornire una buona gestione degli errori e una buona comunicazione per gli utenti, in modo che comprendano cosa è successo e, se possibile, come correggerlo. Assicurati di esaminare i possibili scenari di errore e il modo in cui il dispositivo deve rispondere: cosa succede se un utente interrompe un'attività in corso? Cosa succede se un utente richiede un'azione da un dispositivo mentre è offline? La pianificazione di questi problemi e l'aiuto all'utente per risolverli possono evitare la frustrazione dell'utente e creare un'esperienza di qualità superiore per i tuoi dispositivi.
Questa guida fornisce alcuni esempi di risposte agli 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 luci smart nel soggiorno. L'utente
emette il comando "accendi le luci del soggiorno" e Google ha inviato un intent EXECUTE
al tuo URL di esecuzione. Hai scoperto che i dispositivi dell'utente sono offline
e non controllabili, quindi l'esecuzione 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 segnala all'utente che "device non sono
disponibili al momento". Tieni presente che devi comunque inviare lo stato offline per i dispositivi nello stato del report dopo aver inviato errorCode deviceOffline nella risposta EXECUTE.
Esempio 2: eccezione non bloccante per l'intent EXECUTE
Un utente tenta di chiudere la serratura smart della porta d'ingresso utilizzando
Assistant. Puoi controllare correttamente la serratura, ma
la batteria del dispositivo è in esaurimento, quindi l'esecuzione 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" } }] } }
Assistant segnala all'utente che "la batteria del dispositivo è in esaurimento" dopo aver ricevuto la risposta.
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 le caratteristiche che supportano le notifiche proattive, puoi notificare in modo proattivo all'utente quando si verifica un errore se hai implementato le smart home notifiche proattive.
Un'asciugatrice smart è in funzione e qualcuno apre lo sportello prima che il ciclo termini.
Puoi chiamare il metodo reportStateAndNotifications dell'API Google Home Graph per inviare una notifica proattiva con un errorCode:
Questo esempio mostra come inviare una notifica proattiva con un errorCode da un dispositivo di 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 } } } } }
Assistant segnala all'utente che "lo sportello del dispositivo è aperto" dopo aver ricevuto la notifica. Puoi inviare gli stati dei dispositivi corrispondenti insieme alle notifiche nello stesso payload.
Esempio 4: notifica di follow-up
Per i comandi delle caratteristiche 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 smart home le notifiche di follow-up.
Un utente emette 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 } } } } }
Assistant segnala all'utente che "il dispositivo è bloccato" dopo aver ricevuto la notifica. Puoi inviare gli stati dei dispositivi corrispondenti con le notifiche nello stesso payload.
Per ulteriori informazioni e errorCodes dettagliati, consulta la
documentazione di riferimento Errori ed eccezioni.