L'API CrUX consente l'accesso a bassa latenza a dati aggregati sull'esperienza utente reale con la granularità di pagina e origine.
Caso d'uso comune
L'API CrUX consente di eseguire query sulle metriche dell'esperienza utente per un URI specifico, ad esempio "Ottieni metriche per l'origine https://example.com
".
Chiave API CrUX
L'utilizzo dell'API CrUX richiede una chiave API Google Cloud. 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 avvenuti su un dispositivo mobile. Ogni dimensione avrà un determinato numero di valori e, implicitamente, la mancanza di una specifica dimensione significa che la dimensione verrà aggregata per tutti i valori. Ad esempio, se non specifichi nessun fattore di forma, il record contiene informazioni sui caricamenti eseguiti su qualsiasi fattore di forma.
Fattore di forma
La classe del dispositivo utilizzata dall'utente finale per accedere alla pagina. Questa è una classe generale di dispositivi suddivisa in PHONE
, TABLET
e DESKTOP
.
Tipo di connessione effettiva
Il tipo di connessione effettivo indica la qualità di connessione stimata del dispositivo quando si accede alla pagina. Questo è un corso generico diviso in offline
, slow-2G
, 2G
, 3G
e 4G
.
Metrica
Registriamo le metriche come aggregazioni statistiche, in istogrammi, percentili e frazioni.
I valori con virgola mobile vengono arrotondati a quattro cifre decimali (tieni presente che le metriche cumulative_layout_shift
vengono codificate due volte come stringa, quindi non vengono considerate valori in virgola mobile e vengono segnalate a due cifre decimali all'interno della stringa).
Istogramma
Quando le metriche sono espresse in un istogramma, mostriamo le percentuali di caricamenti pagina che rientrano in determinati intervalli per quella metrica.
Un semplice istogramma a tre bin per una metrica di esempio ha il seguente aspetto:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
Questi dati indicano che per il 38, 18% dei caricamenti delle pagine,la metrica di esempio è stata misurata tra 0 ms e 1000 ms. Le unità della metrica non sono contenute in questo istogramma. In questo caso, faremo riferimento ai millisecondi.
Inoltre, il 49,91% dei caricamenti di pagine ha registrato un valore della metrica compreso tra 1000 ms e 3000 ms, mentre l'11,92% ha registrato un valore superiore a 3000 ms.
Percentili
Le metriche possono anche contenere percentili utili per ulteriori analisi. Registriamo valori specifici di metriche al percentile specificato per quella metrica. Si basano sul set completo di dati disponibili e non sui dati binding finali, perciò non corrispondono necessariamente a un percentile interpolato basato sull'istogramma finale del binding.
{
"percentiles": {
"p75": 2063
}
}
In questo esempio, è stato misurato almeno il 75% dei caricamenti delle pagine con un valore metrica <= 2063
.
Frazioni
Le frazioni indicano le percentuali di caricamenti pagina che possono essere etichettate in un determinato modo. In questo caso, i valori della metrica sono queste etichette.
Ad esempio, la metrica form_factors
è composta da un oggetto fractions
che elenca la suddivisione dei fattori di forma (o dispositivi) relativa alla query in questione:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
In questo caso, il 3,77% dei caricamenti pagina è stato misurato su un computer, il 2,88% su un tablet e il 93,35% su uno smartphone, per un totale del 100%.
Tipi di valori delle metriche
Nome metrica API CrUX | Tipo di dati | Unità metriche | Aggregazioni statistiche | Documentazione |
---|---|---|---|---|
cumulative_layout_shift |
Due cifre decimali codificate come stringa | senza unità | istogramma con tre fasce, percentili con p75 | cls |
first_contentful_paint |
int | millisecondi | istogramma con tre fasce, percentili con p75 | FCP |
first_input_delay (deprecato) |
int | millisecondi | istogramma con tre fasce, percentili con p75 | fiducia |
interaction_to_next_paint |
int | millisecondi | istogramma con tre fasce, percentili con p75 | inp |
largest_contentful_paint |
int | millisecondi | istogramma con tre fasce, percentili con p75 | lcp |
experimental_time_to_first_byte |
int | millisecondi | istogramma con tre fasce, percentili con p75 | ttfb |
form_factors |
Doppia posizione con quattro decimali | percentuale | mappatura dal fattore di forma alla frazione | Fattori di forma |
navigation_types |
Doppia posizione con quattro decimali | percentuale | mappatura dal tipo di navigazione alla frazione | tipi di navigazione |
Mappatura dei nomi delle metriche BigQuery
Nome metrica API CrUX | Nome metrica BigQuery |
---|---|
cumulative_layout_shift |
layout_instability.cumulative_layout_shift |
first_contentful_paint |
first_contentful_paint |
first_input_delay |
first_input.delay |
interaction_to_next_paint |
interaction_to_next_paint |
largest_contentful_paint |
largest_contentful_paint |
experimental_time_to_first_byte |
experimental.time_to_first_byte |
navigation_types |
navigation_types |
form_factors |
n/d |
Periodo di raccolta
A partire da ottobre 2022, l'API CrUX contiene un oggetto collectionPeriod
con i campi firstDate
e endDate
che rappresentano le date di inizio e di fine della finestra di aggregazione. Ad esempio:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
Ciò consente di comprendere meglio i dati e se sono già stati aggiornati per quel giorno o se restituiscono gli stessi dati di ieri.
Tieni presente che l'API CrUX è indietro di circa due giorni rispetto alla data odierna, poiché attende i dati completati per il giorno corrente e richiede un po' di tempo di elaborazione prima che sia disponibile nell'API. Il fuso orario utilizzato è il fuso orario PST (Pacific Standard Time), che non cambia per l'ora legale.
Esempi di query
Le query vengono inviate come oggetti JSON utilizzando una richiesta POST a https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
con i dati delle query come oggetto JSON nel corpo POST:
{
"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:queryRecord?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_shift
first_contentful_paint
first_input_delay
(deprecato)interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(segnalato solo se non viene specificato alcunformFactor
nella richiesta)
Se non viene fornito alcun valore formFactor
, i valori verranno aggregati per tutti i fattori di forma.
Per altri esempi di query, consulta Utilizzare l'API Chrome UX Report.
Pipeline di dati
Il set di dati CrUX viene elaborato tramite una pipeline per consolidare, aggregare e filtrare i dati prima di diventare disponibile utilizzando 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.
La procedura è simile a quella con cui il set di dati CrUX su BigQuery aggrega i report mensili.
Aggiornamenti giornalieri
I dati vengono aggiornati ogni giorno intorno alle 04:00 UTC. 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 singolo endpoint per l'API CrUX 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:queryRecord
L'URL utilizza la sintassi di transcodifica gRPC.
Corpo della richiesta
Il corpo della richiesta deve contenere dati con la seguente struttura:
{
"effectiveConnectionType": string,
"formFactor": enum (FormFactor),
"metrics": [
string
],
// 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 | |
---|---|
effectiveConnectionType |
Il tipo di connessione effettivo è una dimensione della query che specifica la classe di rete effettiva a cui devono appartenere i dati del record. Questo campo utilizza i valori Nota: se non viene specificato alcun tipo di connessione effettivo, verrà restituito un record speciale con dati aggregati su tutti i tipi di connessione effettivi. |
formFactor |
Il fattore di forma è una dimensione della query che specifica la classe del dispositivo a cui devono appartenere i dati del record. Questo campo utilizza i valori Nota: se non viene specificato alcun fattore di forma, verrà restituito un record speciale con dati aggregati su tutti i fattori di forma. |
metrics[] |
Le metriche da includere nella risposta. Se non viene specificata alcuna metrica, verranno restituite le metriche trovate. Valori consentiti: |
Campo di unione url_ . url_pattern è l'identificatore principale per una ricerca di record. Può essere uno solo dei seguenti valori: |
|
origin |
L'"origine" di Esempi: |
url |
Il Esempi: |
Ad esempio, per richiedere i valori di visualizzazione con contenuti più grandi del desktop per la home page della documentazione per gli sviluppatori di Chrome:
{
"url": "https://developer.chrome.com/docs/",
"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": {
"formFactor": "DESKTOP",
"url": "https://developer.chrome.com/docs/"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.9815
},
{
"start": 2500,
"end": 4000,
"density": 0.0108
},
{
"start": 4000,
"density": 0.0077
}
],
"percentiles": {
"p75": 651
}
}
},
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
}
}
Chiave
Key
definisce tutte le dimensioni che identificano questo record come univoco.
{
"effectiveConnectionType": string,
"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. |
effectiveConnectionType |
Il tipo di connessione effettiva è la classe di connessione generale utilizzata da tutti gli utenti per questo record. Questo campo utilizza i valori ["offline", "slow-2G", "2G", "3G", "4G"] come specificati in: https://wicg.github.io/netinfo/#effective-connection-types Se il tipo di connessione effettiva non è specificato, verranno restituiti dati aggregati su tutti i tipi di connessione effettivi. |
Campo di unione url_ . Il pattern URL è l'URL a cui si applica il record. url_ può essere solo uno dei seguenti: |
|
origin |
Nota: quando specifichi un valore |
url |
Nota: quando specifichi un valore |
Metriche
Un metric
è un insieme di dati aggregati relativi all'esperienza utente per una singola metrica di rendimento sul web, ad esempio First Contentful Paint.
Potrebbe contenere un istogramma riepilogativo dell'utilizzo reale di Chrome come una serie di bins
, dati di percentile specifici (come p75) oppure frazioni etichettate.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
o
{
"fractions": {
object (Fractions)
}
}
Campi | |
---|---|
histogram[] |
L'istogramma delle esperienze utente per una metrica. L'istogramma avrà almeno una fascia e le densità di tutte le fasce verranno sommate fino a circa 1. |
percentiles |
Percentili utili comuni della metrica. Il tipo di valore dei percentili sarà lo stesso dei tipi di valori specificati per le fasce a istogrammi. |
fractions |
Questo oggetto contiene frazioni etichettate, che sommano circa 1. Le frazioni vengono arrotondate a quattro cifre decimali. |
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,
"density": number
}
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. |
density |
La 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 | |
---|---|
p75 |
Il 75% dei caricamenti pagina ha riscontrato una metrica specifica corrispondente o inferiore a questo valore. |
Frazioni
Fractions
contiene frazioni etichettate che sommano circa 1. Ogni etichetta descrive in qualche modo un carico di pagina, pertanto le metriche rappresentate in questo modo possono essere considerate come la produzione di valori distinti anziché valori numerici e le frazioni esprimono la frequenza con cui è stato misurato un particolare valore distinto.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": 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.
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 è limitata a 150 query al minuto per progetto Google Cloud, offerta 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.