Questa guida illustra l'endpoint dell'API History del Report sull'esperienza utente di Chrome (CrUX), che fornisce serie temporali di dati sul rendimento web. Questi dati vengono aggiornati settimanalmente e ti consentono di visualizzare una cronologia di circa 6 mesi, con 25 punti dati distanziati per una settimana.
Se utilizzato con gli aggiornamenti giornalieri dell'endpoint dell'API CrUX originale, ora puoi visualizzare rapidamente sia i dati più recenti sia ciò che è accaduto in precedenza, rendendolo uno strumento efficace per vedere le modifiche delle pagine web nel tempo.
Prova l'API in questa pagina
Esegui query sull'API CrUX giornaliera
Per riepilogare quanto descritto in un articolo precedente sull'API CrUX, puoi ottenere uno snapshot dei dati di campo 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à dell'istogramma e i valori percentile per un determinato periodo di raccolta di 28 giorni, in questo caso dal 27 dicembre 2022 al 23 gennaio 2023.
Esegui query sull'API CrUX History
Per chiamare l'endpoint della cronologia, modifica queryRecord nell'URL in queryHistoryRecord nel comando curl. Puoi 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. Anziché un singolo punto dati, ora sono disponibili serie temporali per i campi contenenti il 75° percentile (p75) e i 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 LCP (Largest Contentful Paint) è [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, dall'interpretazione delle ultime voci della serie temporale nell'esempio per https://web.dev è emerso 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% aveva valori compresi tra 2500 ms e 4000 ms e il 2,85% aveva valori superiori a 4000 ms.
Allo stesso modo, esiste una serie temporale per i valori p75: il valore p75 LCP dal 14 agosto 2022 al 10 settembre 2022 è stato 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 sei 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, questo riguarda 6 mesi.
In una determinata risposta, la lunghezza della serie temporale per le densità dei bin dell'istogramma e per i valori p75 sarà esattamente uguale alla lunghezza dell'array nel campo collectionPeriods: esiste una corrispondenza uno a uno in base all'indice in questi array.
Esegui 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. Sebbene i dati a livello di origine fossero disponibili in precedenza utilizzando il set di dati CrUX su BigQuery (o la dashboard 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 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, i dati "mancanti" saranno rappresentati da "NaN" per le densità histogramTimeseries e da null per percentilesTimeseries. La ragione della differenza è che le densità dell'istogramma sono sempre numeri, mentre i percentile possono essere numeri o stringhe (CLS utilizza stringhe, anche se sembrano numeri).
Visualizzare i dati
Potresti chiederti perché i dati sono strutturati in questo modo. È emerso che ciò rende più facile la traccia dei grafici. Ad esempio, di seguito è riportato un grafico dei 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, 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 p75 fornisce una panoramica rapida 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 intervalli fornisce 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 effettivamente scarso. In entrambi i grafici è relativamente facile dedurre che si è verificata una regressione del rendimento che ha avuto inizio verso la fine di ottobre ed è stata corretta entro la metà di novembre.
Per generare questi grafici autonomamente, abbiamo creato un Colab di esempio. Un Colab, o "Colaboratory", ti consente di scrivere ed eseguire Python dal browser. Colab dell'API CrUX History (source) utilizza Python per effettuare chiamate all'API e creare grafici dei dati.
Questo Colab ti consente di creare grafici p75, grafici a tre intervalli, 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 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 di siti potevano ottenere informazioni storiche limitate 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 questi dati autonomamente utilizzando l'API giornaliera, ma spesso la necessità di farlo era stata scoperta solo dopo una regressione delle metriche.
L'introduzione di questa API CrUX History dovrebbe consentire ai proprietari di siti di comprendere meglio le metriche in evoluzione del loro sito e di utilizzarla come strumento di diagnostica in caso di problemi. Se utilizzi la nuova API, puoi inviare un feedback nel gruppo Google Chrome UX Report (Discussions).
Ringraziamenti
Immagine hero di Dave Herring su Unsplash