API CrUX

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.

Nota: i valori per ciascun percentile sono derivati sinteticamente. Ciò non implica che alcun utente abbia effettivamente riscontrato il valore indicato, ma solo che una certa percentuale di caricamenti pagina ha riscontrato un valore metrica inferiore al valore specificato.

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

Nota: in CrUX BigQuery, le densità degli istogrammi vengono sommate fino al 100% per origine nei vari fattori di forma, pertanto la metrica form_factors supportata nell'API viene invece espressa come densità a istogrammi per first_contentful_paint.

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"]}'

Nota: l'esempio precedente riguarda i sistemi basati su macOS o Linux, inclusa la shell Git BASH per Windows. Altri sistemi potrebbero richiedere leggere modifiche. Ad esempio, la riga di comando cmd.exe non consente le virgolette singole per i parametri, né le continuazioni di riga (\), quindi richiede l'uso delle virgolette doppie (utilizzando le virgolette interne, se necessario con \"), e anche di utilizzare una singola riga.

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 alcun formFactor 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".

Attenzione: i dati non subiranno variazioni nello stesso giorno dopo l'aggiornamento intorno alle 04:00 UTC; le chiamate ripetute produrranno gli stessi risultati.

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	string 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 ["offline", "slow-2G", "2G", "3G", "4G"] come specificato nella specifica dell'API Network Information 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	enum (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 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 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 di unione url_pattern. url_pattern è l'identificatore principale per una ricerca di record. Può essere uno solo dei seguenti valori:
origin	string L'"origine" di url_pattern si riferisce a un pattern URL che è l'origine di un sito web. Esempi: "https://example.com", "https://cloud.google.com"
url	string Il url url_pattern si riferisce a un pattern URL che è 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 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	enum (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	string 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_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 relativi all'esperienza utente a livello di origine.
url	string url specifica un URL specifico a cui è destinato questo record. Nota: quando specifichi un valore url, verranno aggregati solo i dati per quell'URL specifico.

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[]	object (Bin) 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	object (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	object (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	(integer | string) "Start" indica l'inizio della fascia dati.
end	(integer | string) "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	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. 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	(integer | string) 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	string L'URL richiesto originale prima di qualsiasi azione di normalizzazione.
normalizedUrl	string 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.