Google Home Vitals (Cloud)

Mit dieser Suite aus Dashboards und Benachrichtigungen können Sie proaktiv eine hochwertige Integration in das Google Home-Ökosystem aufrechterhalten. Google möchte Partner dabei unterstützen, ein hochwertiges Ökosystem für alle Kunden zu entwickeln.

Das Dashboard besteht aus drei Abschnitten, die jeweils einen wichtigen Teil abdecken, der zur Qualität einer Gesamtintegration beiträgt.

1. Messwerte von Google an Partner : Misst den Status von Aufrufen von Google an Ihr Cloud-Backend.

2. Systemstatus – Messwerte von Partner an Google : Misst den Status von Aufrufen von Ihrem System an Google.

3. Gerätezustand – Statusgenauigkeit : Misst die Genauigkeit von Zuständen, die in Google-Systemen gespeichert sind und zur Beantwortung von Nutzeranfragen verwendet werden.

Wenn Messwerte ihre Zielwerte nicht erreichen, werden sie rot hervorgehoben, um auf ein Problem hinzuweisen, das sich auf die Nutzerfreundlichkeit auswirken könnte. Im Folgenden finden Sie Details zu den einzelnen Zielen und warum sie für Ihre Nutzer wichtig sind.

Wenn Sie über die folgende Schaltfläche nicht direkt zum Dashboard gelangen, können Sie es aufrufen, indem Sie die Seite Übersicht und dann Dashboards auswählen. Wählen Sie in der Liste Meine Dashboards die Option Google Home Vitals Dashboard (Cloud) aus, um Ihr Dashboard aufzurufen.

Zum Dashboard

Messwerte von Google an Partner

Mit dem Messwert Erfolgsrate für Abfragen/Ausführungen >= 99,5% wird gemessen, wie oft Nutzerbefehle korrekt ausgeführt werden.So können Assistant-Antworten wie „Ich kann das Gerät nicht erreichen“ oder die falsche Bestätigung eines Befehls vermieden werden, der noch nicht ausgeführt wurde.

Was ist ein „Erfolg“?

Eine Transaktion wird als Erfolg gewertet, wenn die Google Home-Plattform eine gültige Antwort erhält, die angibt, dass die beabsichtigte Aktion ausgeführt oder der angeforderte Status abgerufen wurde.

Antworten, die nicht blockierende Ausnahmen enthalten (z. B. der Status SUCCESS zusammen mit der Ausnahme lowBattery), werden als erfolgreiche Transaktionen gezählt. Der Befehl wurde an das Gerät gesendet und der Intent wurde trotz der Warnung erfüllt.

Was ist ein „Fehler“?

Die Fehler, die unter Häufige Plattformfehlercodes aufgeführt und als Partner Actionable gekennzeichnet sind, werden bei der Berechnung der Erfolgsraten für QUERY und EXECUTE als „Fehler“ gewertet. Außerdem sind die Fehler unter Fehler und Ausnahmen ebenfalls „Fehler“, mit den folgenden Ausnahmen:

Mit dem Messwert Latenz für Abfragen/Ausführungen (90. Perzentil) <= 1.000 ms wird die Wartezeit für angeforderte Aktionen gemessen. So wird sichergestellt, dass Nutzer nicht zu lange warten müssen, z. B. einige Sekunden, bis das Licht ausgeschaltet wird.

Latenzmesswerte

Die Latenz ist ein wichtiger Indikator dafür, wie schnell Ihre Integration für den Endnutzer reagiert. Im Dashboard wird die Latenz des 90. Perzentils (P90) erfasst. Sie gibt die Erfahrung Ihrer „langsamsten“ Nutzer wieder. Ein P90 von 800 ms bedeutet beispielsweise, dass 90% der Anfragen in 800 ms oder weniger bestätigt werden.

Google misst die Latenz für Statusprüfungen und Gerätebefehle unterschiedlich, um die technische Genauigkeit zu gewährleisten.

1. Abfragelatenz (Frage)

Hier wird die Cloud-to-cloud Round-Trip-Zeit gemessen, wenn Google den aktuellen Status eines Geräts anfordert.

• Start: Google sendet eine action.devices.QUERY-Anfrage an Ihre Auftragsausführungs-URL.
• Messzeitraum: Die Zeit, die Ihre Cloud benötigt, um die vollständige HTTP-Antwort zu empfangen, zu verarbeiten und an Google zurückzusenden.
• Ende: Google empfängt und bestätigt die endgültige Antwortnutzlast von Ihrem Dienst.

2. Ausführungslatenz (Aktion)

Hier wird die Zeit für die Befehlsbestätigung gemessen, wenn Google eine Steueranfrage an ein Gerät sendet.

