Questa guida introduce l'endpoint dell'API Chrome UX Report (CrUX) History, che fornisce serie temporali di dati sulle prestazioni web. Questi dati vengono aggiornati settimanalmente e ti consentono di vedere una cronologia di circa 6 mesi, con 25 punti dati distanziati per una settimana.
Se utilizzato insieme agli aggiornamenti giornalieri dell'endpoint originale dell'API CrUX, ora è possibile visualizzare rapidamente sia i dati più recenti sia quelli accaduti in precedenza, il che lo rende un potente strumento per vedere i cambiamenti delle pagine web nel tempo.
Esegui una query sull'API CrUX giornaliera
Per ricapitolare da un articolo precedente sull'API CrUX, puoi ottenere un'istantanea dei dati dei campi per una determinata origine in questo modo:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Questo snapshot include i valori di densità dell'istogramma e i valori percentili per un determinato periodo di raccolta di 28 giorni, in questo caso dal 27 dicembre 2022 al 23 gennaio 2023.
Esegui una query sull'API CrUX History
Per chiamare l'endpoint della cronologia, modifica queryRecord nell'URL in queryHistoryRecord nel comando curl. È possibile utilizzare la stessa chiave API CrUX utilizzata per la chiamata precedente.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev"}'
La forma generale di una risposta è simile, ma ci sono molti più dati. Invece di un singolo punto dati, ora esistono serie temporali per i campi contenenti il 75° percentile (p75) e valori di densità dell'istogramma.
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377
]
}
}
// ...
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
}
}
In questo esempio, la serie temporale densities per il bucket da 0 a 2500 ms della metrica Largest Contentful Paint (LCP) è [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Ciascuna di queste densità è stata osservata durante la voce collectionPeriods corrispondente. Ad esempio, la quinta densità (0,9183) era la densità del quinto periodo di raccolta, che terminava il 3 settembre 2022, e 0,9187 era la densità del periodo che termina la settimana successiva.
In altre parole, interpretando le ultime voci delle serie temporali nell'esempio per https://web.dev, è stato rilevato che dal 14 agosto 2022 al 10 settembre 2022, il 91, 87% dei caricamenti di pagine aveva valori LCP inferiori a 2500 ms, il 5, 27% valori compresi tra 2500 ms e 4200, 0 ms e 4% maggiore di 4 ms.
Allo stesso modo, esiste una serie temporale per i valori p75: il valore LCP p75 per il 14 agosto 2022 e fino al 10 settembre 2022 era 1377. Ciò significa che, per questo periodo di raccolta, il 75% delle esperienze utente ha avuto un LCP inferiore a 1377 ms e il 25% delle esperienze utente ha avuto un LCP superiore a 1377 ms.
Mentre l'esempio elenca solo 6 voci di serie temporali e periodi di raccolta, le risposte dell'API forniscono 25 voci di serie temporali; poiché le date di fine di ciascuno di questi periodi di raccolta sono sabati a distanza di 7 giorni l'una dall'altra, coprendo 6 mesi.
In una determinata risposta, la lunghezza delle serie temporali per le densità bin dell'istogramma e per i valori p75 sarà esattamente uguale alla lunghezza della matrice nel campo collectionPeriods: in queste matrici esiste una corrispondenza uno a uno basata sull'indice.
Query sui dati a livello di pagina
Oltre ai dati a livello di origine, l'API CrUX History consente di accedere ai dati storici a livello di pagina. Mentre in precedenza i dati a livello di origine erano disponibili utilizzando il set di dati CrUX su BigQuery (o la dashboard di CrUX), i dati storici a livello di pagina erano disponibili solo se i siti raccoglievano e memorizzavano i dati stessi. La nuova API ora sblocca questi dati storici a livello di pagina.
È possibile eseguire query sui dati a livello di pagina allo stesso modo, ma utilizzando url anziché origin nel payload:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
I dati storici a livello di pagina (e a livello di origine) sono soggetti agli stessi requisiti di idoneità del resto di CrUX, pertanto le pagine in particolare potrebbero non avere un record storico completo. In questi casi lo stato "mancante" i dati saranno rappresentati da "NaN" per le densità histogramTimeseries e da null per percentilesTimeseries. Il motivo della differenza è che le densità degli istogrammi sono sempre numeri, mentre i percentili possono essere numeri o stringhe (CLS utilizza stringhe, anche se somigliano a numeri).
Visualizza i dati
Potreste domandarvi perché i dati hanno questa forma. È emerso che ciò rende più facile la rappresentazione dei grafici. Ad esempio, ecco un grafico per i valori p75 per Interaction To Next Paint (INP) per https://web.dev:
In questo grafico a linee, ogni valore sull'asse y è un valore p75 della serie temporale p75s e l'asse x è il tempo, che è impostato come lastDate per ogni periodo di raccolta.
Ecco un grafico relativo alle serie temporali degli istogrammi, noto come grafico a tri-bin, perché questi istogrammi hanno tre fasce.
L'asse X è impostato come lastDate per ogni periodo di raccolta. Questa volta, tuttavia, l'asse y rappresenta la percentuale di caricamenti pagina che rientra in un intervallo specifico per la metrica INP, mostrata tramite un grafico a barre in pila. Il grafico di p75 offre una rapida panoramica e, all'interno di un singolo grafico, è relativamente facile aggiungere più metriche o mostrare linee sia per PHONE che per DESKTOP. Il grafico a tre scomparti dà un'idea della distribuzione dei valori delle metriche misurati durante ogni periodo di raccolta.
Ad esempio, anche se il grafico p75 suggerisce che https://web.dev aveva valori INP quasi accettabili durante il periodo di osservazione, il grafico tri-bin mostra che, per una piccola parte dei caricamenti di pagina, l'INP è stato in realtà scarso. In entrambi i grafici, è relativamente facile dedurre che c'era una regressione delle prestazioni che è iniziata verso la fine di ottobre ed è stata risolta a metà novembre.
Per generare personalmente questi grafici, abbiamo creato un esempio di Colab. Un Colab, o "Colaboratory", ti consente di scrivere ed eseguire Python dal tuo browser. L'API CrUX History Colab (fonte) utilizza Python per effettuare chiamate all'API e creare un grafico dei dati.
Questo Colab ti consente di creare grafici p75, grafici a tri-bin, ottenere dati in formato tabulare e visualizzare la coppia di richieste e risposte per l'API CrUX compilando un breve modulo. Non è necessario essere un programmatore per usare questo strumento, ma sicuramente puoi osservare il codice Python e modificarlo in qualcosa di incredibile. Buon divertimento e non esitare a fornire un feedback su ciò che trovi.
Ovviamente non sei limitato a Colab o Python e questo è solo un esempio di come usare questa nuova API. Essendo un endpoint HTTP basato su JSON, l'API può essere interrogata da qualsiasi tecnologia.
Conclusione
Prima dell'introduzione dell'endpoint dell'API CrUX History, i proprietari dei siti avevano un numero limitato di informazioni storiche che potevano ottenere da CrUX. I dati mensili a livello di origine erano disponibili utilizzando BigQuery e la dashboard di CrUX, ma non i dati settimanali né i dati storici a livello di pagina. I proprietari dei siti potevano registrare direttamente questi dati utilizzando l'API giornaliera, ma spesso la necessità di farlo era stata scoperta solo dopo una regressione delle metriche.
La speranza con l'introduzione di questa API CrUX History è che consenta ai proprietari di siti di comprendere meglio l'evoluzione delle metriche del sito, nonché come strumento diagnostico per quando si verificano problemi. Se utilizzi la nuova API, puoi ricevere feedback nel gruppo Google relativo al report sull'esperienza utente di Chrome (Discussioni).
Ringraziamenti
Immagine hero di Dave Herring su Unsplash