Google Home Vitals (Cloud)

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

Das Dashboard enthält drei Abschnitte, die jeweils einen wichtigen Aspekt abdecken, der zur Qualität einer Integration beiträgt.

1. Messwerte für die Zusammenarbeit zwischen Google und Partnern: Hier wird der Zustand von Aufrufen von Google an Ihr Cloud-Backend gemessen.

2. System Health - Partner to Google Metrics (Systemstatus – Messwerte für Partner zu Google): Hier wird der Status von Aufrufen von Ihrem System an Google gemessen.

3. Gerätezustand – Genauigkeit des Status: Misst die Genauigkeit der in Google-Systemen gespeicherten Status, die zur Bearbeitung 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 dazu, 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 auswählen, dann Dashboards und in der Liste Meine Dashboards das Google Home-Vitals-Dashboard (Cloud) auswählen.

Zum Dashboard

Messwerte von Google an Partner

Mit der Messwert Erfolgsrate bei Anfragen/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 fälschliche Bestätigung eines Befehls, der noch nicht ausgeführt wurde, vermieden werden.

Was definiert einen „Erfolg“?

Eine Transaktion wird als erfolgreich markiert, 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. ein SUCCESS-Status in Verbindung mit einer lowBattery-Ausnahme), werden als erfolgreiche Transaktionen gezählt. Der Befehl wurde vom Gerät empfangen und der Intent wurde trotz der Warnung ausgeführt.

Was gilt als „Fehler“?

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

Der Messwert Latenz bei Abfrage/Ausführung (p90) <= 1.000 ms misst die Wartezeit für die angeforderte Aktion und trägt dazu bei, 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 P90-Latenz (90. Perzentil) erfasst. Sie gibt an, wie lange die „langsamsten“ Nutzer warten müssen. Ein P90-Wert von 800 ms bedeutet beispielsweise, dass 90% der Anfragen innerhalb von 800 ms oder weniger beantwortet werden.

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

1. ABFRAGELATENZ (FRAGE)

Damit wird die Cloud-to-cloud-Umlaufzeit gemessen, wenn Google nach dem aktuellen Status eines Geräts fragt.

• Start: Google sendet eine action.devices.QUERY-Anfrage an Ihre Fulfillment-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 Nutzlast der endgültigen Antwort von Ihrem Dienst.

2. EXECUTE-Latenz (Aktion)

Damit wird die Zeit gemessen, die vergeht, bis ein Gerät einen Steuerungsbefehl bestätigt, nachdem Google eine Steuerungsanfrage an das Gerät gesendet hat.

• Start: Google sendet eine action.devices.EXECUTE-Anfrage an Ihre Fulfillment-URL.
• Messzeitraum: Die Zeit, die deine Cloud benötigt, um den Befehl zu empfangen und eine Bestätigungsantwort zurückzugeben.
• Ende: Google erhält die Statusantwort SUCCESS, PENDING oder OFFLINE.
• Technischer Umfang: Mit dieser Messung wird die Zeit für die „Antwortbestätigung“ zwischen der Cloud von Google und Ihrer Cloud gemessen. Es wird nicht die Zeit gemessen, die die physische Hardware (z. B. eine Glühbirne) benötigt, um den physischen Status zu ändern, da dies oft eine lokale Mesh-Netzwerklatenz außerhalb des Cloud-to-Cloud-Pfads beinhaltet.

Optionen zur Latenzreduzierung

Architekturempfehlungen für das geografische Routing

Wenn die Implementierung von Anycast-IP 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 von statischem Routing einen Global Application Load Balancer (bei den meisten großen Cloud-Anbietern verfügbar).

   • Funktionsweise:Sie konfigurieren einen einzelnen globalen Einstiegspunkt (URL) am Netzwerkrand. Der Load-Balancer erkennt automatisch den geografischen Ursprung der Anfrage aus den Fulfillment-Clustern von Google und leitet den Traffic an das nächstgelegene regionale fehlerfreie Backend weiter.

   • Vorteil:Diese Option bietet die Leistung von Anycast bei deutlich geringerer Konfigurationskomplexität und geringeren Kosten.

