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 : misura l'integrità delle chiamate da Google a l tuo backend cloud.

2. Integrità del sistema - Metriche da partner a Google : misura l'integrità delle chiamate dal tuo sistema a Google.

3. Integrità del dispositivo - Accuratezza dello stato : misura l'accuratezza degli stati archiviati nei sistemi Google, utilizzati per rispondere alle query degli utenti.

Quando le metriche non soddisfano 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 perché è importante per i tuoi utenti.

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

Vai alla Dashboard

Metriche da Google a partner

La metrica Percentuale di successo di query/esecuzione >= 99,5% misura la frequenza con cui i comandi degli utenti vengono eseguiti correttamente, il che aiuta a evitare risposte dell'Assistente come "Non riesco a raggiungere il dispositivo" o a confermare in modo errato un comando che non è stato ancora 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 partner vengono considerati "errori" nel calcolo delle percentuali di successo di QUERY ed EXECUTE. Inoltre, gli errori rilevati in Errori ed eccezioni sono anch'essi "errori", con le seguenti eccezioni:

La metrica Latenza di query/esecuzione (p90) <= 1000 ms misura il tempo di attesa dell'azione richiesta e aiuta a garantire che gli utenti non debbano attendere troppo a lungo, ad esempio qualche secondo per lo spegnimento della luce.

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).

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

1. Latenza QUERY (interrogativa)

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

• Inizio: Google invia una richiesta action.devices.QUERY all'URL di fulfillment.
• Finestra di misurazione: il tempo impiegato dal tuo cloud per ricevere, elaborare e ritrasmettere la risposta HTTP completa a Google.
• Fine: Google riceve e riconosce 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 all'URL di fulfillment.
• Finestra di misurazione: il tempo impiegato dal tuo cloud per ricevere il comando e restituire una risposta di riconoscimento.
• Fine: Google riceve la risposta di stato SUCCESS, PENDING o OFFLINE.
• Ambito tecnico: questa metrica misura il tempo di "riconoscimento della risposta" tra il cloud di Google e il tuo cloud. Non misura il tempo impiegato dall'hardware fisico (ad esempio, una lampadina) per completare la modifica dello stato fisico, poiché spesso comporta la latenza della rete mesh locale al di fuori del percorso da cloud a cloud.

Suddivisione della sequenza temporale della latenza EXECUTE/QUERY

Quando si analizzano i timestamp per una latenza EXECUTE o QUERY, il tempo di round trip totale può essere suddiviso nel seguente flusso sequenziale:

Poiché questa suddivisione confronta i timestamp lato Google e lato partner, i server dei partner devono essere sincronizzati con NTP (Network Time Protocol). Anche una piccola deriva dell'orologio (50-100 ms) distorcerà i tempi di transito calcolati (t2 - t1 e t4 - t3), portando potenzialmente a metriche logicamente impossibili come latenze di transito negative.

[t1] Richiesta inviata (in uscita da Google) : Google avvia la richiesta di intent. Poiché t1 non è esposto direttamente, viene calcolato approssimativamente sottraendo la latenza totale dal timestamp in entrata finale.

Transito di rete (t1 a t2): il tempo di transito e di coda stimato della rete prima di raggiungere l'endpoint di fulfillment.

[t2] Richiesta ricevuta (in entrata dal partner) : il timestamp esatto in cui la richiesta arriva al gateway API o al server in entrata del tuo ambiente.

Elaborazione del partner (t2 a t3): la latenza di esecuzione interna, routing, e gestione dei dispositivi interamente all'interno del tuo ambiente cloud.

[t3] Risposta inviata (in uscita dal partner) : il timestamp in cui il tuo servizio invia la risposta di fulfillment a Google.

Transito di ritorno (t3 a t4): il tempo di routing della rete di ritorno e di completamento della connessione a Google.

[t4] Richiesta finalizzata (in entrata da Google) : Google riceve ed elabora la risposta finale. Questo timestamp viene registrato esplicitamente nei Google Cloud log come receiveTimestamp.

Per illustrare come queste metriche sono correlate, considera una richiesta di esempio con una latenza totale registrata (latencyMsec) di 1700 ms e un receiveTimestamp (t4) di 2026-05-25T15:25:00.550Z.EXECUTEGoogle Cloud

Opzioni di riduzione della latenza

Consigli sull'architettura per il geo-routing

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 provider di servizi cloud).

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

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

2. DNS con riconoscimento della posizione geografica (GeoDNS)

   • Come funziona:configura il tuo provider DNS in modo che risolva l'URL di fulfillment 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 fulfillment regionali di Google (ad esempio, negli Stati Uniti, nell'UE o in Asia) risolvono il tuo dominio, ricevono l'indirizzo IP del data center nella 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 "Trampoline"

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

   1. Google accede al tuo URL globale.

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

   3. Il proxy inoltra il payload tramite il backbone interno ad alta velocità al database principale.

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

2. Suggerimenti sulla regione del token di accesso

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

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

