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. 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 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 Overview, luego Dashboards y, por último, en la lista My Dashboards, selecciona Google Home Vitals Dashboard (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 incorrectamente un comando que 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 BÚSQUEDA (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.
• Período 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 dispositivo en la 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 "acuse de recibo 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 objeto 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 porcentaje de precisión del estado >= 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 Report State.

El panel de calidad realiza un seguimiento de esto cada hora con dos métricas distintas: Precisión general y la Combinación de tipo y rasgo más baja.

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 un resultado de intención conocido.

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

El panel calcula la precisión en función de un intervalo de 1 hora. Si una hora tiene menos de 100 muestras totales (S_Total < 100), la exactitud para esa hora se establece en N/A.

Vista 1: Precisión general (promedio global)

Esto representa la precisión total de tu integración en todos los tipos de dispositivos y rasgos combinados. Proporciona un promedio ponderado del estado de todo tu ecosistema.

• Cálculo: Precisión total del estado en todos los dispositivos / Total del estado total en todos los dispositivos

Vista 2: Combinación de tipo y rasgo más baja

Identifica la categoría específica menos confiable de tu integración. Evita que los dispositivos de gran volumen y alta calidad oculten los dispositivos de bajo volumen y baja calidad. Por ejemplo, si tienes un gran volumen de luces con una exactitud del estado superior al 99.5%, pero un volumen bajo de interruptores con una exactitud del estado baja, esto destaca la mejora necesaria en los interruptores que se pueden perder en un valor promedio.

• Cálculo: Es el mínimo de la exactitud del estado o el total del estado para todas las combinaciones de rasgos y dispositivos.

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 exactos y actualizados, así como 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.