Google Home Vitals (Cloud)

Este paquete 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 de socio a Google: 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 consultas 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, por último, Panel de Google Home Vitals (Cloud) en la lista Mis paneles para verlo.

Ir al panel

Métricas de Google al socio

La métrica Tasa de éxito de consultas/ejecuciones >= 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 comunicarme con el dispositivo" o confirmar de forma incorrecta un comando que aún no se cumplió.

La métrica Tasa de éxito de sincronización >= 99.5% mide la frecuencia con la que las solicitudes de sincronización se completan correctamente, lo que garantiza que los dispositivos que se muestran en Google Home estén sincronizados con los dispositivos conectados a tu infraestructura de nube.

¿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 se recuperó el estado solicitado.

Las respuestas que incluyen excepciones no bloqueantes (por ejemplo, un estado SUCCESS acompañado de una excepción lowBattery) se cuentan como transacciones exitosas. El comando llegó al dispositivo y se cumplió el intent a pesar de la advertencia.

¿Qué define un "error"?

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

Paridad del estado de respuesta de ejecución

Cuando devuelvas un estado SUCCESS en una respuesta EXECUTE, el objeto states de la carga útil de la respuesta debe contener todos los campos de estado activos y actualizados que definen los atributos que estás ejecutando. Si omites los campos de estado obligatorios o devuelves un objeto states vacío para los rasgos complejos, la plataforma de Google Home no podrá analizar el resultado de la ejecución y lo registrará como una falla de AGENT_ISSUE o INVALID_RESPONSE, lo que reducirá tu tasa de éxito de consultas y ejecuciones.

La métrica Latencia de consulta/ejecución (p90) <= 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, esperar 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. En el panel, se hace un seguimiento de 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 de dispositivos para garantizar la precisión técnica.

1. Latencia de 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 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 confirma la carga útil de la respuesta final de tu servicio.

2. Latencia de EXECUTE (acción)

Esto 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 tu URL de entrega.
• Ventana de medición: Es el tiempo que tarda tu nube en recibir el comando y devolver una respuesta de confirmación.
• Fin: 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, esto implica una latencia de red en malla local fuera de la ruta de nube a nube.

Desglose del cronograma de latencia de EXECUTE/QUERY

Cuando se analizan las marcas de tiempo de una latencia de EXECUTE o QUERY, el tiempo total de ida y vuelta se puede desglosar en el siguiente flujo secuencial:

Dado que este desglose compara las marcas de tiempo del lado de Google y del lado del socio, los servidores de los socios deben sincronizarse con el NTP (protocolo NTP). Incluso una desviación de reloj menor (de 50 a 100 ms) distorsionará los tiempos en tránsito calculados (t2 - t1 y t4 - t3), lo que podría generar métricas lógicamente imposibles, como latencias de tránsito negativas.

[t1] Solicitud enviada (saliente de Google): Google inicia la solicitud de intent. Debido a que t1 no se expone directamente, se calcula de forma aproximada restando la latencia total de la marca de tiempo de entrada final.

Tránsito de red (t1 a t2): Es el tiempo estimado de tránsito de red y de espera antes de llegar al extremo de entrega.

[t2] Solicitud recibida (entrada del socio): Es la marca de tiempo exacta en la que la solicitud llega a la API Gateway o al servidor de entrada de tu entorno.

Procesamiento del socio (de t2 a t3): Es la latencia de ejecución interna, enrutamiento y manejo de dispositivos que se produce por completo dentro de tu entorno de nube.

[t3] Respuesta enviada (salida del socio): Es la marca de tiempo en la que tu servicio envía la respuesta de entrega a Google.

Tránsito de retorno (de t3 a t4): Es el tiempo de enrutamiento de la red de retorno y de finalización de la conexión de vuelta a Google.

[t4] Solicitud finalizada (entrada de Google): Google recibe y procesa la respuesta final. Esta marca de tiempo se registra de forma explícita en tus registros de Google Cloud como receiveTimestamp.

Para ilustrar cómo se relacionan estas métricas, considera una solicitud de EXECUTE de ejemplo con una latencia registrada total (latencyMsec) de 1,700 ms y un Google Cloud receiveTimestamp (t4) de 2026-05-25T15:25:00.550Z.

