Google Home Vitals (Cloud)

Este conjunto de paneles y alertas te ayuda a mantener de forma proactiva una integración de alta calidad con el ecosistema de Google Home. Google se compromete a ayudar a los socios a desarrollar un ecosistema de alta calidad para todos los clientes.

El panel tiene tres secciones, cada una de las cuales abarca una parte clave que contribuye a la calidad de una integración general.

1. Métricas de Google para socios: Miden el estado de las llamadas de Google a tu backend de la nube.

2. System Health - Partner to Google Metrics: Mide el estado de las llamadas desde tu sistema a Google.

3. Estado del dispositivo: Precisión del estado: Mide la precisión de los estados almacenados en los sistemas de Google, que se usan para responder las búsquedas de los usuarios.

Cuando las métricas no alcanzan sus valores objetivo, se destacan en rojo para indicar un problema que podría afectar la experiencia del usuario. La siguiente información proporciona detalles sobre cada objetivo y por qué es importante para tus usuarios.

Si el siguiente botón no te lleva directamente al panel, puedes acceder a él seleccionando la página Descripción general, luego Paneles y, en la lista Mis paneles, selecciona Panel de signos vitales de Google Home (Cloud) para ver tu panel.

Ir al panel

Métricas de Google al socio

La métrica Tasa de éxito de la consulta/ejecución >= 99.5% mide la frecuencia con la que se cumplen correctamente los comandos de los usuarios, lo que ayuda a evitar respuestas de Asistente como "No puedo acceder al dispositivo" o confirmar de forma incorrecta un comando que aún no se cumplió.

¿Qué define un "éxito"?

Una transacción se marca como exitosa si la plataforma de Google Home recibe una respuesta válida que indica que se completó la acción prevista o que se recuperó el estado solicitado.

Las respuestas que incluyen excepciones que no generan un bloqueo (por ejemplo, un estado SUCCESS acompañado de una excepción lowBattery) se consideran transacciones exitosas. El comando llegó al dispositivo y se satisfizo la intención a pesar de la advertencia.

¿Qué define un "error"?

Los errores que se encuentran en Códigos de error comunes de la plataforma y que se marcan como Acción del socio se consideran "Fallos" cuando se calculan las tasas de éxito de QUERY y EXECUTE. Además, los errores que se encuentran en Errores y excepciones también son "Fallas", con las siguientes excepciones:

La métrica Latencia de consulta/ejecución (percentil 90) <= 1,000 ms mide el tiempo de espera de la acción solicitada y ayuda a garantizar que los usuarios no tengan que esperar demasiado, por ejemplo, unos segundos para que se apague la luz.

Métricas de latencia

La latencia es un indicador fundamental de la capacidad de respuesta de tu integración para el usuario final. El panel supervisa la latencia del percentil 90 (P90), que representa la experiencia de los usuarios "más lentos" (por ejemplo, un P90 de 800 ms significa que el 90% de las solicitudes se confirman en 800 ms o menos).

Google mide la latencia de manera diferente para las verificaciones de estado y los comandos del dispositivo para garantizar la precisión técnica.

1. Latencia de la consulta (interrogativa)

Esto mide el tiempo de ida y vuelta de Cloud-to-cloud cuando Google solicita el estado actual de un dispositivo.

• Inicio: Google envía una solicitud action.devices.QUERY a la URL de cumplimiento.
• Ventana de medición: Es el tiempo que tarda tu nube en recibir, procesar y transmitir la respuesta HTTP completa a Google.
• Fin: Google recibe y confirma la recepción de la carga útil de la respuesta final de tu servicio.

2. Latencia de EXECUTE (acción)

Mide el tiempo de confirmación del comando cuando Google envía una solicitud de control a un dispositivo.

• Inicio: Google envía una solicitud action.devices.EXECUTE a la URL de cumplimiento.
• Ventana de medición: Es el tiempo que tarda tu nube en recibir el comando y devolver una respuesta de confirmación.
• Finalización: Google recibe la respuesta de estado SUCCESS, PENDING o OFFLINE.
• Alcance técnico: Esta métrica mide el tiempo de "confirmación de respuesta" entre la nube de Google y tu nube. No mide el tiempo que tarda el hardware físico (por ejemplo, una bombilla) en completar el cambio de estado físico, ya que a menudo implica una latencia de red en malla local fuera de la ruta de nube a nube.

Opciones de reducción de latencia

Recomendaciones de arquitectura para el enrutamiento geográfico

Si la implementación de IP de Anycast no es factible, te recomendamos las siguientes alternativas rentables para garantizar que los usuarios reciban servicio del centro de datos regional más cercano.

1. Balanceo de cargas global (GLB)

   En lugar del enrutamiento estático, usa un balanceador de cargas de aplicaciones global (disponible en la mayoría de los principales proveedores de servicios en la nube).

   • Cómo funciona: Configuras un solo punto de entrada global (URL) que se encuentra en el borde de la red. El balanceador de cargas detecta automáticamente el origen geográfico de la solicitud desde los clústeres de cumplimiento de Google y enruta el tráfico a tu backend regional en buen estado más cercano.

   • Beneficio: Proporciona el rendimiento de Anycast con un costo y una complejidad de configuración significativamente menores.