Integrità del sistema - Metriche da partner a Google

Il mantenimento di una percentuale di successo >= 99, 5% aiuta 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 tuo cloud esegue il push degli aggiornamenti di stato. Per garantire che i partner non vengano penalizzati per i problemi dell'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 dell'API HomeGraph.

Che cosa definisce un "successo"?

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

Che cosa definisce un "errore"?

4xx (errore del partner) rappresentano gli errori e indicano un problema con la richiesta inviata dal tuo cloud. I codici comuni includono:

richiesta non valida (400)

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

Soluzione: assicurati che il corpo della richiesta sia un JSON valido (nessuna struttura non valida 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 trovati in HomeGraph (non ancora sincronizzati, già scollegati o mancata corrispondenza dell'ID).

Soluzione :

1. Assicurati che il agentUserId corrisponda al valore fornito nella tua risposta SYNC.
2. Utilizza l'API SYNC di Home Graph per determinare se l'errore 404: non trovato è causato da un dispositivo mancante o un utente in HomeGraph.
3. Assicurati di attivare requestSync dopo l'aggiunta, la rimozione, la ridenominazione o l'aggiornamento del dispositivo o dell'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 allocata.

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

Integrità del dispositivo - Accuratezza dello stato

Il raggiungimento o il superamento di un'accuratezza dello stato >= 99,5% aiuta a garantire che gli utenti vedano risultati corretti quando visualizzano gli stati dei dispositivi o utilizzano funzionalità di AI come Chiedi a Home. Se l'accuratezza dello stato è bassa, le automazioni potrebbero non essere attivate e le voci della cronologia potrebbero non essere visualizzate nella scheda Attività di GHA al momento giusto. Per ulteriori informazioni, consulta Report State. Nota:il target di accuratezza dello stato deve essere soddisfatto per TUTTI i tratti supportati.

1. Componenti di accuratezza

La metrica è derivata da "campioni" in cui Google può verificare lo stato segnalato rispetto a un risultato di intent noto. Per la precisione tecnica, l'accuratezza viene valutata in due percorsi distinti:

• Accuratezza basata su QUERY:verificata quando un utente o un sistema interroga attivamente lo stato attuale di un dispositivo.
• Accuratezza basata su EXECUTE:verificata valutando lo stato del dispositivo post-comando segnalato dopo una richiesta di controllo.

2. Metriche della dashboard (calcolo orario)

La dashboard calcola l'accuratezza in base a un intervallo di 1 ora. Per garantire la confidenza statistica ed evitare di penalizzare le integrazioni sul rumore a basso indicatore, Google applica una soglia minima del volume di traffico. Se una combinazione specifica di tratto e dispositivo accumula meno di 100 campioni totali in una finestra mobile di 5 giorni, la sua accuratezza viene considerata statisticamente insignificante e viene impostata su N/A.

Quando un'ora ha un volume di campioni sufficiente in entrambi i percorsi, l'accuratezza oraria di base per uno stato specifico viene calcolata come la media delle due percentuali indipendenti:

Accuratezza dello stato orario = (accuratezza della query % + accuratezza dell'esecuzione %) / 2

Dove ogni percorso è definito come:

• Accuratezza della query % = (campioni accurati della query oraria) / (campioni totali della query oraria)
• Accuratezza dell'esecuzione % = (campioni accurati dell'esecuzione oraria) / (campioni totali dell'esecuzione oraria)

Punteggio di accuratezza del tratto (calcolato per tratto) = SOMMA(campioni accurati della query + campioni accurati dell'esecuzione) / SOMMA(campioni totali della query + campioni totali dell'esecuzione)

Poiché il punteggio di qualità valuta il rendimento minimo rigoroso nell'intero ecosistema, ogni singolo tratto supportato ed idoneo deve soddisfare individualmente il target di accuratezza dello stato >= 99,5% (non si tratta di una media tra i tratti).

Questa visualizzazione impedisce ai dispositivi con un volume elevato e un'accuratezza eccellente di mascherare i problemi di accuratezza sui dispositivi con un volume inferiore. I partner che temono che i tratti sottoutilizzati abbassino il loro punteggio possono essere certi che un tratto usato raramente è protetto automaticamente dal controllo del volume di traffico minimo e non verrà preso in considerazione nel punteggio del tipo e del tratto più basso a meno che non soddisfi la soglia di campioni richiesta.

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

Si verificano discrepanze quando lo stato archiviato 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 dei campi del payload differisce tra la risposta QUERY e la richiesta Report State per lo stesso dispositivo.

Soluzione:assicurati che la struttura dei dati sia identica in entrambi i percorsi. Se un tratto è incluso in SYNC, i campi corrispondenti 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 di Report State.

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 segnalato lo stato aggiornato del dispositivo a Google.

Soluzione:invia sempre un aggiornamento di 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 di stato non vengono attivati, non raggiungono HomeGraph o il dispositivo non segnala correttamente le transizioni nel suo stato di connettività o operativo.

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