Opciones de reducción de latencia

Recomendaciones de arquitectura para el enrutamiento geográfico

Si no es posible implementar la IP de Anycast, te recomendamos las siguientes alternativas rentables para garantizar que los usuarios reciban el 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 al 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 menores.

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 de esa región específica.

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

Más allá 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 ligeros regionales (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 "establecimiento de conexión TCP", que suele ser el factor que más contribuye a la latencia en las solicitudes de larga distancia.

2. Sugerencias de región para el 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 para Google. Cuando Google envía una solicitud de entrega, tu puerta de enlace puede inspeccionar de inmediato el token y enrutar la solicitud al clúster regional correcto sin necesidad de realizar una búsqueda en la base de datos.

Estado del sistema: Métricas de socio a Google

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

La tasa de éxito se calcula en función de los códigos de respuesta HTTP que devuelve 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 (Éxito): Home Graph recibió y procesó correctamente la actualización de estado.

¿Qué define un "error"?

Los errores 4xx (error del socio) representan fallas y, además, 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 un JSON con formato incorrecto o el uso de un valor nulo 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 de SYNC.

404 No encontrado

Causa: No se encontró deviceId ni 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 de SYNC.
2. Usa la API de SYNC de Home Graph para determinar si el error 404 No encontrado se debe a que falta un dispositivo o un usuario en Home Graph.
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 inactivos. Después de recibir el intent DISCONNECT, tu servicio en la nube debería dejar de publicar cambios en Google con Sincronización de solicitudes y Estado del informe.

429 Recurso agotado

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

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

Estado del dispositivo: Precisión del estado

Cumplir o superar una precisión de estado de >= 99.5% ayuda a garantizar que los usuarios vean resultados correctos cuando consulten los estados de los dispositivos o usen funciones potenciadas por IA, como Preguntarle 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 Estado del informe. Nota: El objetivo de precisión de estado se debe cumplir en TODOS los atributos admitidos.

1. Componentes de exactitud

La métrica se deriva de "muestras" en las que Google puede verificar el estado informado en función de un resultado de intención conocido. Para lograr precisión técnica, la exactitud se evalúa a través de dos vías distintas:

• Precisión basada en CONSULTAS: 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 con ruido de señal baja, Google aplica un umbral mínimo de volumen de tráfico. Si una combinación específica de atributo y dispositivo acumula menos de 100 muestras en total durante un período continuo de 5 días, su precisión se considera estadísticamente insignificante y se establece como N/A.

Cuando una hora tiene un volumen de muestra suficiente en ambas rutas, 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 = (% de precisión de la consulta + % de precisión de la ejecución) / 2

Donde cada ruta se define de la siguiente manera:

• %de precisión de las consultas = (Muestras precisas de consultas por hora) / (Muestras totales de consultas por hora)
• %de precisión de la ejecución = (Muestras precisas de ejecución por hora) / (Muestras totales de ejecución por hora)

Puntuación de precisión de rasgos (calculada por rasgo) = SUM(Muestras precisas de consultas + Muestras precisas de ejecución) / SUM(Muestras totales de consultas + Muestras totales de ejecución)

Debido a que el nivel de calidad evalúa el rendimiento mínimo estricto en todo tu ecosistema, cada atributo compatible y apto debe cumplir de forma individual con el objetivo de precisión de estado de >= 99.5% (este no es un promedio de los atributos).

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 a los que les preocupa que los atributos poco utilizados disminuyan su puntuación pueden tener la certeza de que un atributo que se usa con poca frecuencia se protege automáticamente con la verificación de volumen de tráfico mínimo y no se tendrá en cuenta en la puntuación de tipo y atributo más bajos, a menos que cumpla con el umbral de muestra requerido.

3. Mejora 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 "Falta un 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 de acceso. Si se incluye un atributo en SYNC, sus campos correspondientes deben estar presentes y ser coherentes tanto en los informes proactivos como en las consultas reactivas.

Errores de "Inexactitud"

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, hay 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 exactamente 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: En el caso del error DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, no se recibió ningún estado del informe 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 se active Report State 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 que la entrega se haya realizado correctamente en Google Home Graph 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.