Te damos la bienvenida al Centro para desarrolladores de Google Home, el nuevo destino para aprender a desarrollar acciones para el hogar inteligente. Nota: Continuarás compilando acciones en la Consola de Actions.

Soluciona errores y excepciones

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Cuando los dispositivos o las solicitudes no funcionan como se espera, es importante proporcionar un buen manejo de errores y comunicación para tus usuarios, de modo que comprendan lo que sucedió y, siempre que sea posible, cómo corregirlo. Asegúrate de pensar en posibles situaciones de falla y cómo responderá el dispositivo: ¿Qué sucede si un usuario interrumpe una tarea en curso? ¿Qué sucede si un usuario solicita una acción desde un dispositivo sin conexión? Planificar estos problemas y ayudar a que el usuario se recupere de ellos puede evitar que se sienta frustrado y crear una experiencia de mayor calidad para tus dispositivos.

En esta guía, se proporcionan algunos ejemplos de respuestas a intents que controlan errores. Consulta Errores y excepciones para revisar los valores válidos de errorCode 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 “enciende las luces de la sala de estar” y Google envió un intent EXECUTE a tu URL de entrega. Notaste que los dispositivos del usuario están sin conexión y no se pueden controlar, por lo que la 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 de un dispositivo liviano, 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"
      }
    ]
  }
}

Google Assistant will prompt the user with "the device are not available right now" after receiving the response. Remember that you still need to send offline state for devices in report state after sending errorCode deviceOffline in EXECUTE response.

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

Un usuario intenta bloquear su cerradura inteligente en la puerta principal mediante el dispositivo con Assistant. Puedes controlar su bloqueo correctamente, pero te das cuenta de 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ó 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 pedirá al usuario que "el dispositivo tenga 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 particular, para las funciones que los usuarios esperan completar automáticamente. Para las características que admiten notificaciones proactivas, puedes notificar al usuario de forma proactiva mientras se produce un error si implementaste smart home proactive notifications..

Una secadora inteligente está funcionando, y alguien abre la puerta antes de que termine el ciclo. Puedes llamar al Google Home Graph API reportStateAndNotifications method to send a proactive notification with an errorCode:

En este ejemplo, se muestra cómo enviar una notificación proactiva con un errorCode desde un dispositivo de secado, 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 solicitará al usuario que "se abra 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

Para los comandos de características 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 notificaciones de seguimiento smart home.

Un usuario emite un comando para cerrar la puerta de su cochera, pero la puerta está atascada 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 pedirá al usuario que "el dispositivo esté atascado" después de recibir la notificación. Puedes enviar los estados del dispositivo correspondiente con notificaciones en la misma carga útil.

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