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 è composta da tre sezioni, ognuna delle quali copre una parte fondamentale che contribuisce alla qualità di un'integrazione complessiva.

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

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

3. Stato del dispositivo - Precisione dello stato: misura la precisione degli stati memorizzati 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 ciascun target e sul motivo per cui è 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 tua dashboard.

Vai alla Dashboard

Metriche di Google per i partner

La metrica Tasso di successo di Query/Execute >= 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 la conferma errata di un comando che non è stato ancora eseguito.

La metrica Tasso di successo della sincronizzazione >= 99,5% misura la frequenza con cui le richieste di sincronizzazione vengono soddisfatte correttamente, il che garantisce che i dispositivi mostrati in Google Home siano sincronizzati con i dispositivi connessi alla tua infrastruttura cloud.

Che cosa si intende per "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 si intende per "errore"?

Gli errori rilevati in Codici di errore comuni della piattaforma contrassegnati come Partner Actionable sono considerati "Errori" nel calcolo dei tassi di successo di QUERY, EXECUTE e SYNC. Inoltre, gli errori rilevati in Errori ed eccezioni sono anche "Errori", con le seguenti eccezioni:

Parità dello stato della risposta di esecuzione

Quando restituisci uno stato SUCCESS in una risposta EXECUTE, l'oggetto states del payload della risposta deve contenere tutti i campi di stato attivi e aggiornati definiti dai tratti che stai eseguendo. Se ometti i campi di stato obbligatori o restituisci un oggetto states vuoto per i tratti complessi, la piattaforma Google Home non riuscirà ad analizzare il risultato dell'esecuzione, registrandolo come errore AGENT_ISSUE o INVALID_RESPONSE, il che riduce il tasso di successo di Query ed Execute.

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

Metriche di latenza

La latenza è un indicatore fondamentale della reattività della tua 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 confermato in 800 ms o meno).

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

1. QUERY Latency (Interrogative)

Misura il tempo di round trip di Cloud-to-cloud quando Google richiede lo stato attuale di un dispositivo.

• Inizio: Google invia una richiesta action.devices.QUERY al tuo URL di fulfillment.
• Finestra di misurazione: il tempo impiegato dal tuo 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)

Questo valore misura il tempo di conferma del comando quando Google invia una richiesta di controllo a un dispositivo.

• Inizio: Google invia una richiesta action.devices.EXECUTE al tuo URL di fulfillment.
• Finestra di misurazione: il tempo impiegato dal cloud per ricevere il comando e restituire una risposta di conferma.
• Fine: Google riceve la risposta di 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 la modifica dello stato fisico, poiché spesso ciò comporta una latenza della rete mesh locale al di fuori del percorso cloud-to-cloud.

Suddivisione della cronologia della latenza di EXECUTE/QUERY

Quando analizzi 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 di Google e del partner, i server del partner devono essere sincronizzati con NTP (Network Time Protocol). Anche una lieve deviazione 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 (Google in uscita): 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 (da t1 a t2): il tempo stimato di transito di rete e di coda prima di raggiungere l'endpoint di fulfillment.

[t2] Richiesta ricevuta (Ingress partner): il timestamp esatto in cui la richiesta arriva all'API Gateway o al server Ingress del tuo ambiente.

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

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

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

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

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

Opzioni di riduzione della latenza

Consigli sull'architettura per il routing geografico

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

1. Bilanciamento del carico globale (GLB)

   Anziché il routing statico, utilizza un bilanciatore del carico delle applicazioni globale (disponibile presso la maggior parte dei principali cloud provider).

   • Come funziona: configuri un unico punto di ingresso globale (URL) che si trova sul perimetro 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 integro regionale più vicino.

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

2. DNS sensibile alla geolocalizzazione (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 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 "Trampoline"

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

   1. Google raggiunge l'URL globale.

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

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

   Vantaggio: riduce il tempo di "handshake TCP", che spesso è il fattore che contribuisce maggiormente alla 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 tuo sistema può identificare la regione di residenza dell'utente.

   Implementazione: codifica un identificatore della regione nel access_token emesso per Google. Quando Google invia una richiesta di fulfillment, il tuo 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 da partner a Google

Mantenere un tasso 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).

Il tasso di successo viene calcolato in base ai codici di risposta HTTP restituiti da Google quando il tuo cloud invia 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 si intende per "Successo"?

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

Che cosa si intende per "errore"?

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

400 Bad Request

Causa: il server non è riuscito a elaborare la richiesta a causa di una sintassi non valida. Le cause più comuni includono un 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 con formato non corretto o valori null 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 SYNC di Home Graph per determinare se l'errore 404 - Non trovato è causato da un dispositivo o un utente mancante in Home Graph.
3. Assicurati di attivare requestSync dopo l'aggiunta, la rimozione, la ridenominazione o l'aggiornamento di un dispositivo o di 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: l'integrazione ha superato la quota assegnata.

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

Stato del dispositivo - Precisione dello stato

Raggiungere o superare un valore di Precisione stato >= 99,5% aiuta a garantire che gli utenti vedano i 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 attivarsi e le voci della cronologia potrebbero non essere visualizzate nella scheda Attività di GHA al momento giusto. Per saperne di più, consulta Report State. Nota:il target di accuratezza dello stato deve essere soddisfatto per TUTTI i tratti supportati.

1. Componenti di accuratezza

La metrica viene ricavata 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 base a due percorsi distinti:

• Precisione basata su QUERY:verificata quando un utente o un sistema interroga attivamente lo stato attuale di un dispositivo.
• Precisione basata su EXECUTE:verificata valutando lo stato del dispositivo dopo il comando segnalato in seguito a 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 l'affidabilità statistica ed evitare di penalizzare le integrazioni con un rumore di segnale basso, Google applica una soglia minima del volume di traffico. Se una combinazione specifica di tratto e dispositivo accumula meno di 100 campioni totali in un periodo di 5 giorni, la sua accuratezza è 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 = (% di accuratezza delle query + % di accuratezza dell'esecuzione) / 2

Dove ogni percorso è definito come:

• %di accuratezza delle query = (Campioni accurati di query orarie) / (Campioni totali di query orarie)
• %di accuratezza dell'esecuzione = (Campioni accurati di esecuzione oraria) / (Campioni totali di 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 assoluto nell'ecosistema, ogni singolo tratto supportato e idoneo deve soddisfare individualmente il target di precisione 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 preoccupati che i tratti sottoutilizzati possano abbassare il loro punteggio possono stare tranquilli: un tratto utilizzato raramente viene protetto automaticamente dal controllo del volume di traffico minimo e non verrà preso in considerazione nel punteggio Tipo e tratto più basso, a meno che non soddisfi la soglia del campione richiesta.

3. Miglioramento dell'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 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 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 alcuno stato del report 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 riescono a raggiungere HomeGraph o che il dispositivo non segnala correttamente le transizioni nel suo stato di connettività o di funzionamento.

Soluzione: assicurati che Report State 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 assicuri che il dispositivo sincronizzi costantemente il proprio stato per mantenere accurate l'interfaccia utente e il motore di automazione.