Google Home Vitals (Cloud)

Cette suite de tableaux de bord et d'alertes vous aide à maintenir de manière proactive une intégration de haute qualité avec l'écosystème Google Home. Google s'engage à aider ses partenaires à développer un écosystème de haute qualité pour tous les clients.

Le tableau de bord comporte trois sections, chacune couvrant un élément clé qui contribue à la qualité d'une intégration globale.

1. Métriques Google vers le partenaire : mesure l'état des appels de Google vers votre backend cloud.

2. État du système – Métriques du partenaire vers Google : mesure l'état des appels de votre système vers Google.

3. État de l'appareil – Précision de l'état : mesure la précision des états stockés dans les systèmes Google, qui sont utilisés pour répondre aux requêtes des utilisateurs.

Lorsque les métriques n'atteignent pas leurs valeurs cibles, elles sont mises en surbrillance en rouge pour indiquer un problème susceptible d'avoir un impact sur l'expérience utilisateur. Les informations suivantes fournissent des détails sur chaque cible et expliquent pourquoi elle est importante pour vos utilisateurs.

Si le bouton suivant ne vous redirige pas directement vers le tableau de bord, vous pouvez y accéder en sélectionnant la page Vue d'ensemble, puis Tableaux de bord, puis Tableau de bord Google Home Vitals (Cloud) dans la liste Mes tableaux de bord.

Accéder à Google Dashboard

Métriques Google vers le partenaire

La métrique Taux de réussite des requêtes/exécutions >= 99,5% mesure la fréquence à laquelle les commandes des utilisateurs sont correctement exécutées, ce qui permet d'éviter les réponses de l'Assistant telles que "Je ne parviens pas à joindre l'appareil" ou la confirmation incorrecte d'une commande qui n'a pas encore été exécutée.

La métrique Taux de réussite de la synchronisation >= 99,5% mesure la fréquence à laquelle les requêtes de synchronisation sont correctement traitées, ce qui garantit que les appareils affichés dans Google Home sont synchronisés avec les appareils connectés à votre infrastructure cloud.

Qu'est-ce qui définit une "réussite" ?

Une transaction est marquée comme réussie si la plate-forme Google Home reçoit une réponse valide indiquant que l'action prévue a été effectuée ou que l'état demandé a été récupéré.