• Start: Google sendet eine action.devices.EXECUTE-Anfrage an Ihre Auftragsausführungs-URL.
• Messzeitraum: Die Zeit, die Ihre Cloud benötigt, um den Befehl zu empfangen und eine Bestätigungsantwort zurückzugeben.
• Ende: Google empfängt die Statusantwort SUCCESS, PENDING oder OFFLINE.
• Technischer Umfang: Mit diesem Messwert wird die Zeit für die Bestätigung der Antwort zwischen der Cloud von Google und Ihrer Cloud gemessen. Die Zeit, die die physische Hardware (z. B. eine Glühbirne) benötigt, um den physischen Status zu ändern, wird nicht gemessen, da dies oft die Latenz des lokalen Mesh-Netzwerks außerhalb des Cloud-to-Cloud-Pfads umfasst.

Optionen zur Reduzierung der Latenz

Architektonische Empfehlungen für das geografische Routing

Wenn die Anycast-IP-Implementierung nicht möglich ist, empfehlen wir die folgenden kostengünstigen Alternativen, um sicherzustellen, dass Nutzer vom nächstgelegenen regionalen Rechenzentrum bedient werden.

1. Globales Load-Balancing (GLB)

   Verwenden Sie anstelle des statischen Routings einen globalen Application Load Balancer (verfügbar bei den meisten großen Cloud-Anbietern).

   • Funktionsweise:Sie konfigurieren einen einzelnen globalen Einstiegspunkt (URL), der sich am Netzwerkrand befindet. Der Load-Balancer erkennt automatisch den geografischen Ursprung der Anfrage von den Auftragsausführungsclustern von Google und leitet den Traffic an Ihr nächstgelegenes regionales fehlerfreies Backend weiter.

   • Vorteil:Dies bietet die Leistung von Anycast mit deutlich geringerer Konfigurationskomplexität und niedrigeren Kosten.

2. Standortbezogenes DNS (GeoDNS)

   • Funktionsweise:Konfigurieren Sie Ihren DNS-Anbieter so, dass Ihre Auftragsausführungs-URL basierend auf dem geografischen Standort der DNS-Abfrage in verschiedene IP-Adressen aufgelöst wird.

   • Implementierung:Achten Sie darauf, dass Ihr DNS-Anbieter für die Ausgangspunkte von Google optimiert ist. Wenn die regionalen Auftragsausführungsdienste von Google (z. B. in den USA, der EU oder Asien) Ihre Domain auflösen, erhalten sie die IP-Adresse für das Rechenzentrum in dieser bestimmten Region.

Optimierungsstrategien auf der Anwendungsebene

Neben dem Routing auf Infrastrukturebene können Sie die folgenden Strategien auf der Anwendungsebene implementieren, um die Latenz bei der Anfrageverarbeitung zu reduzieren.

1. Die „Trampoline“-Proxy-Methode

   Wenn Sie ein primäres Rechenzentrum beibehalten müssen, verwenden Sie regionale Lightweight-Proxyserver (Trampoline), um den ersten Handshake zu verarbeiten.

   1. Google ruft Ihre globale URL auf.

   2. Ein regionaler Proxy (z. B. eine Lightweight-Nginx- oder Lambda-Funktion) empfängt die Anfrage.

   3. Der Proxy leitet die Nutzlast über Ihr internes Hochgeschwindigkeits-Backbone an die primäre Datenbank weiter.

   Vorteil:Dadurch wird die Zeit für den TCP-Handshake reduziert, die oft den größten Beitrag zur Latenz bei Anfragen über große Entfernungen leistet.

2. Hinweise zur Region für Zugriffstoken

   Während der Kontoverknüpfung (OAuth) kann Ihr System die Heimatregion des Nutzers ermitteln.

   Implementierung:Codieren Sie eine Regions-ID in das access_token, das an Google ausgegeben wird. Wenn Google eine Auftragsausführungsanfrage sendet, kann Ihr Gateway das Token sofort prüfen und die Anfrage an den richtigen regionalen Cluster weiterleiten, ohne dass eine Datenbanksuche erforderlich ist.

Systemstatus – Messwerte von Partner an Google

Wenn Sie eine Erfolgsrate von mindestens 99,5% beibehalten, wird sichergestellt, dass die Gerätestatus in Google Home korrekt sind, Geräte hinzugefügt und entfernt werden, Automatisierungen ausgelöst werden und Verlaufsereignisse auf dem Tab „Aktivität“ der Google Home app (GHA)angezeigt werden.

