1. Prima di iniziare
Questo codelab è progettato per partner e sviluppatori di Google Home con integrazioni cloud per migliorare la qualità dell'ecosistema e l'esperienza utente.
Obiettivi didattici
La dashboard Google Home Vitals funge da fonte centrale di verità per sviluppatori e partner per monitorare lo stato operativo delle loro integrazioni Google Home. In un ecosistema in cui l'esperienza utente è definita da latenza e affidabilità, Google Home Vitals è il portale self-service che contiene tutte le analisi approfondite necessarie per passare dalla risoluzione dei problemi reattiva alla gestione proattiva della qualità.
- Come viene calcolato il punteggio di integrazione di qualità
- Come leggere e utilizzare la dashboard
- Come eseguire il debug delle metriche di scarsa qualità
Che cosa ti serve
- Avere un'integrazione Google Home Cloud
Configurazione
Come accedere alla dashboard Google Home Vitals:
- Apri Google Cloud Platform
- Monitoraggio > Dashboard
- Fai clic sulla dashboard "Google Home Vitals (Cloud)".
2. Come leggere la dashboard
Calcolo del punteggio di qualità: standard "Buono" e "Scarso"
La dashboard spiega la suddivisione per il calcolo del punteggio di qualità. I punteggi di qualità vengono assegnati in base alla granularità del tipo di dispositivo. Perché l'integrazione di un tipo di dispositivo sia considerata BUONA, deve soddisfare quattro criteri simultanei:
- Tasso di successo globale:il tasso di successo complessivo delle chiamate da partner a Google deve essere >=99,5%.
Nota:il mancato raggiungimento del tasso di successo globale (>=99,5%) comporta una valutazione automatica SCARSA per l'intero progetto, indipendentemente dal rendimento dei singoli dispositivi. - Affidabilità dei comandi: i tassi di successo di QUERY ed EXECUTE devono essere >=99,5% per ogni tipo di dispositivo.
- Latenza reattiva:la latenza del 90° percentile per QUERY ed EXECUTE deve essere <=1000 ms per ogni tipo di dispositivo.
- Integrità dello stato:l'accuratezza dello stato deve essere >=99,5%.
Perché queste metriche sono importanti
- Tasso di successo globale:le chiamate da partner a Google a livello di integrazione misurano l'integrità delle chiamate dal tuo cloud a Google. Un tasso di successo pari ad almeno il 99,5% garantisce che Google Home utilizzi gli stati corretti dei dispositivi. Alcuni esempi includono l'aggiunta e la rimozione di dispositivi, l'attivazione di automazioni e la visualizzazione degli eventi della cronologia nella scheda Attività dell'app Google Home.
- Affidabilità dei comandi: i tassi di successo di QUERY ed EXECUTE vengono misurati a livello di tipo di dispositivo. Un tasso di successo >=99, 5% garantisce che i comandi dell'utente vengano eseguiti correttamente (ovvero evita risposte dell'assistente come "Non riesco a raggiungere il dispositivo" o la conferma errata di un comando che non è stato eseguito).
- Latenza reattiva:le latenze QUERY ed EXECUTE vengono misurate anche a livello di tipo di dispositivo.Una latenza <=1000 ms per tipo di dispositivo garantisce che l'utente non debba attendere troppo a lungo per eseguire l'azione desiderata (ad es. attendere alcuni secondi prima che la luce si spenga).
- Integrità dello stato:Misura l'accuratezza dello stato memorizzato nei sistemi Google e utilizzato per erogare le query degli utenti. Se questi numeri sono bassi, gli utenti potrebbero visualizzare risultati errati per i tuoi dispositivi quando ne visualizzano lo stato o utilizzano funzionalità di AI come Chiedi a Home. Le automazioni potrebbero non attivarsi e le voci della cronologia potrebbero non essere visualizzate in Attività al momento giusto.
Come leggere la dashboard
Inizia dalla sezione Metriche del punteggio di qualità, che funge da indicatore principale dello stato dell'integrazione. Una BUONA valutazione a livello di dispositivo dipende dal rispetto dei criteri di successo VERDI per tutte le metriche in questa sezione. I requisiti tecnici dettagliati e le definizioni delle metriche sono disponibili nella documentazione del Developer Center.
La sezione "Punteggio delle metriche di qualità" nella parte superiore della dashboard Google Home Vitals riflette le metriche utilizzate per calcolare il punteggio di qualità dell'integrazione.
Legenda
- VERDE (BUONO): la metrica soddisfa la soglia di qualità.
- ROSSO (SCARSA): la metrica non soddisfa la soglia di qualità.
Esempio
Nell'esempio riportato di seguito, puoi notare che il tipo di dispositivo AC_UNIT soddisfa i criteri di qualità nella sezione Tasso di successo di QUERY ed EXECUTE e nella sezione Latenza QUERY, ma non supera la barra Latenza EXECUTE (rossa). Ciò significa che i comandi vengono eseguiti a una velocità accettabile, ma la latenza EXECUTE è troppo lenta di 36 ms. La sezione Integrità del sistema mostra un tasso di errore del 98,92% per i metodi aggregati nell'integrazione, il che significa che è possibile migliorare l'accuratezza degli stati dei dispositivi degli utenti in Google Home. Ciò significa che l'1, 08% delle chiamate (DeleteAgentUser, Query, ReportStateAndNotification, RequestSyncDevices o Sync) restituisce codici di risposta diversi da 2xx o 5xx (ad es. errori 404). L'ultima metrica utilizzata per misurare la qualità superata/non superata per il tipo di dispositivo AC_UNIT è l'accuratezza dello stato. In questo esempio, la percentuale di successo è del 77,43%, il che significa che è probabile che gli utenti visualizzino risultati imprecisi per i dispositivi. Con queste tre metriche, il punteggio complessivo per AC_UNIT è SCARSO e inferiore alla soglia di qualità.
Ciascuno di questi calcoli della qualità corrisponde a una sezione di debug riportata di seguito. Apri i passaggi compressi per eseguire un ulteriore debug.
Per eseguire il debug delle percentuali di successo e delle latenze di QUERY/EXECUTE, vai a "Passaggio 1: valida le chiamate cloud".
Per eseguire il debug dei tassi di successo da Partner a Google, vai a "Passaggio 2: valida le chiamate a Google".
Per eseguire il debug della precisione dello stato per ogni tipo di dispositivo, vai a "Passaggio 3: migliora la precisione dello stato".
3. Passaggio 1 per il debug: convalida le chiamate cloud
Passaggio 1: panoramica
Questa sezione si concentra sulle chiamate cloud, ovvero le metriche che misurano l'integrità delle comunicazioni da Google al tuo backend cloud (note anche come metriche da Google al partner). Sono inclusi comandi come Query, Execute.
Monitoriamo i tassi di successo e le latenze per QUERY ed EXECUTE (che influiscono sui punteggi di qualità del tipo di dispositivo).
La panoramica riportata di seguito mostra le percentuali di successo e gli errori aggregati di QUERY ed EXECUTE a livello di integrazione. I passaggi da 1a a 1d mostrano la suddivisione di queste metriche a livello di tipo/caratteristica del dispositivo. 
I passaggi 1a e 1b mostrano l'andamento del conteggio delle richieste di evasione, i conteggi degli errori nel tempo e gli stati di errore specifici.
Passaggio 1a: esamina gli errori di query
Passaggio 1b: esamina gli errori di esecuzione
I passaggi 1c e 1d mostrano anche la suddivisione del 90° e del 50° percentile per queste metriche sia a livello di integrazione che di tipo di dispositivo.
Passaggio 1c: esamina la latenza delle query
Passaggio 1d: esamina la latenza di esecuzione
4. Passaggio di debug 2: convalida delle chiamate a Google
Passaggio 2: panoramica
Dopo il debug delle chiamate da Google al partner, questo secondo passaggio riguarda il debug delle chiamate dal cloud del partner a Google. Questa sezione copre le metriche a livello di integrazione partner, non a livello di tipo di dispositivo. Sono inclusi codici di risposta come 400 Bad Request, 404 Not Found e 429 Resource Exhausted.
Passaggio 2a: esegui il debug dei problemi relativi alla quota
Google Home limita l'allocazione e l'utilizzo delle risorse e applica quote appropriate in base al singolo progetto. Google applica il limite predefinito di 6000 richieste ogni 60 secondi all'aggregazione delle chiamate API di query, eliminazione, Report State e sincronizzazione delle richieste asincrone, in base all'integrazione da cloud a cloud.
Il raggiungimento dei limiti di quota può influire negativamente sull'accuratezza dello stato del report, perché il mancato completamento di un aggiornamento dello stato può causare una mancata corrispondenza. Di seguito sono riportati grafici con suddivisioni che mostrano in modo specifico lo stato del report e gli errori di sincronizzazione delle richieste, la suddivisione del conteggio e degli errori del metodo API, nonché la percentuale di utilizzo della quota. Se questi grafici mostrano un aumento imprevisto del traffico, esamina l'integrazione per determinare se una modifica sta causando l'invio di più traffico all'API Home Graph.
In alcuni scenari, ad esempio la crescita naturale del traffico nel tempo (ad es. la crescita è coerente con un aumento del numero di dispositivi, il lancio di un nuovo tipo di dispositivo o un altro lancio previsto), potrebbe essere opportuno aumentare la quota per l'integrazione. Per richiedere un aumento della quota, segui i passaggi descritti nella nostra documentazione per gli sviluppatori.
5. Passaggio di debug 3: migliora l'accuratezza dello stato
Passaggio 3: panoramica
Dopo aver eseguito il debug dei passaggi 1 e 2, il passaggio 3 riguarda l'accuratezza di Report State, ovvero gli stati del dispositivo memorizzati nei sistemi Google, che vengono utilizzati per rispondere alle query degli utenti. Di seguito sono riportate le suddivisioni per caratteristica e tipo di dispositivo. I passaggi 3a e 3b riguardano due errori comuni per lo stato del report, ovvero errori relativi a campi mancanti ed errori imprecisi.
Passaggio 3a: errori "Campo mancante"
Gli errori "Campo mancante" si verificano quando l'insieme di campi del payload differisce tra una risposta QUERY e una richiesta di stato segnalato per un determinato dispositivo. Il set di campi all'interno del payload di ogni dispositivo deve essere lo stesso. Ciò può essere causato se la logica per calcolare il payload differisce tra la risposta QUERY e lo stato del report. Utilizza i grafici riportati di seguito per tracciare i tipi di dispositivi e le caratteristiche che presentano risposte QUERY e report state non corrispondenti.
Passaggio 3b: errori "Impreciso"
Gli errori imprecisi si verificano quando l'insieme di campi del payload è lo stesso tra una risposta QUERY e una richiesta di stato segnalato per un determinato dispositivo, ma i valori di stato sono diversi. Ciò può essere causato dalla mancata ricezione di un report sullo stato o se la logica per calcolare lo stato è diversa tra QUERY e un report sullo stato. Utilizza i grafici riportati di seguito per tracciare i tipi di dispositivi e le caratteristiche che presentano risposte QUERY e report state non corrispondenti.
6. Altra documentazione e risorse
- Per inviare feedback o segnalare problemi relativi a questa dashboard, segnala un problema nel nostro Issue Tracker pubblico.
- Per presentare una richiesta di ricorso, segnala un problema utilizzando il nostro modulo di ricorso relativo alla metrica di qualità.
- Per monitorare regolarmente la qualità dell'integrazione, configura gli avvisi di Google Cloud per ricevere notifiche quando le metriche scendono al di sotto di una soglia accettabile. In questo modo, sarai il primo a sapere quando si verifica un problema.
- Per tutte le altre informazioni, consulta la documentazione per sviluppatori all'indirizzo https://developers.home.google.com/tools/analytics/home-vitals.