Les réponses qui incluent des exceptions non bloquantes (par exemple, un état SUCCESS accompagné d'une exception lowBattery) sont comptabilisées comme des transactions réussies. La commande a atteint l'appareil et l'intent a été exécuté malgré l'avertissement.

Qu'est-ce qui définit un "échec" ?

Les erreurs trouvées sur la page Codes d'erreur courants de la plate-forme qui sont marquées comme Actionnable par le partenaire sont considérées comme des "échecs" lors du calcul des taux de réussite des intents QUERY, EXECUTE et SYNC. De plus, les erreurs détectées sur la page Erreurs et exceptions sont également des "échecs", à l'exception des suivantes :

Parité de l'état de la réponse d'exécution

Lorsque vous renvoyez un état SUCCESS dans une réponse EXECUTE, l'objet states de la charge utile de votre réponse doit contenir tous les champs d'état actifs et mis à jour définis par les traits que vous exécutez. Si vous omettez des champs d'état obligatoires ou si vous renvoyez un objet states vide pour les caractéristiques complexes, la plate-forme Google Home ne pourra pas analyser le résultat de l'exécution et l'enregistrera comme un échec AGENT_ISSUE ou INVALID_RESPONSE, ce qui réduira votre taux de réussite des requêtes et des exécutions.

La métrique Latence de requête/exécution (p90) <= 1 000 ms mesure le temps d'attente de l'action demandée et permet de s'assurer que les utilisateurs n'ont pas à attendre trop longtemps, par exemple quelques secondes pour que leur lumière s'éteigne.

Statistiques relatives à la latence

La latence est un indicateur essentiel de la réactivité de votre intégration pour l'utilisateur final. Le tableau de bord suit la latence du 90e centile (P90), qui représente l'expérience de vos utilisateurs les plus "lents" (par exemple, un P90 de 800 ms signifie que 90% des requêtes sont confirmées en 800 ms ou moins).

Google mesure la latence différemment pour les vérifications d'état et les commandes d'appareil afin de garantir la précision technique.

1. Latence de REQUÊTE (interrogative)

Cela mesure le délai aller-retour Cloud-to-cloud lorsque Google demande l'état actuel d'un appareil.

• Début : Google envoie une requête action.devices.QUERY à votre URL de fulfillment.
• Fenêtre de mesure : temps nécessaire à votre cloud pour recevoir, traiter et transmettre la réponse HTTP complète à Google.
• Fin : Google reçoit et accuse réception de la charge utile de réponse finale de votre service.

2. Latence EXECUTE (Action)

Cette métrique mesure le temps d'accusé de réception de la commande lorsque Google envoie une requête de contrôle à un appareil.

• Début : Google envoie une requête action.devices.EXECUTE à votre URL de fulfillment.
• Fenêtre de mesure : temps nécessaire pour que votre cloud reçoive la commande et renvoie une réponse d'accusé de réception.
• Fin : Google reçoit la réponse d'état SUCCESS, PENDING ou OFFLINE.
• Champ d'application technique : cette métrique mesure le temps de "réponse d'accusé de réception" entre le cloud de Google et votre cloud. Elle ne mesure pas le temps nécessaire au matériel physique (par exemple, une ampoule) pour effectuer le changement d'état physique, car cela implique souvent une latence du réseau maillé local en dehors du chemin cloud-to-cloud.

Répartition de la chronologie de la latence EXECUTE/QUERY

Lors de l'analyse des codes temporels pour une latence EXECUTE ou QUERY, le délai aller-retour total peut être décomposé en flux séquentiel suivant :

Étant donné que cette répartition compare les codes temporels côté Google et côté partenaire, les serveurs partenaires doivent être synchronisés avec le protocole NTP (Network Time Protocol). Même une dérive d'horloge mineure (50 à 100 ms) fausse les délais d'acheminement calculés (t2 - t1 et t4 - t3), ce qui peut entraîner des métriques logiquement impossibles, telles que des latences de transit négatives.

[t1] Requête envoyée (Google sortant) : Google lance la requête d'intent. Étant donné que t1 n'est pas directement exposé, il est calculé approximativement en soustrayant la latence totale du code temporel entrant final.

Transit réseau (t1 à t2) : estimation du temps de transit réseau et de mise en file d'attente avant d'atteindre votre point de terminaison de fulfillment.

[t2] Requête reçue (entrée partenaire) : code temporel exact de l'arrivée de la requête sur l'API Gateway ou le serveur d'entrée de votre environnement.

Traitement par le partenaire (t2 à t3) : latence d'exécution interne, de routage et de gestion des appareils entièrement dans votre environnement cloud.

[t3] Réponse envoyée (sortie du partenaire) : code temporel indiquant quand votre service renvoie la réponse de fulfillment à Google.

Transit de retour (t3 à t4) : temps de routage et de connexion du réseau de retour vers Google.

[t4] Requête finalisée (Google entrant) : Google reçoit et traite la réponse finale. Ce code temporel est explicitement enregistré dans vos journaux Google Cloud en tant que receiveTimestamp.

Pour illustrer la façon dont ces métriques sont liées, prenons l'exemple d'une requête EXECUTE avec une latence totale consignée (latencyMsec) de 1 700 ms et un Google Cloud receiveTimestamp (t4) de 2026-05-25T15:25:00.550Z.

Options de réduction de la latence

Recommandations architecturales pour le routage géographique

Si l'implémentation d'Anycast IP n'est pas possible, nous vous recommandons les alternatives économiques suivantes pour vous assurer que les utilisateurs sont desservis par le centre de données régional le plus proche.

1. Équilibrage de charge global (GLB)

   Au lieu du routage statique, utilisez un équilibreur de charge d'application global (disponible auprès de la plupart des principaux fournisseurs de services cloud).

   • Fonctionnement : vous configurez un point d'entrée global unique (URL) situé à la périphérie du réseau. L'équilibreur de charge détecte automatiquement l'origine géographique de la requête à partir des clusters de traitement de Google et achemine le trafic vers le backend régional opérationnel le plus proche.

   • Avantage : Cette approche offre les performances d'Anycast avec une complexité de configuration et un coût nettement inférieurs.

2. DNS géolocalisé (GeoDNS)

   • Fonctionnement : configurez votre fournisseur DNS pour qu'il résolve votre URL de fulfillment en différentes adresses IP en fonction de l'emplacement géographique de la requête DNS.

   • Implémentation : assurez-vous que votre fournisseur DNS est optimisé pour les points de sortie de Google. Lorsque les services de traitement régionaux de Google (par exemple, aux États-Unis, dans l'UE ou en Asie) résolvent votre domaine, ils reçoivent l'adresse IP du centre de données de cette région spécifique.

Stratégies d'optimisation au niveau de la couche d'application

Au-delà du routage au niveau de l'infrastructure, vous pouvez mettre en œuvre les stratégies suivantes au niveau de la couche d'application pour réduire la latence lors du traitement des requêtes.

1. La méthode de proxy "Trampoline"

   Si vous devez conserver un centre de données principal, utilisez des serveurs proxy légers régionaux (Trampolines) pour gérer le handshake initial.

   1. Google accède à votre URL globale.

   2. Un proxy régional (par exemple, une fonction Nginx ou Lambda légère) reçoit la requête.

   3. Le proxy transfère la charge utile vers la base de données principale via votre réseau backbone interne à haut débit.

   Avantage : cela réduit le temps de "handshake TCP", qui est souvent le principal facteur de latence pour les requêtes longue distance.

2. Conseils sur la région du jeton d'accès

   Lors du processus d'association de compte (OAuth), votre système peut identifier la région d'origine de l'utilisateur.

   Implémentation : encodez un identifiant de région dans le access_token émis pour Google. Lorsque Google envoie une requête de traitement, votre passerelle peut immédiatement inspecter le jeton et acheminer la requête vers le cluster régional approprié sans avoir à effectuer de recherche dans la base de données.

État du système : métriques du partenaire vers Google

Maintenir un taux de réussite supérieur ou égal à 99, 5% permet de s'assurer que l'état des appareils est correct dans Google Home, que les appareils sont ajoutés et supprimés, que les automatisations se déclenchent et que les événements de l'historique s'affichent dans l'onglet "Activité" de Google Home app (GHA).

Le taux de réussite est calculé en fonction des codes de réponse HTTP renvoyés par Google lorsque votre cloud transmet des mises à jour d'état. Pour s'assurer que les partenaires ne sont pas pénalisés par des problèmes d'infrastructure côté Google, la métrique exclut les erreurs internes de Google du nombre d'échecs. Les appels d'API inclus dans le calcul sont disponibles dans la documentation de référence de l'API HomeGraph.

Qu'est-ce qui définit une "réussite" ?

2xx (Réussite) : la mise à jour de l'état a bien été reçue et traitée par Home Graph.

Qu'est-ce qui définit un "échec" ?

Les erreurs 4xx (erreur du partenaire) représentent des échecs et indiquent un problème avec la requête envoyée depuis votre cloud. Voici quelques codes courants :

400 Requête erronée

Cause : Le serveur n'a pas pu traiter la requête en raison d'une syntaxe non valide. Les causes les plus courantes sont un fichier JSON incorrect ou l'utilisation de "null" au lieu de "" pour une valeur de chaîne.

Solution : Assurez-vous que le corps de la requête est un fichier JSON valide (pas de structure incorrecte ni de valeurs nulles pour les champs de chaîne) et vérifiez que agentUserId correspond à la valeur de la réponse SYNC.

404 Not Found

Cause : deviceId ou agentUserId est introuvable dans HomeGraph (pas encore synchronisé, déjà dissocié ou ID non concordant).

Solution :

1. Assurez-vous que l'élément agentUserId correspond à la valeur fournie dans votre réponse SYNC.
2. Utilisez l'API Home Graph SYNC pour déterminer si l'erreur "404 Not Found" est due à un appareil ou un utilisateur manquant dans HomeGraph.
3. Veillez à déclencher requestSync après l'ajout, la suppression, le changement de nom ou la mise à jour d'un appareil ou d'un compte pour vous assurer que l'état reste à jour.
4. Gérez correctement les intents DISCONNECT pour arrêter de signaler les appareils obsolètes. Après avoir reçu l'intent DISCONNECT, votre service cloud doit cesser de publier les modifications sur Google avec Request Sync et Report State.

429 Ressource épuisée

Cause : Votre intégration a dépassé le quota qui lui est alloué.

Solution : consultez les instructions de la section "Étape 2a : Déboguer les problèmes de quota" du tableau de bord de gestion des quotas. Pour en savoir plus, vous pouvez également consulter Quotas et limites de la maison connectée.

État de l'appareil – Précision de l'état

Atteindre ou dépasser une précision de l'état >= 99,5% permet de s'assurer que les utilisateurs voient des résultats corrects lorsqu'ils consultent l'état des appareils ou utilisent des fonctionnalités d'IA comme Demander à Home. Si la précision de l'état est faible, il est possible que les automatisations ne se déclenchent pas et que les entrées d'historique n'apparaissent pas dans l'onglet "Activité" de GHA au bon moment. Pour en savoir plus, consultez ReportState. Remarque : L'objectif de précision de l'état doit être atteint pour TOUS les traits acceptés.

1. Composants de la précision

La métrique est dérivée d'"échantillons" pour lesquels Google peut vérifier l'état signalé par rapport à un résultat d'intention connu. Pour une précision technique, la justesse est évaluée selon deux voies distinctes :

• Précision basée sur les REQUÊTES : vérifiée lorsqu'un utilisateur ou un système interroge activement l'état actuel d'un appareil.
• Précision basée sur EXECUTE : vérifiée en évaluant l'état de l'appareil après la commande, signalé à la suite d'une requête de contrôle.

2. Métriques du tableau de bord (calcul horaire)

Le tableau de bord calcule la précision sur un intervalle d'une heure. Pour garantir la confiance statistique et éviter de pénaliser les intégrations en cas de bruit de signal faible, Google applique un seuil de volume de trafic minimal. Si une combinaison spécifique de caractéristique et d'appareil accumule moins de 100 échantillons au total sur une période glissante de cinq jours, sa précision est considérée comme statistiquement non significative et est définie sur N/A.

Lorsqu'une heure présente un volume d'échantillons suffisant pour les deux parcours, la précision horaire de référence pour un état spécifique est calculée comme la moyenne des deux pourcentages indépendants :

Précision de l'état horaire = (Précision de la requête % + Précision de l'exécution %) / 2

Où chaque parcours est défini comme suit :

• %de précision des requêtes = (Échantillons de requêtes horaires précis) / (Nombre total d'échantillons de requêtes horaires)
• %de précision de l'exécution = (Échantillons d'exécution précis par heure) / (Nombre total d'échantillons d'exécution par heure)

Score de précision du trait (calculé par trait) = SOMME(Échantillons précis de requête + Échantillons précis d'exécution) / SOMME(Échantillons totaux de requête + Échantillons totaux d'exécution)

Étant donné que le score de qualité évalue les performances strictement minimales de votre écosystème, chaque trait compatible et éligible doit individuellement atteindre l'objectif de précision de l'état >= 99,5% (il ne s'agit pas d'une moyenne de tous les traits).

Cette vue empêche les appareils à volume élevé offrant une excellente précision de masquer les problèmes de précision sur les appareils à volume plus faible. Les partenaires qui craignent que des caractéristiques sous-utilisées ne fassent baisser leur score peuvent être rassurés : une caractéristique rarement utilisée est automatiquement protégée par la vérification du volume de trafic minimal et ne sera pas prise en compte dans le score de type et de caractéristique le plus bas, sauf si elle atteint le seuil d'échantillon requis.

3. Améliorer la précision de l'état de l'appareil

Des écarts se produisent lorsque l'état stocké dans Home Graph ne correspond pas aux résultats d'une requête QUERY en temps réel.

Erreurs "Champ manquant"

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"
  }
  

