Google Home Vitals (cloud)

Questa suite di dashboard e avvisi ti aiuta a mantenere in modo proattivo un'integrazione di alta qualità con l'ecosistema Google Home. Google si impegna a supportare i partner nello sviluppo di un ecosistema di alta qualità per tutti i clienti

La dashboard è suddivisa in tre sezioni, ognuna delle quali copre una parte fondamentale che contribuisce alla qualità di un'integrazione complessiva.

1. Metriche da Google a partner: misurano l'integrità delle chiamate da Google al tuo backend cloud.

2. Stato del sistema - Metriche partner-Google: misura lo stato delle chiamate dal tuo sistema a Google.

3. Integrità del dispositivo - Precisione dello stato: misura la precisione degli stati archiviati nei sistemi Google, che vengono utilizzati per rispondere alle query degli utenti.

Quando le metriche non raggiungono i valori target, vengono evidenziate in rosso per indicare un problema che potrebbe influire sull'esperienza utente. Le seguenti informazioni forniscono dettagli su ogni target e sul motivo per cui è importante per i tuoi utenti.

Se il pulsante seguente non ti reindirizza direttamente alla dashboard, puoi accedervi selezionando la pagina Panoramica, poi Dashboard e infine Dashboard Google Home Vitals (Cloud) dall'elenco Le mie dashboard.

Vai alla Dashboard

Metriche da Google al partner

La metrica Tasso di successo di query/esecuzione >= 99,5% misura la frequenza con cui i comandi degli utenti vengono eseguiti correttamente, il che contribuisce a evitare risposte dell'assistente come "Non riesco a raggiungere il dispositivo" o la conferma errata di un comando che non è stato eseguito.

Che cosa definisce un "successo"?

Una transazione viene contrassegnata come riuscita se la piattaforma Google Home riceve una risposta valida che indica che l'azione prevista è stata eseguita o che lo stato richiesto è stato recuperato.

