L'API CrUX History fornisce un accesso a bassa latenza a sei mesi di dati storici dell'esperienza utente reale con la granularità di pagina e origine.
Caso d'uso comune
L'API CrUX History consente di eseguire query sulle metriche storiche dell'esperienza utente per un URI specifico, ad esempio "Visualizza le tendenze UX storiche per l'origine https://example.com".
L'API History segue la stessa struttura dell'API CrUX giornaliera, tranne per il fatto che i valori sono forniti in un array e le chiavi sono etichettate con nomi plurali (ad esempio, histogramTimeseries anziché histogram o p75s anziché p75).
Chiave API CrUX
Come l'API giornaliera, l'utilizzo dell'API CrUX History richiede una chiave API Google Cloud. La stessa chiave può essere utilizzata per l'API giornaliera e per la cronologia.
Puoi crearne una nella pagina Credenziali ed eseguirne il provisioning per l'utilizzo in Chrome UX Report API.
Una volta che disponi di una chiave API, la tua applicazione può aggiungere il parametro di query key=[YOUR_API_KEY] a tutti gli URL delle richieste. Consulta Esempi di query.
La chiave API è sicura per l'incorporamento negli URL, non richiede alcuna codifica.
Modello dei dati
Questa sezione descrive in dettaglio la struttura dei dati nelle richieste e nelle risposte.
Registra
Un'informazione discreta su una pagina o un sito. Un record può contenere dati specifici per un identificatore e per una specifica combinazione di dimensioni. Un record può contenere dati per una o più metriche.
Identificatori
Gli identificatori specificano i record che devono essere cercati. In CrUX, questi identificatori sono pagine web e siti web.
Origin
Quando l'identificatore è un'origine, tutti i dati presenti per tutte le pagine in quell'origine vengono aggregati. Ad esempio, supponiamo che l'origine http://www.example.com avesse pagine come previsto da questa Sitemap:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Ciò significa che quando esegui una query sul Report sull'esperienza utente di Chrome con l'origine impostata su http://www.example.com, verranno restituiti i dati relativi a http://www.example.com/, http://www.example.com/foo.html e http://www.example.com/bar.html, aggregati, perché si tratta di tutte le pagine di quell'origine.
URL
Se l'identificatore è un URL, verranno restituiti solo i dati relativi all'URL in questione. Vediamo di nuovo la Sitemap di origine http://www.example.com:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Se l'identificatore è impostato su URL con il valore http://www.example.com/foo.html, verranno restituiti solo i dati per quella pagina.
Dimensioni
Le dimensioni identificano uno specifico gruppo di dati in base al quale viene aggregato un record. Ad esempio, un fattore di forma PHONE indica che il record contiene informazioni relative ai caricamenti eseguiti su un dispositivo mobile.
L'API CrUX History è disponibile solo aggregata per dimensione del fattore di forma. Questa è una classe generale di dispositivi suddivisa in PHONE, TABLET e DESKTOP.
Metrica
Registriamo le metriche in serie temporali delle aggregazioni statistiche, ovvero istogrammi, percentili e frazioni.
Istogrammi
Quando le metriche vengono espresse in un array a istogrammi, ogni voce della serie temporale rappresenta la percentuale di caricamenti pagina per cui la metrica rientra in un intervallo, in modo proporzionale a tutti. I punti dati vengono presentati nell'ordine delle date del periodo di raccolta restituite dall'API: il primo punto corrisponde al periodo di raccolta più recente e il punto finale al periodo di raccolta più recente.
Un semplice istogramma a tre bin per una metrica di esempio ha il seguente aspetto:
{
"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]
}
],
}
Questi dati indicano che il 91,90% dei caricamenti di pagine ha registrato il valore metrica di esempio compreso tra 0 ms e 2500 ms per il primo periodo di raccolta nella storia, seguito da 92,03%, 91,94%... Le unità della metrica non sono contenute in questo istogramma, in questo caso supporremo i millisecondi.
Inoltre, il 5,21% dei caricamenti pagine ha registrato un valore della metrica di esempio compreso tra 2500 ms e 4000 ms nel primo periodo di raccolta nella storia e il 2,88% dei caricamenti pagina ha registrato un valore superiore a 4000 ms nel primo periodo di raccolta della storia.
Percentili
Le metriche possono anche contenere serie temporali di percentili che possono essere utili per ulteriori analisi.
I punti dati vengono presentati nell'ordine delle date del periodo di raccolta restituite dall'API: il primo punto corrisponde al periodo di raccolta più recente e il punto finale al periodo di raccolta più recente.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Questi percentili possono mostrare valori specifici della metrica nel percentile specificato per quella metrica. Questi si basano sul set completo di dati disponibili e non sui dati di binding finali, quindi non corrispondono necessariamente a un percentile interpolato basato sull'istogramma finale della bind.
Frazioni
Le metriche possono essere espresse come serie temporali di frazioni etichettate; ogni etichetta descrive un caricamento pagina in un determinato modo. I punti dati vengono presentati nell'ordine delle date del periodo di raccolta restituite dall'API: il primo punto corrisponde al periodo di raccolta più recente e il punto finale al periodo di raccolta più recente.
Esempio:
{
"fractionTimeseries": {
"desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
"phone": {"fractions": [0.6295, 0.7544, 0.8288]},
"tablet": {"fractions": [0.051, 0.0341, 0.029]}
}
}
In questo esempio, il punto dati più recente indica che il 14,21% dei caricamenti delle pagine proveniva da computer e l'82,88% da telefoni.
Tipi di valori delle metriche
Poiché l'API CrUX History utilizza gli stessi tipi di valori delle metriche, puoi consultare la documentazione giornaliera sui tipi di valori delle metriche dell'API CrUX per ulteriori dettagli.
Idoneità delle metriche
In base ai criteri di idoneità, un'origine o un URL potrebbero essere idonei solo per alcuni dei periodi di raccolta coperti dall'API CrUX History. In questi casi, l'API CrUX History restituirà "NaN" per le densità histogramTimeseries e null per percentilesTimeseries per i periodi di raccolta per i quali non sono disponibili dati idonei. 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).
Ad esempio, se il secondo periodo non contiene dati idonei, viene visualizzato come segue:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
}
],
"percentilesTimeseries": {
"p75s": [1362, null, 1344, 1356, 1366, 1377]
},
}
Per gli URL o le origini che rientrano e non rientrano nell'idoneità nel tempo, potresti notare molte voci mancanti.
Periodi di raccolta
L'API CrUX History contiene un oggetto collectionPeriods con un array di campi firstDate e endDate che rappresentano le date di inizio e di fine di ogni finestra di aggregazione. Ad esempio:
"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 }
}
]
Questi periodi di raccolta sono in ordine crescente e rappresentano l'intervallo di date di ciascuno dei punti dati nelle altre sezioni della risposta.
L'API History viene aggiornata ogni lunedì e contiene dati fino al sabato precedente (in base al ritardo standard di 2 giorni). Contiene i dati delle 25 settimane precedenti, un periodo di raccolta per settimana.
Poiché ogni periodo di raccolta contiene i dati aggregati dei 28 giorni precedenti e i periodi di raccolta sono settimanali, i periodi di raccolta si sovrapporranno. Sono simili a una media mobile dei dati, con dati di tre settimane inclusi in ogni periodo successivo e una settimana diversa.
Esempi di query
Le query vengono inviate come oggetti JSON utilizzando una richiesta POST a https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" con i dati delle query come oggetto JSON nel corpo POST.
Nota l'utilizzo di queryHistoryRecord che sostituisce il queryRecord dell'API CrUX giornaliera.
Un corpo di esempio è:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Ad esempio, questa chiamata può essere chiamata da curl con la seguente riga di comando (sostituendo API_KEY con la chiave):
curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'
I dati a livello di pagina sono disponibili tramite l'API passando una proprietà url alla query, anziché origin:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Se la proprietà metrics non è impostata, verranno restituite tutte le metriche disponibili:
cumulative_layout_shiftfirst_contentful_paintfirst_input_delayinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesform_factors(segnalato solo se non viene specificato alcunformFactornella richiesta)
Se non viene fornito alcun valore formFactor, i valori verranno aggregati per tutti i fattori di forma.
Per altri esempi di query, consulta la guida sull'utilizzo dell'API CrUX History.
Pipeline di dati
Il set di dati CrUX viene elaborato tramite una pipeline per consolidare, aggregare e filtrare i dati prima di essere resi disponibili tramite l'API.
La media mobile
I dati contenuti nel report sull'esperienza utente di Chrome rappresentano una media mobile di 28 giorni di metriche aggregate. Ciò significa che i dati presentati nel report sull'esperienza utente di Chrome in un determinato momento sono in realtà dati degli ultimi 28 giorni aggregati.
L'API History contiene una serie di periodi di raccolta, ciascuno dei quali comprende i 28 giorni. Poiché ogni periodo di raccolta contiene i dati aggregati dei 28 giorni precedenti e i periodi di raccolta sono settimanali, i periodi di raccolta si sovrapporranno. Sono simili a una media mobile dei dati, con dati di tre settimane inclusi in ogni periodo successivo e una settimana diversa.
Aggiornamenti settimanali
L'API History viene aggiornata ogni lunedì intorno alle 04:00 UTC e contiene dati fino al sabato precedente (in base al ritardo standard di 2 giorni). Contiene i dati delle 25 settimane precedenti (circa 6 mesi), un periodo di raccolta alla settimana.
Non esiste un accordo sul livello del servizio per i tempi di aggiornamento; l'aggiornamento viene eseguito ogni giorno secondo il criterio del "best effort".
Schema
Esiste un unico endpoint per l'API CrUX History che accetta le richieste HTTP POST. L'API restituisce un record contenente uno o più metrics corrispondenti ai dati sulle prestazioni dell'origine o della pagina richiesta.
Richiesta HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord
L'URL utilizza la sintassi di transcodifica gRPC.
Corpo della richiesta
L'API CrUX History utilizza gli stessi corpi delle richieste dell'API CrUX giornaliera, ad eccezione del fatto che non supporta il campo della richiesta effectiveConnectionType.
Ad esempio, per richiedere i valori Largest Contentful Paint per desktop per la home page web.dev:
{
"origin": "https://web.dev/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Corpo della risposta
Le richieste andate a buon fine restituiscono risposte con un oggetto record e urlNormalizationDetails nella seguente struttura:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Ad esempio, la risposta al corpo della richiesta nella richiesta precedente potrebbe essere:
{
"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 }
}, {
...
}
]
}
}
Chiave
Key definisce tutte le dimensioni che identificano questo record come univoco.
{
"formFactor": enum (FormFactor),
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
| Campi | |
|---|---|
formFactor |
Il fattore di forma è la classe del dispositivo utilizzata da tutti gli utenti per accedere al sito per questo record. Se il fattore di forma non è specificato, verranno restituiti i dati aggregati su tutti i fattori di forma. |
Campo di unione url_. Il pattern URL è l'URL a cui si applica il record. url_ può essere solo uno dei seguenti: |
|
origin |
L'origine specifica l'origine a cui è destinato questo record. Nota: quando specifichi un'origine, i dati per i caricamenti in questa origine su tutte le pagine vengono aggregati in dati relativi all'esperienza utente a livello di origine. |
url |
Nota: quando specifichi un valore |
Metriche
Un metric è un insieme di dati relativi all'esperienza utente per una singola metrica di rendimento sul web, ad esempio First Contentful Paint. Contiene un istogramma riepilogativo dell'utilizzo reale di Chrome sotto forma di serie di bins.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
o
"fractionTimeseries": {
object (Fractions)
}
| Campi | |
|---|---|
histogramTimeseries[] |
Istogramma con serie temporale delle esperienze utente per una metrica. L'istogramma con serie temporale avrà almeno una fascia e le densità di tutte le fasce verranno sommate fino a circa 1. I valori mancanti per quel determinato periodo di raccolta verranno contrassegnati come |
percentilesTimeseries |
Percentili utili comuni della metrica. Il tipo di valore dei percentili sarà lo stesso dei tipi di valori specificati per le fasce a istogrammi. I valori mancanti per quel determinato periodo di raccolta verranno contrassegnati come |
fractionTimeseries |
Questo oggetto contiene serie temporali di frazioni etichettate, che sommano fino a 1 voce per voce. Le frazioni vengono arrotondate a quattro cifre decimali. Le voci mancanti sono espresse come ""NaN"" in tutte le frazioni. |
Bin
Un bin è una parte discreta di dati che si estende dall'inizio alla fine o se non viene indicata alcuna fine dall'inizio all'infinito positivo.
I valori iniziale e finale di un bin vengono indicati nel tipo di valore della metrica che rappresenta. Ad esempio, la prima visualizzazione con contenuti viene misurata in millisecondi ed è esposta come int, pertanto le relative sezioni metriche utilizzeranno int32s per i tipi di inizio e fine. Tuttavia, lo spostamento cumulativo del layout viene misurato in decimali senza unità ed è esposto come decimale codificato come stringa, pertanto le relative sezioni delle metriche utilizzeranno le stringhe per il tipo di valore.
{
"start": value,
"end": value,
"densities": [number, number, number...etc.]
}
| Campi | |
|---|---|
start |
"Start" indica l'inizio della fascia dati. |
end |
"End" indica la fine del contenitore di dati. Se la fine non è compilata, il bin non ha fine ed è valido dall'inizio al +inf. |
densities |
Una serie temporale della proporzione di utenti che hanno riscontrato il valore di questa fascia per la metrica specificata. Le densità vengono arrotondate a quattro cifre decimali. |
Percentili
Percentiles contiene valori sintetici di una metrica in un determinato percentile statistico. Questi vengono utilizzati per stimare il valore di una metrica ottenuto da una percentuale di utenti sul numero totale di utenti.
{
"P75": value
}
| Campi | |
|---|---|
p75s |
Serie temporali dei valori per cui il 75% dei caricamenti pagina ha riscontrato la metrica specificata con un valore pari o inferiore a questo valore. |
Frazioni
Fractions contiene serie temporali di frazioni etichettate che sommano fino a 1 voce per voce.
Ogni etichetta descrive in qualche modo un caricamento pagina; pertanto, le metriche rappresentate in questo modo possono essere considerate come valori distinti anziché valori numerici. Le frazioni esprimono la frequenza con cui è stato misurato un determinato valore distinto.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Proprio come i valori di densità nelle barre degli istogrammi, ogni fraction è un numero
0.0 <= value <= 1.0 e la somma dei valori è ~1, 0. Quando la metrica non è disponibile per un determinato periodo di raccolta, la voce corrispondente sarà "NaN" in tutti gli array di frazioni.
| Campi | |
|---|---|
p75s |
Serie temporali dei valori per cui il 75% dei caricamenti pagina ha riscontrato la metrica specificata con un valore pari o inferiore a questo valore. |
UrlNormalization
Oggetto che rappresenta le azioni di normalizzazione intraprese per normalizzare un URL in modo da avere maggiori probabilità di successo della ricerca. Si tratta di semplici modifiche automatiche apportate durante la ricerca del url_pattern fornito di cui è noto che non hanno avuto esito positivo. Le azioni complesse come i seguenti reindirizzamenti non vengono gestite.
{
"originalUrl": string,
"normalizedUrl": string
}
| Campi | |
|---|---|
originalUrl |
L'URL richiesto originale prima di qualsiasi azione di normalizzazione. |
normalizedUrl |
L'URL dopo qualsiasi azione di normalizzazione. Si tratta di un URL valido per l'esperienza utente che potrebbe essere ragionevolmente cercato. |
Limiti di frequenza
L'API CrUX History condivide lo stesso limite con l'API CrUX per 150 query al minuto per progetto Google Cloud per entrambe le API, che vengono offerte senza costi. Questo limite e il tuo utilizzo attuale sono disponibili in Google Cloud Console. Questa generosa quota dovrebbe essere sufficiente per la stragrande maggioranza dei casi d'uso e non è possibile pagare per un aumento della quota.