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 que los usuarios entiendan y, siempre que sea posible, cómo corregirlo. Asegúrate de analizar de posibles errores y cómo responderá tu dispositivo: ¿qué sucede si un usuario interrumpe una tarea en curso? ¿Qué sucede si un usuario solicita una acción a un dispositivo? mientras está sin conexión? Planifica para enfrentar estos problemas y ayudar al usuario a recuperarse puede evitar la frustración del usuario y crea una experiencia de mayor calidad para tus dispositivos.

En esta guía, se proporcionan algunos ejemplos de respuestas de intent que controlan errores. Consulta los Errores y excepciones en revisa los valores válidos de errorCode para detectar 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 para "encender las luces de la sala de estar" y Google enviaron un EXECUTE a tu URL de entrega. Detectamos que los dispositivos del usuario están sin conexión y no es controlable, 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"
      }
    ]
  }
}

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

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

Un usuario intenta trabar su cerradura inteligente en la puerta principal usando un dispositivo con Assistant Puedes controlar la cerradura correctamente, pero si detectas que la batería del dispositivo está baja, por lo que tu entrega mostrará un EXECUTE. respuesta 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"
      }
    }]
  }
}

El Assistant le pedirá al usuario que indique que el dispositivo tiene poca carga. batería" después de recibir la respuesta.

Ejemplo 3: Notificaciones proactivas de errores

En algunos casos, puede ser útil alertar a los usuarios de un error, especialmente para funciones que los usuarios esperan completar automáticamente. Para los rasgos que admiten notificaciones proactivas, puedes notificar de manera proactiva al usuario mientras ocurre 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 a la API de Google Home Graph método reportStateAndNotifications para enviar una notificación proactiva con un errorCode:

Este ejemplo muestra cómo enviar una notificación proactiva con un errorCode en una 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
        }
      }
    }
  }
}

El Assistant le pedirá al usuario que indique que la puerta del dispositivo está abierto" después de recibir la notificación. Puedes enviar el estados del dispositivo junto con notificaciones en la misma carga útil.

Ejemplo 4: Notificación de seguimiento

Para los comandos de rasgos que admiten notificaciones de seguimiento, puedes enviar un notificación de seguimiento al usuario cuando 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 la cochera, pero la puerta está atascada durante el cierre. 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 solicitará al usuario que indique "el dispositivo es atascado" después de recibir la notificación. Puedes enviar el estados del dispositivo con notificaciones en la misma carga útil.

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