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.