Cuando los dispositivos o las solicitudes no funcionan como se espera, es importante proporcionar un buen manejo de errores y comunicación para que los usuarios comprendan lo que sucedió y, cuando sea posible, cómo corregirlo. Asegúrate de analizar posibles situaciones de falla 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 de un dispositivo mientras está sin conexión? Planificar estos problemas y ayudar al usuario a recuperarse de ellos puede evitar la frustración 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
la sección Errores y excepciones para
revisar los valores errorCode válidos para errores y excepciones.
Ejemplo 1: Respuesta de error para el intent EXECUTE
Un usuario final tiene dos luces inteligentes instaladas en su sala de estar. El usuario emite el 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 muestra una respuesta EXECUTE con status ERROR y errorCode deviceOffline.
En este ejemplo, se muestra cómo mostrar una respuesta EXECUTE con un errorCode desde un dispositivo de luz 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" } ] } }
Después de recibir la respuesta, el Google Assistant le indica al usuario que los dispositivos no están disponibles en este momento. Recuerda que debes enviar el estado sin conexión de los dispositivos en el estado del informe después de enviar errorCode deviceOffline en la respuesta EXECUTE.
Ejemplo 2: Excepción no bloqueadora para el intent EXECUTE
Un usuario intenta bloquear la cerradura inteligente de su puerta principal con
Assistant. Puedes controlar correctamente la cerradura, pero descubres que la batería del dispositivo está baja, por lo que tu entrega muestra 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 bloqueo 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" } }] } }
Después de recibir la respuesta, el Assistant le indica al usuario que el dispositivo tiene poca batería.
Ejemplo 3: Notificaciones de error proactivas
En algunos casos, puede ser útil alertar a los usuarios sobre un error, en particular 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 smart home notificaciones proactivas.
Una secadora inteligente está en funcionamiento y alguien abre la puerta antes de que termine el ciclo.
Puedes llamar al método de la API Google Home Graph para enviar una notificación proactiva con un
errorCode:reportStateAndNotifications
En este ejemplo, se muestra cómo enviar una notificación proactiva con un errorCode desde un dispositivo de secadora 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 } } } } }
Después de recibir la notificación, el Assistant le indica al usuario que la puerta del dispositivo está abierta. Puedes enviar los estados de los dispositivos 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 mientras se produce un error o una excepción si implementaste smart home notificaciones de seguimiento.
Un usuario emite un comando para cerrar la puerta de su 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 } } } } }
Después de recibir la notificación, el Assistant le indica al usuario que el dispositivo está atascado. Puedes enviar los estados de los dispositivos correspondientes con las 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.