Die Erfolgsrate wird anhand der HTTP-Antwortcodes berechnet, die von Google zurückgegeben werden, wenn Ihre Cloud Statusaktualisierungen sendet. Damit Partner nicht für Infrastrukturprobleme auf Google-Seite bestraft werden, werden Google-interne Fehler bei der Berechnung der Fehleranzahl ausgeschlossen. Die in der Berechnung enthaltenen API-Aufrufe finden Sie in der Home Graph API-Referenz.

Was ist ein „Erfolg“?

2xx (Erfolg): Die Statusaktualisierung wurde von Home Graph erfolgreich empfangen und verarbeitet.

Was ist ein „Fehler“?

4xx (Partnerfehler) stellen Fehler dar und weisen auf ein Problem mit der Anfrage hin, die von Ihrer Cloud gesendet wurde. Häufige Codes sind:

400 Fehlerhafte Anfrage

Ursache:Der Server konnte die Anfrage aufgrund einer ungültigen Syntax nicht verarbeiten. Häufige Ursachen sind fehlerhaftes JSON oder die Verwendung von „null“ anstelle von „“ für einen Stringwert.

Lösung: Achten Sie darauf, dass der Anfragetext gültiges JSON ist (keine fehlerhafte Struktur oder Nullwerte für Stringfelder) und dass agentUserId mit dem Wert aus der SYNC-Antwort übereinstimmt.

404 Nicht gefunden

Ursache:deviceId oder agentUserId wurde in Home Graph nicht gefunden (noch nicht synchronisiert, bereits entknüpft oder ID-Fehler).

Lösung :

1. Achten Sie darauf, dass agentUserId mit dem Wert in Ihrer SYNC-Antwort übereinstimmt.
2. Verwenden Sie die Home Graph SYNC API , um zu ermitteln, ob der Fehler „404 Nicht gefunden“ durch ein fehlendes Gerät oder einen fehlenden Nutzer in Home Graph verursacht wird.
3. Lösen Sie nach dem Hinzufügen, Entfernen, Umbenennen oder Aktualisieren eines Geräts oder Kontos requestSync aus, damit der Status auf dem neuesten Stand bleibt.
4. Verarbeiten Sie DISCONNECT Intents ordnungsgemäß, um die Berichterstellung für veraltete Geräte zu beenden. Nachdem Ihr Cloud-Dienst den DISCONNECT-Intent empfangen hat, sollte er keine Änderungen mehr mit Request Sync und Report State an Google senden.

429 Ressource erschöpft

Ursache:Ihre Integration hat das zugewiesene Kontingent überschritten.

Lösung:Eine Anleitung zur Kontingentverwaltung finden Sie im Dashboard im Abschnitt „Schritt 2a: Kontingentprobleme beheben“. Weitere Informationen finden Sie unter Kontingente und Limits für Smart Home.

Gerätezustand – Zustandsgenauigkeit

Wenn Sie eine Statusgenauigkeit von mindestens 99,5% erreichen oder übertreffen, werden Nutzern korrekte Ergebnisse angezeigt, wenn sie Gerätestatus aufrufen oder KI-Funktionen wie „Home fragen“ verwenden. Bei einer geringen Statusgenauigkeit werden Automatisierungen möglicherweise nicht ausgelöst und Verlaufseinträge werden nicht rechtzeitig auf dem Tab „Aktivität“ der GHA angezeigt. Weitere Informationen finden Sie unter Status melden. Hinweis:Das Ziel für die Statusgenauigkeit muss für ALLE unterstützten Merkmale erreicht werden.

1. Komponenten der Genauigkeit

Der Messwert wird aus „Beispielen“ abgeleitet, bei denen Google den gemeldeten Status mit einem bekannten Intent-Ergebnis vergleichen kann. Aus technischen Gründen wird die Genauigkeit auf zwei verschiedenen Wegen bewertet:

• Abfragebasierte Genauigkeit:Wird überprüft, wenn ein Nutzer oder ein System aktiv den aktuellen Status eines Geräts abfragt.
• Ausführungsbasierte Genauigkeit:Wird überprüft, indem der nach dem Befehl gemeldete Gerätezustand nach einer Steueranfrage bewertet wird.

2. Dashboardmesswerte (stündliche Berechnung)

Im Dashboard wird die Genauigkeit in einem Intervall von einer Stunde berechnet. Um die statistische Zuverlässigkeit zu gewährleisten und Integrationen bei geringem Signalrauschen nicht zu bestrafen, erzwingt Google einen Mindestschwellenwert für das Trafficvolumen. Wenn für eine bestimmte Kombination aus Merkmal und Gerät in einem rollierenden Zeitraum von fünf Tagen weniger als 100 Stichproben erfasst werden, wird die Genauigkeit als statistisch unbedeutend betrachtet und auf Nicht zutreffend gesetzt.

