API CrUX

L'API CrUX consente l'accesso a bassa latenza a dati aggregati relativi all'esperienza utente reale a livello di granularità della pagina e dell'origine.

Caso d'uso comune

L'API CrUX consente di eseguire query sulle metriche dell'esperienza utente per un URI specifico, come "Recupera 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 di Chrome UX Report API.

Se disponi di una chiave API, l'applicazione può aggiungere il parametro di query key=[YOUR_API_KEY] a tutti gli URL della richiesta. Consulta Esempi di query.

La chiave API è sicura per l'incorporamento negli URL; non è necessaria alcuna codifica.

Modello dei dati

Questa sezione descrive in dettaglio la struttura dei dati nelle richieste e nelle risposte.

Record

Un'informazione discreta su una pagina o un sito. Un record può contenere dati specifici di un identificatore e di una specifica combinazione di dimensioni. Un record può contenere dati per una o più metriche.

Identificatori

Gli identificatori specificano i record da cercare. In CrUX questi identificatori sono pagine web e siti web.

Origine

Quando l'identificatore è un'origine, tutti i dati presenti per tutte le pagine in quell'origine vengono aggregati insieme. Ad esempio, supponiamo che l'origine http://www.example.com abbia delle pagine come indicato da questa Sitemap:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Ciò significa che quando viene eseguita una query nel Report sull'esperienza utente di Chrome con l'origine impostata su http://www.example.com, vengono restituiti i dati relativi a http://www.example.com/, http://www.example.com/foo.html e http://www.example.com/bar.html, in quanto si tratta di tutte pagine appartenenti a quell'origine.

URL

Quando l'identificatore è un URL, vengono restituiti solo i dati relativi a quell'URL specifico. Rivediamo la Sitemap di origine di 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 un gruppo specifico di dati in base a cui viene aggregato un record. Ad esempio, un fattore di forma PHONE indica che il record contiene informazioni sui caricamenti avvenuti su un dispositivo mobile. Ogni dimensione avrà un determinato numero di valori e, implicitamente, la mancanza di specificarne la dimensione fa sì che la dimensione venga aggregata in tutti i valori. Ad esempio, specificare nessun fattore di forma indica che il record contiene informazioni relative a caricamenti avvenuti su qualsiasi fattore di forma.

Fattore di forma

La classe del dispositivo utilizzata dall'utente finale per accedere alla pagina. Questa è una classe generica di dispositivi suddivisa in PHONE, TABLET e DESKTOP.

Tipo di connessione effettivo

Tipo di connessione effettiva indica la qualità di connessione stimata del dispositivo quando si accede alla pagina. Questo è un corso generico suddiviso in offline, slow-2G, 2G, 3G e 4G.

Metrica

Le metriche vengono registrate 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 sono codificate con un doppio come stringa, quindi non vengono considerate numeri in virgola mobile e vengono riportate con 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 intervalli specifici 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 pagina,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 supporremo i millisecondi.

Inoltre, il 49,91% dei caricamenti pagina ha registrato un valore metrica compreso tra 1000 ms e 3000 ms e l'11,92% ha registrato un valore superiore a 3000 ms.

Percentili

Le metriche possono anche contenere percentili che possono essere utili per ulteriori analisi. Registriamo i valori specifici delle metriche al percentile specificato. Si basano sull'insieme completo dei dati disponibili e non sui dati raggruppati finali, quindi non corrispondono necessariamente a un percentile interpolato basato sull'istogramma binnato finale.

{
  "percentiles": {
    "p75": 2063
  }
}

In questo esempio, almeno il 75% dei caricamenti pagina è stato misurato con il valore della metrica <= 2063.

Frazioni

Le frazioni indicano le percentuali di caricamenti pagina che possono essere etichettate in un determinato modo. In questo caso, i valori delle metriche sono queste etichette.

Ad esempio, la metrica form_factors è composta da un oggetto fractions che elenca la suddivisione dei fattori di forma (o dei dispositivi) coperti dalla query:

"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 un telefono, ottenendo il 100% in totale.

Tipi di valori delle metriche

