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 al socio : Mide el estado de las llamadas de Google a tu backend de la nube.

2. Estado del sistema: Métricas del socio a Google : Mide el estado de las llamadas de 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 atender las consultas de los usuarios.

Cuando las métricas no cumplen con 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 estadísticas vitales de Google Home (Cloud) para ver tu panel.

Ir al panel

Métricas de Google al socio

La métrica Porcentaje de éxito de consultas o ejecuciones >= 99.5% mide la frecuencia con la que se cumplen correctamente los comandos de los usuarios, lo que ayuda a evitar respuestas del 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 cumplió la acción deseada 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 el intent se satisfizo a pesar de la advertencia.

¿Qué define una "falla"?

Los errores que se encuentran en Códigos de error comunes de la plataforma y que están marcados como Acción del socio se consideran "fallas" cuando se calculan los porcentajes 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 consultas o ejecuciones (p90) <= 1000 ms mide el tiempo de espera de la acción solicitada y ayuda a garantizar que los usuarios no tengan que esperar demasiado tiempo, 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 hace un seguimiento de la latencia del percentil 90 (P90), que representa la experiencia de tus usuarios "más lentos" (por ejemplo, un P90 de 800 ms significa que el 90% de las solicitudes se reconocen en 800 ms o menos).

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

1. Latencia de QUERY (interrogativa)

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 tu URL de entrega.
• 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 reconoce la carga útil de la respuesta final de tu servicio.

2. Latencia de EXECUTE (acción)

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

• Inicio: Google envía una solicitud action.devices.EXECUTE a tu URL de entrega.
• Ventana de medición: Es el tiempo que tarda tu nube en recibir el comando y mostrar una respuesta de reconocimiento.
• Fin: Google recibe la respuesta de estado SUCCESS, PENDING o OFFLINE.
• Alcance técnico: Esta métrica mide el tiempo de "reconocimiento 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 acceso 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 único punto de entrada global (URL) que se encuentra en el perímetro de la red. El balanceador de cargas detecta automáticamente el origen geográfico de la solicitud de los clústeres de entrega de Google y enruta el tráfico a tu backend regional en buen estado más cercano.

   • Beneficio: Esto proporciona el rendimiento de Anycast con una complejidad y un costo de configuración significativamente más bajos.

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

   • Cómo funciona: Configura tu proveedor de DNS para que resuelva tu URL de entrega 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 entrega 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 en la capa de 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 regionales ligeros (Trampolines) para controlar el protocolo de enlace 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 "protocolo de enlace TCP", que suele ser el factor que más contribuye a la latencia de 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 origen del usuario.

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

Estado del sistema: Métricas del socio a Google

Mantener un porcentaje de éxito >= 99.5% ayuda a garantizar que los estados del dispositivo 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 de Google Home app (GHA).

El porcentaje 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 sean penalizados 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 (Éxito): Home Graph recibió y procesó correctamente la actualización de estado.

¿Qué define una "falla"?

4xx (Error del socio) representan fallas e indican 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 valores nulos 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 con formato incorrecto ni valores nulos para los campos de cadena) y verifica que agentUserId coincida con el valor de la respuesta SYNC.

404 No encontrado

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

Solución:

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

429 Resource Exhausted

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

Solución: Consulta las instrucciones de la sección "Paso 2a: Depura problemas de cuota" en el panel para administrar la cuota. También puedes consultar Cuotas y límites de casa inteligente para obtener más información.

Estado del dispositivo: Precisión del estado

Cumplir o superar un Estado de precisión >= 99.5% ayuda a garantizar que los usuarios vean resultados correctos cuando consultan los estados del dispositivo o usan funciones de IA como Ask 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 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 con un resultado de intent conocido. Para obtener precisión técnica, la exactitud se evalúa en dos rutas de acceso distintas:

• Precisión basada en QUERY: Se verifica cuando un usuario o sistema interroga de forma activa el estado actual de un dispositivo.
• Precisión basada en EXECUTE: 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 en el ruido de señal baja, 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 móvil 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 muestra suficiente en ambas rutas de acceso, la precisión de referencia por hora para un estado específico se calcula como el promedio de los dos porcentajes independientes:

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

Cada ruta de acceso se define de la siguiente manera:

• Precisión de la consulta % = (Muestras precisas de la consulta por hora) / (Muestras totales de la consulta por hora)
• Precisión de la ejecución % = (Muestras precisas de la ejecución por hora) / (Muestras totales de la ejecución por hora)

Puntuación de precisión del rasgo (calculada por rasgo) = SUM(Muestras precisas de la consulta + Muestras precisas de la ejecución) / SUM(Muestras totales de la consulta + Muestras totales de la ejecución)

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

Esta vista evita que los dispositivos de alto volumen con una precisión excelente enmascaren los problemas de precisión en los dispositivos de menor volumen. Los socios preocupados por que los rasgos subutilizados disminuyan su puntuación pueden estar seguros de que un rasgo que se usa con poca frecuencia se protege automáticamente con la verificación del volumen de tráfico mínimo y no se incluirá en la puntuación de tipo y rasgo más bajos, a menos que cumpla con el umbral de muestra requerido.

3. Cómo mejorar el estado del dispositivo y la precisión del estado

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

Errores de "Missing Field"

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 QUERY y tu solicitud Report State para el mismo dispositivo.

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

Errores de "Inaccurate"

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: Para el error DETAILED_ACCURACY_RESULT_INACCURATE, hay una discrepancia entre el valor que se muestra en la respuesta QUERY y el último valor de Report State.

Solución: Asegúrate de que Report State se active cada vez que cambie el estado de un dispositivo y 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ó el estado actualizado del dispositivo a Google.

Solución: Envía siempre una actualización de Report State después de la ejecución del comando para que Home Graph 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: Para el error DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, no se recibió ningún Report State 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 las actualizaciones de estado no se activan, no llegan a HomeGraph o el dispositivo no informa correctamente las transiciones en su conectividad o estado operativo.

Solución: Asegúrate de que Report State se active y se envíe correctamente 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 constantemente su estado para mantener la precisión de la interfaz de usuario y el motor de automatización.