Questa guida presenta l'endpoint dell'API Chrome UX Report (CrUX) History, che fornisce serie temporali di dati sulle prestazioni web. Questi dati vengono aggiornati ogni settimana e ti consentono di vedere la storia di circa 6 mesi, con 25 punti dati suddivisi per settimana.
Se utilizzato con gli aggiornamenti giornalieri dall'endpoint API CrUX originale, ora è possibile visualizzare rapidamente sia i dati più recenti sia ciò che è accaduto in precedenza, il che fa di questo strumento un potente strumento per vedere i cambiamenti delle pagine web nel tempo.
Esegui una query sull'API CrUX giornaliera
Ricapitolando 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 }
}
}
}
Questa istantanea include i valori di densità degli istogrammi 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. Puoi usare 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! Anziché un singolo punto dati, ora esistono serie temporali per i campi contenenti il 75° percentile (p75) e i valori di densità degli istogrammi.
{
"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].. Ognuna di queste densità è stata osservata durante la voce collectionPeriods corrispondente. Ad esempio, la quinta densità, 0,9183, è stata la densità per il quinto periodo di raccolta, che termina il 3 settembre 2022, e 0,9187 è la densità nel periodo che termina la settimana successiva.
In altre parole, interpretando le ultime voci della serie temporale nell'esempio per https://web.dev, è stato rilevato che dal 14 agosto 2022 al 10 settembre 2022, il 91, 87% dei caricamenti pagina aveva valori LCP inferiori a 2500 ms, il 5, 27% aveva valori compresi tra 2500 ms e 4008 ms superiori a 0 ms e 0, 4%
Allo stesso modo, esiste una serie temporale per i valori p75: l'LCP p75 per il periodo dal 14 agosto 2022 al 10 settembre 2022 era 1377. Ciò significa che, durante questo periodo di raccolta, il 75% delle esperienze utente aveva un LCP inferiore a 1377 ms e il 25% delle esperienze utente aveva 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 per ciascuno di questi periodi di raccolta sono sabati a distanza di 7 giorni, l'intervallo copre 6 mesi.
In ogni risposta, la lunghezza della serie temporale per le densità del bin degli istogrammi e per i valori di p75 sarà esattamente la stessa della lunghezza dell'array nel campo collectionPeriods: esiste una corrispondenza uno a uno basata sull'indice in questi array.
Eseguire 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 i dati a livello di origine erano disponibili in precedenza utilizzando il set di dati CrUX su BigQuery (o tramite la dashboard di CrUX), i dati storici a livello di pagina erano disponibili solo se i siti raccoglievano e archiviavano i dati stessi. La nuova API ora consente di accedere a questi dati storici a livello di pagina.
È possibile eseguire query sui dati a livello di pagina nello 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 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, i dati "mancanti" 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 (il CLS utilizza le stringhe, anche se hanno l'aspetto di numeri).
Visualizzare i dati
Quindi, potresti domandarti: perché i dati sono modellati in questo modo? È stato riscontrato che ciò semplifica 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.
Di seguito è riportato un grafico relativo alle serie temporali della sezione degli istogrammi, nota come grafico tri-bin, perché questi istogrammi hanno tre bin.
L'asse x è impostato come lastDate per ogni periodo di raccolta. Questa volta, tuttavia, l'asse y è la percentuale di caricamenti pagina che rientrano in un intervallo specifico per la metrica INP, mostrata tramite un grafico a barre in pila. Il grafico 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 tri-bin dà un'idea della distribuzione dei valori delle metriche misurati durante ciascun periodo di raccolta.
Ad esempio, anche se il grafico p75 suggerisce che https://web.dev presentava valori INP quasi accettabili durante il periodo di osservazione, il grafico tri-bin mostra che per una piccola parte dei caricamenti pagina, l'INP era in realtà scarso. In entrambi i grafici, è relativamente facile dedurre che una regressione delle prestazioni è iniziata verso la fine di ottobre ed è stata risolta entro metà novembre.
Per generare questi grafici personalmente, abbiamo creato un esempio Colab. Un Colab, o "Colaboratory", ti consente di scrivere ed eseguire Python dal tuo browser. Il Colab dell'API CrUX History (fonte) utilizza Python per effettuare chiamate all'API e creare grafici dei dati.
Questo Colab ti consente di creare grafici P75 e tribin, ottenere dati in formato tabulare e visualizzare la coppia di richiesta e risposta per l'API CrUX, compilando un breve modulo. Non è necessario essere un programmatore per usarlo, ma sicuramente puoi osservare il codice Python e modificarlo per renderlo incredibile! Divertiti e non esitare a fornire un feedback su ciò che trovi.
Naturalmente, non devi limitarti a Colab o Python e questo è solo un esempio di come usare questa nuova API. Essendo un endpoint HTTP basato su JSON, l'API è interrogabile da qualsiasi tecnologia.
Conclusione
Prima dell'introduzione dell'endpoint API di CrUX History, i proprietari dei siti avevano pochi dati storici che potevano ottenere da CrUX. I dati mensili a livello di origine erano disponibili tramite BigQuery e CrUX Dashboard, ma non erano disponibili dati settimanali né dati storici a livello di pagina. I proprietari dei siti potevano registrare questi dati autonomamente utilizzando l'API giornaliera, ma spesso la necessità di questi dati veniva rilevata solo dopo una regressione delle metriche.
La speranza con l'introduzione di questa API CrUX History è che permetta ai proprietari di siti di avere una migliore comprensione delle metriche mutevoli del sito, nonché di usare uno strumento di diagnostica in caso di problemi. Se utilizzi la nuova API, è gradito ricevere feedback nel gruppo Google relativo ai report sull'esperienza utente di Chrome (Discussioni).
Ringraziamenti
Immagine hero di Dave Herring su Unsplash