Nome metrica dell'API CrUX Tipo di dati Unità metriche Aggregazioni statistiche Documentazione
cumulative_layout_shift Con 2 cifre decimali doppia codifica come stringa senza unità istogramma con tre bin, percentili con p75 cls
first_contentful_paint int millisecondi istogramma con tre bin, percentili con p75 FCP
first_input_delay
(deprecato)		 int millisecondi istogramma con tre bin, percentili con p75 fid
interaction_to_next_paint int millisecondi istogramma con tre bin, percentili con p75 Inp
largest_contentful_paint int millisecondi istogramma con tre bin, percentili con p75 lcp
experimental_time_to_first_byte int millisecondi istogramma con tre bin, percentili con p75 da ttfb
form_factors Doppia con 4 cifre decimali percentuale mappatura dal fattore di forma alla frazione Fattori di forma
navigation_types Doppia con 4 cifre decimali percentuale mappatura dal tipo di navigazione alla frazione tipi di navigazione
round_trip_time int millisecondi percentili con p75 rtt

Mappatura dei nomi della metrica BigQuery

Nome metrica dell'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
round_trip_time 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
      }
    }

In questo modo è possibile comprendere meglio i dati e sapere se sono stati ancora 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 perché attende i dati completati per il giorno in questione e che richiede un po' di tempo di elaborazione prima che sia disponibile nell'API. Il fuso orario utilizzato è PST (Pacific Standard Time) e non cambia in base all'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, puoi chiamare da curl con la seguente riga di comando (sostituendo API_KEY con la tua 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 nella 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 nella richiesta non è specificato nessun formFactor)

Se non viene fornito alcun valore di formFactor, i valori verranno aggregati per tutti i fattori di forma.

Per altri esempi di query, consulta la sezione Utilizzo dell'API Chrome UX Report.

Pipeline di dati

Il set di dati CrUX viene elaborato attraverso una pipeline per consolidare, aggregare e filtrare i dati prima di diventare disponibile utilizzando l'API.

La media mobile

I dati del report sull'esperienza utente di Chrome sono una media mobile di 28 giorni di metriche aggregate. Ciò significa che i dati presentati in un determinato momento nel Report sull'esperienza utente di Chrome sono effettivamente dati degli ultimi 28 giorni aggregati.

Questo scenario è simile al modo in 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, che viene eseguito ogni giorno secondo il criterio del "best effort".

Schema

Esiste un unico endpoint per l'API CrUX che accetta richieste HTTP POST. L'API restituisce un record che contiene 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

string

Il tipo di connessione effettiva è una dimensione di query che specifica la classe di rete effettiva a cui devono appartenere i dati del record.

Questo campo utilizza i valori ["offline", "slow-2G", "2G", "3G", "4G"] come specificato nella specifica dell'API Network Information

Nota: se non viene specificato alcun tipo di connessione effettiva, verrà restituito un record speciale con dati aggregati su tutti i tipi di connessioni effettive.
formFactor

enum (FormFactor)

Il fattore di forma è una dimensione di query che specifica la classe del dispositivo a cui devono appartenere i dati del record.

In questo campo vengono utilizzati i valori DESKTOP, PHONE o TABLET.

Nota: se non viene specificato alcun fattore di forma, verrà restituito un record speciale con dati aggregati su tutti i fattori di forma.
metrics[]

string

Le metriche da includere nella risposta. Se non viene specificata alcuna metrica, verranno restituite tutte le metriche trovate.

Valori consentiti: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Campo unione url_pattern. url_pattern è l'identificatore principale per una ricerca di record. Può essere solo uno dei seguenti:
origin

string

L'"origine" url_pattern fa riferimento a un pattern URL che rappresenta l'origine di un sito web.

Esempi: "https://example.com", "https://cloud.google.com"
url

string

url_pattern url si riferisce a un pattern URL che può essere qualsiasi URL arbitrario.

Esempi: "https://example.com/, https://cloud.google.com/why-google-cloud/"

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 riuscite 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 unico.