Wenn für eine Stunde ein ausreichendes Stichprobenvolumen für beide Pfade vorhanden ist, wird die stündliche Basisgenauigkeit für einen bestimmten Zustand als Durchschnitt der beiden unabhängigen Prozentsätze berechnet:

Stündliche Statusgenauigkeit = (Genauigkeit der Abfrage in % + Genauigkeit der Ausführung in %) / 2

Dabei wird jeder Weg wie folgt definiert:

• Genauigkeit der Abfrage in % = (Anzahl der genauen stündlichen Abfragestichproben) / (Anzahl der stündlichen Abfragestichproben insgesamt)
• Genauigkeit der Ausführung in % = (Anzahl der genauen stündlichen Ausführungsstichproben) / (Anzahl der stündlichen Ausführungsstichproben insgesamt)

Genauigkeitswert für Merkmale (pro Merkmal berechnet) = SUMME(Anzahl der genauen Abfragestichproben + Anzahl der genauen Ausführungsstichproben) / SUMME(Anzahl der Abfragestichproben insgesamt + Anzahl der Ausführungsstichproben insgesamt)

Da mit dem Qualitätswert die absolut minimale Leistung in Ihrem Ökosystem bewertet wird, muss jedes unterstützte und infrage kommende Merkmal einzeln das Ziel für die Statusgenauigkeit von mindestens 99,5% erreichen (dies ist kein Durchschnitt über alle Merkmale hinweg).

So wird verhindert, dass Geräte mit hohem Volumen und ausgezeichneter Genauigkeit Genauigkeitsprobleme bei Geräten mit geringerem Volumen verdecken. Partner, die befürchten, dass untergenutzte Merkmale ihren Wert senken, können sich darauf verlassen, dass ein selten verwendetes Merkmal automatisch durch die Überprüfung des Mindesttrafficvolumens geschützt wird und nicht in den Wert für den niedrigsten Typ und das niedrigste Merkmal einfließt, es sei denn, es erreicht den erforderlichen Stichprobenschwellenwert.

3. Gerätezustand und Statusgenauigkeit verbessern

Abweichungen treten auf, wenn der in Home Graph gespeicherte Status nicht mit den Ergebnissen einer Echtzeitabfrage übereinstimmt.

Fehler vom Typ „Fehlendes Feld“

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

Ursache:Beim Fehler DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD oder DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD unterscheidet sich die Menge der Nutzlastfelder zwischen Ihrer QUERY-Antwort und Ihrer Report State-Anfrage für dasselbe Gerät.

Lösung:Achten Sie darauf, dass die Datenstruktur in beiden Wegen identisch ist. Wenn ein Merkmal in SYNC enthalten ist, müssen die entsprechenden Felder sowohl in proaktiven Berichten als auch in reaktiven Abfragen vorhanden und konsistent sein.

Fehler vom Typ „Ungenau“

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

Ursache:Beim Fehler DETAILED_ACCURACY_RESULT_INACCURATE gibt es eine Abweichung zwischen dem in der QUERY-Antwort zurückgegebenen Wert und dem letzten Report State-Wert.

Lösung:Achten Sie darauf, dass Report State immer ausgelöst wird, wenn sich der Gerätestatus ändert, und dass sowohl Report State als auch QUERY immer genau dieselben aktuellen Werte und alle erforderlichen Felder liefern, um die Datenkonsistenz aufrechtzuerhalten.

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

Ursache:Beim Fehler DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE hat der Partner den Befehl erfolgreich ausgeführt, den aktualisierten Gerätestatus aber nicht an Google zurückgemeldet.

Lösung:Senden Sie nach der Befehlsausführung immer eine Report State-Aktualisierung, damit Home Graph den neuen Gerätestatus erhält.

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

Ursache:Beim Fehler DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED wurde für dieses Gerät kein Report State empfangen (der Zustand ist leer und der gemeldete Zeitstempel ist auf die Epoche gesetzt), obwohl die QUERY-Ergebnisse den aktuellen Status liefern. Das bedeutet, dass Statusaktualisierungen entweder nicht ausgelöst werden, Home Graph nicht erreichen oder das Gerät Übergänge in seinem Verbindungs- oder Betriebsstatus nicht erfolgreich meldet.

Lösung:Achten Sie darauf, dass Report State für alle Statusänderungen ausgelöst und erfolgreich gesendet wird. Prüfen Sie, ob die Backend-Logik Statusaktualisierungen korrekt verarbeitet, die erfolgreiche Zustellung an Google Home Graph bestätigt und dafür sorgt, dass das Gerät seinen Status konsistent synchronisiert, damit die Benutzeroberfläche und die Automatisierungs-Engine korrekt funktionieren.