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 correggere il problema. Assicurati di aver pensato a possibili scenari di errore e a come deve rispondere il tuo dispositivo: cosa succede se un utente interrompe un'attività in corso? Cosa succede se un utente richiede un'azione da un dispositivo mentre è offline? Pianificare la risoluzione di questi problemi e aiutare l'utente a superarli può evitare frustrazioni 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
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 fulfillment. Hai scoperto che i dispositivi dell'utente sono offline
e non controllabili, quindi il 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" } ] } }
Google Assistant chiede all'utente "Il dispositivo non è
disponibile al momento" dopo aver ricevuto la risposta. Ricorda che devi comunque
inviare lo stato offline per i dispositivi nello stato del report dopo l'invio
di 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'evasione 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" } }] } }
Assistant chiede all'utente "la batteria del dispositivo è in esaurimento" dopo aver ricevuto la risposta.
Esempio 3: notifiche proattive degli errori
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.
Una smart dryer è 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'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 } } } } }
Il Assistant chiede all'utente "la porta del dispositivo è aperta" 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 le smart home notifiche di follow-up.
Un utente invia 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 } } } } }
Assistant chiede all'utente "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.