Quando le richieste o i dispositivi non funzionano come previsto, è importante fornire agli utenti una buona gestione degli errori e comunicazioni in modo che capiscano cosa è successo e, ove possibile, come correggerli. Pensa a possibili scenari di errore e a come il dispositivo risponderà: se un utente interrompe un'attività in corso? Cosa succede se un utente richiede un'azione a un dispositivo mentre è offline? Pianificare questi problemi e aiutare gli utenti a riprendersi può evitare frustrazione e creare un'esperienza di qualità superiore per i tuoi dispositivi.
Questa guida fornisce alcuni esempi di risposte per intent che gestiscono errori. Consulta la sezione 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 e installato in salotto. L'utente genera un comando "Accendi le luci in salotto" e Google ha inviato un intent EXECUTE all'URL di evasione degli ordini. Hai rilevato che i dispositivi dell'utente sono offline e non possono essere controllati, 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"
}
]
}
}
Dopo aver ricevuto la risposta, Google Assistant richiederà all'utente il messaggio "dispositivo non disponibile al momento". Tieni presente che, dopo aver inviato errorCode deviceOffline nella risposta EXECUTE, devi comunque inviare lo stato offline per i dispositivi in stato di report.
Esempio 2: eccezione non bloccante per l'intent EXECUTE
Un utente tenta di chiudere la serratura smart alla porta d'ingresso utilizzando un dispositivo con
Assistant. Puoi controllare correttamente il blocco, ma trovi che la batteria del dispositivo è in esaurimento, quindi la tua distribuzione 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 dopo aver ricevuto la risposta mostrerà un messaggio che comunica all'utente che "il dispositivo è 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 intendono completare automaticamente. Per i tratti che supportano le notifiche proattive, puoi avvisare l'utente in modo proattivo mentre si verifica un errore se hai implementato le smart home notifiche proattive.
C'è un'asciugatrice smart in funzione e qualcuno apre la porta prima che finisca il ciclo.
Puoi chiamare il metodo Google Home GraphreportStateAndNotifications
per inviare una notifica proattiva con
errorCode:
Questo esempio mostra come inviare una notifica proattiva con un
errorCode da un dispositivo di essiccazione 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 mostrerà un messaggio che indica che "la porta del dispositivo è aperta". 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 durante 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 viene bloccata durante la chiusura. Puoi inviare una notifica di follow-up con il 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 richiederà all'utente di rilevare "il dispositivo è bloccato". Puoi inviare gli stati dei dispositivi corrispondenti con notifiche nello stesso payload.
Per ulteriori informazioni e errorCodes dettagliate, consulta la documentazione di riferimento relativa a
errori ed eccezioni.