2. DNS con reconocimiento de ubicación geográfica (GeoDNS)

   • Cómo funciona: Configura tu proveedor de DNS para que resuelva la URL de cumplimiento en diferentes direcciones IP según la ubicación geográfica de la consulta de DNS.

   • Implementación: Asegúrate de que tu proveedor de DNS esté optimizado para los puntos de salida de Google. Cuando los servicios de cumplimiento regionales de Google (por ejemplo, en EE.UU., la UE o Asia) resuelvan tu dominio, recibirán la dirección IP del centro de datos en esa región específica.

Estrategias de optimización en la capa de aplicación

Además del enrutamiento a nivel de la infraestructura, puedes implementar las siguientes estrategias a nivel de la aplicación para reducir la latencia en el procesamiento de solicitudes.

1. El método de proxy "Trampoline"

   Si debes mantener un centro de datos principal, usa servidores proxy ligeros regionales (Trampolines) para controlar el handshake inicial.

   1. Google accede a tu URL global.

   2. Un proxy regional (por ejemplo, una función ligera de Nginx o Lambda) recibe la solicitud.

   3. El proxy reenvía la carga útil a través de tu red troncal interna de alta velocidad a la base de datos principal.

   Beneficio: Esto reduce el tiempo de "negociación TCP", que suele ser el mayor factor que contribuye a la latencia en las solicitudes de larga distancia.

2. Sugerencias de región del token de acceso

   Durante el proceso de vinculación de cuentas (OAuth), tu sistema puede identificar la región de la casa del usuario.

   Implementación: Codifica un identificador de región en el access_token que se emite a Google. Cuando Google envía una solicitud de cumplimiento, tu puerta de enlace puede inspeccionar el token de inmediato y enrutar la solicitud al clúster regional correcto sin necesidad de buscar en una base de datos.

Estado del sistema: Métricas de socio a Google

Mantener un porcentaje de éxito >= 99.5% ayuda a garantizar que los estados de los dispositivos sean correctos en Google Home, que los dispositivos se agreguen y quiten, que se activen las automatizaciones y que los eventos del historial aparezcan en la pestaña Actividad del Google Home app (GHA).

La tasa de éxito se calcula en función de los códigos de respuesta HTTP que muestra Google cuando tu nube envía actualizaciones de estado. Para garantizar que los socios no reciban penalizaciones por problemas de infraestructura del lado de Google, la métrica excluye los errores internos de Google del recuento de fallas. Las llamadas a la API incluidas en el cálculo se encuentran en la referencia de la API de HomeGraph.

¿Qué define un "éxito"?

2xx (Correcto): Home Graph recibió y procesó correctamente la actualización de estado.

¿Qué define un "error"?

Los errores 4xx (error del socio) representan fallas y señalan un problema con la solicitud enviada desde tu nube. Entre los códigos comunes, se incluyen los siguientes:

400 Bad Request

Causa: El servidor no pudo procesar la solicitud debido a una sintaxis no válida. Entre las causas comunes, se incluyen el uso de JSON con formato incorrecto o el uso de null en lugar de "" para un valor de cadena.

Solución: Asegúrate de que el cuerpo de la solicitud sea un JSON válido (sin estructura incorrecta ni valores nulos para los campos de cadena) y verifica que agentUserId coincida con el valor de la respuesta de SYNC.

404 No encontrado

Causa: No se encontró deviceId o agentUserId en HomeGraph (aún no se sincronizó, ya se desvinculó o hay una discrepancia en el ID).

Solución:

1. Asegúrate de que agentUserId coincida con el valor proporcionado en tu respuesta de SYNC.
2. Usa la API de SYNC de Home Graph para determinar si el error 404 Not Found se debe a la falta de un dispositivo o un usuario en Home Graph.
3. Asegúrate de activar requestSync después de agregar, quitar, cambiar el nombre o actualizar el dispositivo o la cuenta para garantizar que el estado se mantenga actualizado.
4. Se controlan correctamente los intents de DISCONNECT para dejar de informar sobre dispositivos inactivos. Después de recibir la intención DISCONNECT, tu servicio en la nube debe dejar de publicar cambios en Google con Request Sync y Report State.

429, Recurso agotado

Causa: Tu integración superó la cuota asignada.

Solución: Consulta las instrucciones en la sección "Paso 2a: Depura problemas de cuota" del panel para la administración de cuotas. También puedes consultar Cuotas y límites de Smart Home para obtener más información.

Estado del dispositivo: Precisión del estado

