Cuando los dispositivos o las solicitudes no funcionan como se espera, es importante proporcionar un buen manejo de errores y una buena comunicación para los usuarios, de modo que comprendan lo que sucedió y, siempre que sea posible, cómo corregirlo. Asegúrate de pensar en posibles situaciones de error y cómo debería responder tu dispositivo: ¿Qué sucede si un usuario interrumpe una tarea en curso? ¿Qué sucede si un usuario solicita una acción desde un dispositivo mientras está sin conexión? Planificar para estos problemas y ayudar al usuario a recuperarse de ellos puede evitar la frustración del usuario y crear una experiencia de mayor calidad para tus dispositivos.
En esta guía, se proporcionan algunos ejemplos de respuestas de intents que controlan errores. Consulta
Errores y excepciones para
revisar los valores válidos de errorCode para errores y excepciones.
Ejemplo 1: Respuesta de error para el intent EXECUTE
Un usuario final tiene dos lámparas inteligentes instaladas en su sala de estar. El usuario
emite un comando "enciende las luces de la sala de estar" y Google envió un intent EXECUTE
a tu URL de entrega. Descubriste que los dispositivos del usuario están sin conexión
y no se pueden controlar, por lo que tu entrega devuelve una respuesta EXECUTE con
status ERROR y errorCode deviceOffline.
En este ejemplo, se muestra cómo devolver una respuesta EXECUTE con un errorCode desde un dispositivo de iluminación, como se describió anteriormente:
{ "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" } ] } }
El Google Assistant le indica al usuario que "el dispositivo no está disponible ahora mismo" después de recibir la respuesta. Recuerda que aún
debes enviar el estado sin conexión de los dispositivos en el estado del informe después de enviar
errorCode deviceOffline en la respuesta de EXECUTE.
Ejemplo 2: Excepción no bloqueante para el intent EXECUTE
Un usuario intenta trabar la cerradura inteligente de la puerta de entrada con
Assistant. Puedes controlar correctamente la cerradura, pero
descubres que la batería del dispositivo está baja, por lo que tu entrega devuelve una respuesta
EXECUTE con status SUCCESS y exceptionCode lowBattery.
En este ejemplo, se muestra cómo enviar una respuesta EXECUTE con un exceptionCode desde un dispositivo de cerradura, como se describió anteriormente:
{ "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" } }] } }
El Assistant le indica al usuario que "el dispositivo tiene poca batería" después de recibir la respuesta.
Ejemplo 3: Notificaciones de error proactivas
En algunos casos, puede ser útil alertar a los usuarios sobre un error, en especial para las funciones que los usuarios esperan que se completen automáticamente. En el caso de los atributos que admiten notificaciones proactivas, puedes notificar al usuario de forma proactiva mientras se produce un error si implementaste las notificaciones proactivas de smart home.
Una secadora inteligente está en funcionamiento y alguien abre la puerta antes de que termine el ciclo.
Puedes llamar al método reportStateAndNotifications de la API de Google Home Graph para enviar una notificación proactiva con un errorCode:
En este ejemplo, se muestra cómo enviar una notificación proactiva con un errorCode desde un dispositivo secador, como se describió anteriormente:
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 } } } } }
El Assistant le indica al usuario que "la puerta del dispositivo está abierta" después de recibir la notificación. Puedes enviar los estados de dispositivo correspondientes junto con las notificaciones en la misma carga útil.
Ejemplo 4: Notificación de seguimiento
En el caso de los comandos de atributos que admiten notificaciones de seguimiento, puedes enviar una notificación de seguimiento al usuario cuando se produce un error o una excepción, si implementaste las notificaciones de seguimiento de smart home.
Un usuario emite un comando para cerrar la puerta de la cochera, pero la puerta se atasca mientras se cierra. Puedes enviar una notificación de seguimiento 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 } } } } }
El Assistant le indica al usuario que "el dispositivo está atascado" después de recibir la notificación. Puedes enviar los estados correspondientes del dispositivo con notificaciones en la misma carga útil.
Para obtener más información y errorCodes detallados, consulta la documentación de referencia de Errores y excepciones.