Cause : Avec l'erreur DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD ou DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, l'ensemble des champs de charge utile diffère entre votre réponse QUERY et votre requête ReportState pour le même appareil.

Solution : assurez-vous que la structure des données est identique dans les deux chemins d'accès. Si un trait est inclus dans SYNC, ses champs correspondants doivent être présents et cohérents à la fois dans les rapports proactifs et les requêtes réactives.

Erreurs "Inexact"

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"
  }
  

Cause : Pour l'erreur DETAILED_ACCURACY_RESULT_INACCURATE, il existe un écart entre la valeur renvoyée dans la réponse QUERY et la dernière valeur ReportState.

Solution : Assurez-vous que Report State est déclenché chaque fois que l'état d'un appareil change, et que Report State et QUERY fournissent toujours exactement les mêmes valeurs à jour et tous les champs obligatoires pour maintenir la cohérence des données.

"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"
   }
  

Cause : avec l'erreur DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, le partenaire a exécuté la commande, mais n'a pas signalé l'état mis à jour de l'appareil à Google.

Solution : Envoyez toujours une mise à jour ReportState après l'exécution de la commande afin que Home Graph reçoive le nouvel état de l'appareil.

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"
   }
  

Cause : Pour l'erreur DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, aucun état de rapport n'a été reçu pour cet appareil (l'état est vide et le code temporel indiqué est à l'epoch), bien que les résultats de la REQUÊTE fournissent l'état actuel. Cela indique que les mises à jour d'état ne sont pas déclenchées, qu'elles ne parviennent pas à HomeGraph ou que l'appareil ne signale pas correctement les transitions de son état de connectivité ou de fonctionnement.

Solution : assurez-vous que Report State est déclenché et envoyé pour tous les changements d'état. Vérifiez que la logique de backend gère correctement les mises à jour d'état, confirme la réussite de la diffusion vers Google HomeGraph et s'assure que l'appareil synchronise systématiquement son état pour que l'interface utilisateur et le moteur d'automatisation restent précis.