Cumplir o superar un State Accuracy >= 99.5% ayuda a garantizar que los usuarios vean resultados correctos cuando consulten los estados de los dispositivos o usen funciones basadas en IA, como Pregúntale a Home. Si la precisión del estado es baja, es posible que las automatizaciones no se activen y que las entradas del historial no aparezcan en la pestaña Actividad de GHA en el momento adecuado. Para obtener más información, consulta Report State. Nota: Se debe cumplir con el objetivo de precisión del estado en TODOS los rasgos admitidos.

1. Componentes de precisión

La métrica se deriva de "muestras" en las que Google puede verificar el estado informado en comparación con el resultado conocido de la intención. En cuanto a la precisión técnica, la exactitud se evalúa en dos rutas distintas:

• Precisión basada en consultas: Se verifica cuando un usuario o un sistema interroga de forma activa el estado actual de un dispositivo.
• Precisión de EJECUCIÓN: Se verifica evaluando el estado del dispositivo posterior al comando que se informa después de una solicitud de control.

2. Métricas del panel (cálculo por hora)

El panel calcula la precisión en función de un intervalo de 1 hora. Para garantizar la confianza estadística y evitar penalizar las integraciones con ruido de baja señal, Google aplica un umbral mínimo de volumen de tráfico. Si una combinación específica de rasgo y dispositivo acumula menos de 100 muestras totales en un período continuo de 5 días, su precisión se considera estadísticamente insignificante y se establece en N/A.

Cuando una hora tiene un volumen de muestras suficiente en ambas rutas, la precisión por hora de referencia para un estado específico se calcula como el promedio de los dos porcentajes independientes:

Precisión por hora del estado = (Precisión de la búsqueda % + Precisión de la ejecución %) / 2

Cada ruta de acceso se define de la siguiente manera:

• Porcentaje de precisión de la búsqueda = (Muestras precisas de búsquedas por hora) / (Muestras totales de búsquedas por hora)
• Porcentaje de precisión de la ejecución = (Muestras precisas de ejecución por hora) / (Muestras totales de ejecución por hora)

Puntuación de exactitud del rasgo (calculada por rasgo) = SUM(Muestras precisas de la búsqueda + Muestras precisas de la ejecución) / SUM(Muestras totales de la búsqueda + Muestras totales de la ejecución)

Dado que el Nivel de calidad evalúa el rendimiento del mínimo estricto en todo tu ecosistema, cada rasgo admitido y apto debe cumplir individualmente el objetivo de precisión del estado >= 99.5% (este no es un promedio entre los rasgos).

Esta vista evita que los dispositivos con un volumen alto y una precisión excelente oculten los problemas de precisión en los dispositivos con un volumen más bajo. Los socios que se preocupan por que los atributos subutilizados reduzcan su puntuación pueden tener la certeza de que la verificación del volumen de tráfico mínimo protege automáticamente los atributos que se usan con poca frecuencia y no se tendrán en cuenta en la puntuación de tipo y atributo más bajos, a menos que cumplan con el umbral de muestras requerido.

3. Mejora de la precisión del estado y el estado del dispositivo

Las discrepancias se producen cuando el estado almacenado en Home Graph no coincide con los resultados de una QUERY en tiempo real.

Errores de "Falta el campo"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

Causa: Con el error DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD o DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, el conjunto de campos de carga útil difiere entre tu respuesta de QUERY y tu solicitud de Report State para el mismo dispositivo.

Solución: Asegúrate de que la estructura de datos sea idéntica en ambas rutas. Si un rasgo se incluye en SYNC, sus campos correspondientes deben estar presentes y ser coherentes tanto en los informes proactivos como en las búsquedas reactivas.

Errores de "imprecisión"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

Causa: En el caso del error DETAILED_ACCURACY_RESULT_INACCURATE, existe una discrepancia entre el valor que se muestra en la respuesta de QUERY y el último valor de Report State.

Solución: Asegúrate de que se active Report State cada vez que cambie el estado de un dispositivo y de que tanto Report State como QUERY siempre proporcionen los mismos valores actualizados y todos los campos obligatorios para mantener la coherencia de los datos.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

Causa: Con el error DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, el socio ejecutó el comando correctamente, pero no informó a Google sobre el estado actualizado del dispositivo.

Solución: Siempre envía una actualización de Report State después de la ejecución del comando para que HomeGraph reciba el nuevo estado del dispositivo.

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

Causa: En el caso del error DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, no se recibió ningún ReportState para este dispositivo (el estado está vacío y la marca de tiempo informada está en la época), a pesar de que los resultados de QUERY proporcionan el estado actual. Esto indica que no se activan las actualizaciones de estado, que no llegan a HomeGraph o que el dispositivo no informa correctamente las transiciones en su conectividad o estado operativo.

Solución: Asegúrate de que se active y envíe correctamente el estado del informe para todos los cambios de estado. Verifica que la lógica de backend controle correctamente las actualizaciones de estado, confirme el éxito de la entrega a Google HomeGraph y garantice que el dispositivo sincronice su estado de forma coherente para mantener la precisión de la interfaz de usuario y el motor de automatización.