Soluciona errores y excepciones

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 a fin de que comprendan lo que sucedió y, cuando sea posible, cómo corregirlo. Asegúrate de pensar en posibles situaciones de falla y cómo responderá el dispositivo: ¿qué pasa 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 estos problemas y ayudar al usuario a recuperarse de ellos puede evitar su frustración y crear una experiencia de mayor calidad para tus dispositivos.

En esta guía, se proporcionan algunos ejemplos de respuestas de intent que controlan errores. Consulta Errores y excepciones para revisar los valores de errorCode válidos en busca de errores y excepciones.

Ejemplo 1: Respuesta de error para el intent EXECUTE

Un usuario final tiene dos lámparas inteligentes instaladas en la sala de estar. El usuario emite un comando "encender 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 liviano, como se describió antes:

{
  "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"
      }
    ]
  }
}

Google Assistant le solicitará al usuario que diga "el dispositivo no está disponible en este momento" después de recibir la respuesta. Recuerda que aún necesitas enviar el estado sin conexión para los dispositivos en estado del informe después de enviar errorCode deviceOffline en la respuesta EXECUTE.

Ejemplo 2: Excepción sin bloqueo para el intent EXECUTE

Un usuario intenta bloquear su cerradura inteligente en la puerta principal con un dispositivo con Assistant. Puedes controlar correctamente su bloqueo, pero la batería del dispositivo es 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ó antes:

{
  "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 le mostrará al usuario "el dispositivo tiene batería baja" 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 completar automáticamente. En el caso de las características 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 finalice 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 de secadora como se describió antes:

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 le informará al usuario que "se abrió la puerta del dispositivo" después de recibir la notificación. Puedes enviar los estados del dispositivo correspondientes junto con las notificaciones en la misma carga útil.

Ejemplo 4: Notificación de seguimiento

En el caso de los comandos de traits 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 las notificaciones de seguimiento smart home.

Un usuario emite un comando para cerrar la puerta de la cochera, pero la puerta se bloquea cuando 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
        }
      }
    }
  }
}

Assistant le preguntará al usuario que "el dispositivo está atascado" después de recibir la notificación. Puedes enviar los estados del dispositivo correspondientes con notificaciones en la misma carga útil.

Para obtener más información y detalles sobre errorCodes, consulta la documentación de referencia Errores y excepciones.