Le risposte che includono eccezioni non bloccanti (ad esempio, uno stato SUCCESS accompagnato da un'eccezione lowBattery) vengono conteggiate come transazioni riuscite. Il comando ha raggiunto il dispositivo e l'intent è stato soddisfatto nonostante l'avviso.

Che cosa definisce un "errore"?

Gli errori rilevati in Codici di errore comuni della piattaforma contrassegnati come Azione del partner vengono considerati "Errori" durante il calcolo delle percentuali di successo di QUERY ed EXECUTE. Inoltre, gli errori rilevati in Errori ed eccezioni sono considerati "Errori", con le seguenti eccezioni:

La metrica Latenza query/esecuzione (p90) <= 1000 ms misura il tempo di attesa dell'azione richiesta e contribuisce a garantire che gli utenti non debbano aspettare troppo a lungo, ad esempio, qualche secondo prima che la luce si spenga.

Metriche di latenza

La latenza è un indicatore fondamentale della reattività dell'integrazione per l'utente finale. La dashboard monitora la latenza del 90° percentile (P90), che rappresenta l'esperienza degli utenti "più lenti" (ad esempio, un P90 di 800 ms significa che il 90% delle richieste viene riconosciuto in 800 ms o meno).

Google misura la latenza in modo diverso per i controlli dello stato rispetto ai comandi del dispositivo per garantire l'accuratezza tecnica.

1. QUERY Latency (Interrogative)

Misura il tempo di andata e ritorno di Cloud-to-cloud quando Google chiede lo stato attuale di un dispositivo.

• Inizio: Google invia una richiesta action.devices.QUERY al tuo URL di evasione.
• Finestra di misurazione: il tempo impiegato dal cloud per ricevere, elaborare e trasmettere la risposta HTTP completa a Google.
• Fine: Google riceve e conferma il payload della risposta finale dal tuo servizio.

2. Latenza EXECUTE (azione)

Misura il tempo di riconoscimento del comando quando Google invia una richiesta di controllo a un dispositivo.

• Inizio: Google invia una richiesta action.devices.EXECUTE al tuo URL di evasione.
• Finestra di misurazione: il tempo impiegato dal cloud per ricevere il comando e restituire una risposta di riconoscimento.
• Fine: Google riceve la risposta con lo stato SUCCESS, PENDING o OFFLINE.
• Ambito tecnico: questa metrica misura il tempo di "Response Ack" tra il cloud di Google e il tuo cloud. Non misura il tempo necessario all'hardware fisico (ad esempio una lampadina) per completare il cambio di stato fisico, poiché spesso ciò comporta una latenza della rete mesh locale al di fuori del percorso cloud-to-cloud.

Opzioni di riduzione della latenza

Consigli sull'architettura per il georouting

Se l'implementazione dell'IP Anycast non è fattibile, ti consigliamo le seguenti alternative economiche per garantire che gli utenti vengano serviti dal data center regionale più vicino.

1. Global Load Balancing (GLB)

   Anziché il routing statico, utilizza un bilanciatore del carico delle applicazioni globale (disponibile dalla maggior parte dei principali fornitori di servizi cloud).

   • Come funziona: configuri un unico punto di ingresso globale (URL) che si trova al limite della rete. Il bilanciatore del carico rileva automaticamente l'origine geografica della richiesta dai cluster di evasione di Google e instrada il traffico al backend regionale integro più vicino.

   • Vantaggio:offre le prestazioni di Anycast con costi e complessità di configurazione notevolmente inferiori.

2. DNS con riconoscimento della posizione geografica (GeoDNS)

   • Come funziona:configura il tuo provider DNS in modo che risolva l'URL di evasione in indirizzi IP diversi in base alla posizione geografica della query DNS.

   • Implementazione:assicurati che il tuo provider DNS sia ottimizzato per i punti di uscita di Google. Quando i servizi di evasione regionali di Google (ad esempio, negli Stati Uniti, nell'UE o in Asia) risolvono il tuo dominio, ricevono l'indirizzo IP per il data center in quella regione specifica.

Strategie di ottimizzazione a livello di applicazione

Oltre al routing a livello di infrastruttura, puoi implementare le seguenti strategie a livello di applicazione per ridurre la latenza nell'elaborazione delle richieste.

1. Il metodo proxy "Trampolino"

   Se devi mantenere un data center principale, utilizza i server proxy leggeri regionali (trampolini) per gestire l'handshake iniziale.

   1. Google accede all'URL globale.

   2. Un proxy regionale (ad esempio una funzione Nginx o Lambda leggera) riceve la richiesta.

   3. Il proxy inoltra il payload tramite la tua dorsale interna ad alta velocità al database primario.

   Vantaggio:questo riduce il tempo di "handshake TCP", che spesso è il principale fattore di latenza per le richieste a lunga distanza.

2. Suggerimenti per la regione del token di accesso

   Durante la procedura di collegamento dell'account (OAuth), il sistema può identificare la regione di residenza dell'utente.

   Implementazione:codifica un identificatore di regione nel access_token emesso a Google. Quando Google invia una richiesta di evasione, il gateway può ispezionare immediatamente il token e indirizzare la richiesta al cluster regionale corretto senza dover eseguire una ricerca nel database.

Integrità del sistema - Metriche partner-Google

Il mantenimento di un tasso di successo >= 99, 5% contribuisce a garantire che gli stati dei dispositivi siano corretti in Google Home, che i dispositivi vengano aggiunti e rimossi, che le automazioni vengano attivate e che gli eventi della cronologia vengano visualizzati nella scheda Attività di Google Home app (GHA).

La percentuale di successo viene calcolata in base ai codici di risposta HTTP restituiti da Google quando il cloud esegue il push degli aggiornamenti di stato. Per garantire che i partner non vengano penalizzati per problemi di infrastruttura lato Google, la metrica esclude gli errori interni di Google dal conteggio degli errori. Le chiamate API incluse nel calcolo sono disponibili nel riferimento API HomeGraph.

Che cosa definisce un "successo"?

2xx (Riuscito): l'aggiornamento dello stato è stato ricevuto ed elaborato correttamente da Home Graph.

Che cosa definisce un "errore"?

4xx (Partner Error) rappresentano errori e indicano un problema con la richiesta inviata dal tuo cloud. I codici più comuni includono:

400 Richiesta errata

Causa: il server non è riuscito a elaborare la richiesta a causa di una sintassi non valida. Le cause più comuni includono JSON malformato o l'utilizzo di null anziché "" per un valore stringa.

Soluzione: assicurati che il corpo della richiesta sia un JSON valido (nessuna struttura errata o valori nulli per i campi stringa) e verifica che agentUserId corrisponda al valore della risposta SYNC.

404: non trovato

Causa: deviceId o agentUserId non trovato in HomeGraph (non ancora sincronizzato, già scollegato o ID non corrispondente).

Soluzione:

1. Assicurati che agentUserId corrisponda al valore fornito nella risposta SYNC.
2. Utilizza l'API Home Graph SYNC per determinare se l'errore 404 Not Found è causato da un dispositivo o da un utente mancante in HomeGraph.
3. Assicurati di attivare requestSync dopo l'aggiunta, la rimozione, la ridenominazione o l'aggiornamento di un dispositivo o un account per assicurarti che lo stato rimanga aggiornato.
4. Gestisci correttamente gli intent DISCONNECT per interrompere la segnalazione di dispositivi obsoleti. Dopo aver ricevuto l'intent DISCONNECT, il tuo servizio cloud deve interrompere la pubblicazione delle modifiche su Google con Request Sync e Report State.

429 Risorsa esaurita

Causa: la tua integrazione ha superato la quota assegnata.

Soluzione: consulta le istruzioni nella sezione "Passaggio 2a: esegui il debug dei problemi relativi alla quota" nel dashboard per la gestione delle quote. Per ulteriori informazioni, puoi anche consultare Quote e limiti di Smart Home.

Integrità del dispositivo - Accuratezza dello stato

Se viene soddisfatto o superato il requisito Precisione stato >= 99,5%, gli utenti vedranno risultati corretti quando visualizzano gli stati dei dispositivi o utilizzano funzionalità di AI come Chiedi a Home. Se la precisione dello stato è bassa, le automazioni potrebbero non attivarsi e le voci della cronologia potrebbero non essere visualizzate nella scheda Attività di GHA al momento giusto. Per maggiori informazioni, consulta Stato report.

La dashboard della qualità monitora questo valore ogni ora utilizzando due metriche distinte: Accuratezza complessiva e Combinazione tipo/caratteristica più bassa.

1. Componenti di precisione

La metrica è derivata da "campioni" in cui Google può verificare lo stato segnalato rispetto a un risultato di intent noto.

2. Metriche della dashboard (calcolo orario)

La dashboard calcola l'accuratezza in base a un intervallo di un'ora. Se un'ora ha meno di 100 campioni totali (S_Total < 100), l'accuratezza per quell'ora è impostata su N/A.

Visualizzazione 1: accuratezza complessiva (media globale)

Rappresenta l'accuratezza totale dell'integrazione in tutti i tipi di dispositivi e le caratteristiche combinate. Fornisce una media ponderata dell'integrità dell'intero ecosistema.

• Calcolo: accuratezza totale dello stato su tutti i dispositivi / totale dello stato totale su tutti i dispositivi.

Visualizzazione 2: combinazione di tipo/tratto più bassa

Identifica la categoria specifica meno affidabile nell'integrazione. Impedisce ai dispositivi ad alto volume di alta qualità di nascondere i dispositivi a basso volume di bassa qualità. Ad esempio, se hai un volume elevato di luci con una precisione dello stato superiore al 99,5%, ma un volume basso di interruttori con una precisione dello stato bassa, questo evidenzia il miglioramento necessario per gli interruttori che potrebbero essere persi in un valore medio.

• Calcolo: minimo di Accuratezza stato / Totale stato per tutte le combinazioni di tratto/dispositivo.

3. Migliorare l'accuratezza dello stato e dell'integrità del dispositivo

Le discrepanze si verificano quando lo stato memorizzato in Home Graph non corrisponde ai risultati di una QUERY in tempo reale.

Errori "Campo mancante"

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 l'errore DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD o DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, l'insieme di campi del payload differisce tra la risposta QUERY e la richiesta di stato del report per lo stesso dispositivo.

Soluzione:assicurati che la struttura dei dati sia identica in entrambi i percorsi. Se una caratteristica è inclusa in SYNC, i relativi campi devono essere presenti e coerenti sia nei report proattivi sia nelle query reattive.

Errori "Impreciso"

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:per l'errore DETAILED_ACCURACY_RESULT_INACCURATE, esiste una discrepanza tra il valore restituito nella risposta QUERY e l'ultimo valore dello stato del report.

Soluzione:assicurati che Report State venga attivato ogni volta che lo stato di un dispositivo cambia e che sia Report State sia QUERY forniscano sempre gli stessi valori aggiornati e tutti i campi obbligatori per mantenere la coerenza dei dati.

"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 l'errore DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, il partner ha eseguito il comando correttamente, ma non ha comunicato a Google lo stato aggiornato del dispositivo.

Soluzione:invia sempre un aggiornamento Report State dopo l'esecuzione del comando in modo che Home Graph riceva il nuovo stato 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: per l'errore DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, non è stato ricevuto alcun Report State per questo dispositivo (lo stato è vuoto e il timestamp segnalato è all'epoca), nonostante i risultati della QUERY forniscano lo stato attuale. Ciò indica che gli aggiornamenti dello stato non vengono attivati, non riescono a raggiungere HomeGraph o il dispositivo non segnala correttamente le transizioni nel suo stato di connettività o operativo.

Soluzione: assicurati che lo stato del report venga attivato e inviato correttamente per tutte le modifiche di stato. Verifica che la logica di backend gestisca correttamente gli aggiornamenti di stato, confermi l'esito positivo della consegna a Google HomeGraph e garantisca che il dispositivo sincronizzi costantemente il proprio stato per mantenere accurati l'interfaccia utente e il motore di automazione.