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 valutare i possibili scenari di errore e come dovrebbe rispondere il 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 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 chiede all'utente "il dispositivo non è attualmente disponibile". 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 bloccante per l'intent EXECUTE
Un utente tenta di chiudere a chiave la serratura smart della porta d'ingresso utilizzandoAssistant. 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 chiede all'utente "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 le caratteristiche che supportano le notifiche proattive, puoi informare l'utente in modo proattivo 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
}
}
}
}
}
Assistant chiede all'utente "la porta del dispositivo è aperta" dopo aver ricevuto la notifica. 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
}
}
}
}
}
Assistant chiede all'utente "il dispositivo è bloccato" dopo aver ricevuto la notifica. 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.