{
  "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

enum (FormFactor)

Il fattore di forma è la classe del dispositivo utilizzata da tutti gli utenti per accedere al sito in questo record.

Se il fattore di forma non è specificato, verranno restituiti i dati aggregati di tutti i fattori di forma.
effectiveConnectionType

string

Il tipo di connessione effettivo è la classe di connessione generale che tutti gli utenti hanno riscontrato per questo record. Questo campo utilizza i valori ["offline", "slow-2G", "2G", "3G", "4G"] come specificato in: https://wicg.github.io/netinfo/#effective-connection-types

Se il tipo di connessione effettiva non è specificato, verranno restituiti i dati aggregati di tutti i tipi di connessione effettiva.
Campo unione url_pattern. Il pattern URL è l'URL a cui si applica il record. url_pattern può essere solo uno dei seguenti:
origin

string

origin specifica l'origine a cui è destinato questo record.

Nota: quando specifichi un valore origin, i dati per i caricamenti in questa origine su tutte le pagine vengono aggregati in dati sull'esperienza utente a livello di origine.
url

string

url specifica un URL specifico a cui si riferisce questo record.

Nota: quando specifichi un valore url, verranno aggregati solo i dati relativi a quell'URL specifico.

Metriche

Un metric è un insieme di dati aggregati sull'esperienza utente per una singola metrica delle prestazioni sul web, ad esempio First Contentful Paint. Potrebbe contenere un istogramma di riepilogo dell'utilizzo di Chrome nel mondo reale sotto forma di una serie di bins o dati percentili specifici (ad esempio p75) oppure contenere frazioni etichettate.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

o

{
  "fractions": {
    object (Fractions)
  }
}
Campi
histogram[]

object (Bin)

L'istogramma delle esperienze utente per una metrica. L'istogramma avrà almeno una fascia e la densità di tutte le fasce sarà pari a ~1.
percentiles

object (Percentiles)

Percentili utili comuni della metrica. Il tipo di valore per i percentili sarà lo stesso dei tipi di valori specificati per le fasce degli istogrammi.
fractions

object (Fractions)

Questo oggetto contiene frazioni etichettate, che sommano fino a ~1.

Le frazioni vengono arrotondate a quattro cifre decimali.

Bin

Un bin è una porzione discreta di dati che si estende dall'inizio alla fine o se non è specificata una fine dall'inizio all'infinito positivo.

I valori di inizio e fine di una fascia sono indicati nel tipo di valore della metrica che rappresenta. Ad esempio, la First Contentful Paint viene misurata in millisecondi ed esposta come int. Di conseguenza, i bin delle metriche utilizzeranno int32s per i tipi di inizio e fine. Tuttavia, la variazione del layout cumulativa viene misurata in decimali senza unità ed è esposta come un numero decimale codificato come stringa, pertanto i bin delle metriche utilizzeranno le stringhe per il tipo di valore.

{
  "start": value,
  "end": value,
  "density": number
}
Campi
start

(integer | string)

"Inizio" indica l'inizio del contenitore dati.
end

(integer | string)

"Fine" indica la fine del contenitore dati. Se il campo end non è compilato, il contenitore non ha una fine ed è valido dall'inizio a +inf.
density

number

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. Vengono utilizzati per stimare il valore di una metrica in base a una percentuale di utenti rispetto al numero totale di utenti.

{
  "P75": value
}
Campi
p75

(integer | string)

Il 75% dei caricamenti pagine ha riscontrato una metrica specificata pari o inferiore a questo valore.

Frazioni

Fractions contiene frazioni etichettate che sommano fino a ~1. Ogni etichetta descrive in qualche modo un caricamento pagina, quindi le metriche rappresentate in questo modo possono essere considerate come la produzione di valori distinti invece di valori numerici e le frazioni esprimono la frequenza con cui un particolare valore distinto è stato misurato.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Proprio come i valori di densità nelle fascette di istogrammi, ogni fraction è un numero 0.0 <= value <= 1.0 e la somma è ~1, 0.

UrlNormalization

Oggetto che rappresenta le azioni di normalizzazione intraprese per normalizzare un URL e aumentare le probabilità di riuscita della ricerca. Si tratta di semplici modifiche automatiche che vengono apportate quando si cerca l'elemento url_pattern fornito potrebbe non riuscire. Le azioni complesse come i seguenti reindirizzamenti non vengono gestite.

{
  "originalUrl": string,
  "normalizedUrl": string
}
Campi
originalUrl

string

L'URL richiesto originale prima di qualsiasi azione di normalizzazione.
normalizedUrl

string

L'URL dopo qualsiasi azione di normalizzazione. Questo è 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, che sono offerte senza costi. Questo limite e l'utilizzo attuale possono essere visualizzati nella console Google Cloud. Questa quota generosa dovrebbe essere sufficiente per la maggior parte dei casi d'uso e non è possibile pagare per un aumento della quota.