2. Standortbezogenes DNS (GeoDNS)

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

   • Implementierung:Ihr DNS-Anbieter muss für die Egress-Punkte von Google optimiert sein. Wenn die regionalen Fulfillment-Dienste 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 Region.

Optimierungsstrategien auf der Anwendungsebene

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

1. Die „Trampolin“-Proxy-Methode

   Wenn Sie ein primäres Rechenzentrum betreiben müssen, verwenden Sie regionale Lightweight-Proxyserver (Trampolines), um den ersten Handshake auszuführen.

   1. Google ruft Ihre globale URL auf.

   2. Ein regionaler Proxy (z. B. eine einfache 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 verkürzt, die bei Anfragen über große Entfernungen oft den größten Beitrag zur Latenz leistet.

2. Hinweise zur Region für Zugriffstokens

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

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

Systemzustand – Partner-zu-Google-Messwerte

Wenn du eine Erfolgsrate von mindestens 99,5% beibehältst, werden Gerätestatus in Google Home korrekt angezeigt, Geräte hinzugefügt und entfernt, Automatisierungen ausgelöst und Verlaufsereignisse auf dem Tab „Aktivität“ des Google Home app (GHA) angezeigt.

Die Erfolgsrate wird anhand der HTTP-Antwortcodes berechnet, die von Google zurückgegeben werden, wenn deine Cloud Statusaktualisierungen sendet. Damit Partner nicht für Infrastrukturprobleme auf Google-Seite bestraft werden, werden interne Google-Fehler aus der Anzahl der Fehler ausgeschlossen. Die in die Berechnung einbezogenen API-Aufrufe finden Sie in der HomeGraph API-Referenz.

Was definiert einen „Erfolg“?

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

Was gilt als „Fehler“?

4xx-Fehler (Partnerfehler) weisen auf Fehler hin und deuten auf ein Problem mit der von Ihrer Cloud gesendeten Anfrage hin. 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:Achte 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 HomeGraph nicht gefunden (noch nicht synchronisiert, bereits entknüpft oder ID-Konflikt).

Lösung:

1. Achte darauf, dass agentUserId mit dem Wert in deiner SYNC-Antwort übereinstimmt.
2. Verwende die Home Graph SYNC API, um festzustellen, ob der Fehler 404 „Nicht gefunden“ durch ein fehlendes Gerät oder einen fehlenden Nutzer in Home Graph verursacht wird.
3. Achte darauf, requestSync nach dem Hinzufügen, Entfernen, Umbenennen oder Aktualisieren eines Geräts oder Kontos auszulösen, damit der Status immer auf dem neuesten Stand ist.
4. DISCONNECT-Intents richtig verarbeiten, um die Meldung veralteter Geräte zu beenden. Nachdem Ihr Cloud-Dienst die DISCONNECT-Absicht erhalten hat, sollte er keine Änderungen mehr mit Request Sync und Report State an Google senden.

429 Resource Exhausted (Ressource erschöpft)

Ursache:Ihre Integration hat das zugewiesene Kontingent überschritten.

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

Gerätezustand – Genauigkeit des Status

Wenn du eine Statusgenauigkeit von mindestens 99,5% erreichst oder überschreitest, werden Nutzern korrekte Ergebnisse angezeigt, wenn sie Gerätestatus ansehen oder KI-Funktionen wie „Frag Home“ verwenden. Wenn die Statusgenauigkeit niedrig ist, werden Automatisierungen möglicherweise nicht ausgelöst und Verlaufsereignisse werden möglicherweise nicht rechtzeitig auf dem Tab „Aktivität“ des GHA angezeigt. Weitere Informationen findest du unter Status melden. Hinweis:Das Ziel für die Statusgenauigkeit muss für ALLE unterstützten Attributtypen erreicht werden.

1. Komponenten für die Genauigkeit

Der Messwert wird aus „Stichproben“ abgeleitet, bei denen Google den gemeldeten Status mit einem bekannten Ergebnis der Intention abgleichen kann. Die technische Genauigkeit wird anhand von zwei verschiedenen Pfaden bewertet:

• Abfragebasierte Genauigkeit:Wird überprüft, wenn ein Nutzer oder System den aktuellen Status eines Geräts aktiv abfragt.
• GENAUIGKEIT BEI DER AUSFÜHRUNG:Wird durch Auswerten des Gerätestatus nach dem Befehl überprüft, der nach einer Steuerungsanfrage zurückgemeldet wird.

2. Dashboardmesswerte (stündliche Berechnung)

Im Dashboard wird die Genauigkeit auf Grundlage eines 1-Stunden-Intervalls berechnet. Um die statistische Signifikanz zu gewährleisten und zu vermeiden, dass Integrationen aufgrund von geringem Signalrauschen benachteiligt werden, gilt bei Google ein Mindestschwellenwert für das Trafficvolumen. Wenn für eine bestimmte Kombination aus Merkmal und Gerät in einem rollierenden 5‑Tages-Zeitraum weniger als 100 Stichproben erfasst werden, gilt die Genauigkeit als statistisch nicht signifikant und wird auf N/A gesetzt.

Wenn für eine Stunde in beiden Pfaden ein ausreichendes Stichprobenvolumen vorhanden ist, wird die stündliche Baseline-Genauigkeit für einen bestimmten Bundesstaat als Durchschnitt der beiden unabhängigen Prozentsätze berechnet:

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

Dabei wird jeder Pfad so definiert:

• Genauigkeit der Abfrage % = (Stündliche genaue Stichproben für Abfragen) / (Stündliche Gesamtstichproben für Abfragen)
• Ausführungsgenauigkeit % = (Stündliche genaue Ausführungsproben) / (Stündliche Gesamtzahl der Ausführungsproben)

Messwert für die Genauigkeit von Attributen (pro Attribut berechnet) = SUM(Genauigkeit von Beispielen für Anfragen + Genauigkeit von Beispielen für die Ausführung) / SUM(Gesamtzahl der Beispiele für Anfragen + Gesamtzahl der Beispiele für die Ausführung)

Da der Qualitätsfaktor die Mindestleistung in Ihrem Ökosystem bewertet, muss jedes unterstützte und infrage kommende Attribut einzeln das Ziel von mindestens 99,5% für die Genauigkeit des Status erreichen.Es handelt sich also nicht um einen Durchschnittswert für alle Attribute.

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 Attribute ihren Score senken, können beruhigt sein: Ein selten verwendetes Attribut wird automatisch durch die Prüfung des Mindesttrafficvolumens geschützt und wird nur dann in den niedrigsten Typ- und Attribut-Score einbezogen, wenn es den erforderlichen Stichproben-Schwellenwert erreicht.

3. Genauigkeit von Gerätezustand und ‑status verbessern

Abweichungen treten auf, wenn der im Home Graph gespeicherte Status nicht mit den Ergebnissen einer Echtzeit-QUERY übereinstimmt.

Fehler „Feld fehlt“

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:Bei dem Fehler DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD oder DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD unterscheidet sich die Gruppe der Nutzlastfelder zwischen Ihrer QUERY-Antwort und Ihrer Report State-Anfrage für dasselbe Gerät.

Lösung:Die Datenstruktur muss in beiden Pfaden identisch sein. Wenn ein Attribut in SYNC enthalten ist, müssen die entsprechenden Felder sowohl in proaktiven Berichten als auch in reaktiven Anfragen vorhanden und konsistent sein.

Fehler „Ungenaue Ergebnisse“

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 Diskrepanz zwischen dem in der QUERY-Antwort zurückgegebenen Wert und dem letzten Wert für „Berichtstatus“.

Lösung:Achte darauf, dass „Report State“ immer dann 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 für die Datenkonsistenz liefern.

"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 Ausführung eines Befehls immer ein „Report State“-Update, damit der 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:Für den Fehler DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED wurde für dieses Gerät kein „Report State“ empfangen (der Status ist leer und der gemeldete Zeitstempel ist auf „epoch“ gesetzt), obwohl die QUERY-Ergebnisse den aktuellen Status liefern. Das bedeutet, dass Statusaktualisierungen entweder nicht ausgelöst werden, HomeGraph 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üfe, ob die Backend-Logik Statusaktualisierungen korrekt verarbeitet, die erfolgreiche Zustellung an Google HomeGraph bestätigt und der Gerätestatus konsistent synchronisiert wird, damit die Benutzeroberfläche und die Automatisierungs-Engine korrekt funktionieren.