API CrUX

L'API CrUX fornisce un accesso a bassa latenza ai dati aggregati sull'esperienza utente reale con granularità a livello di pagina e origine.

Fai una prova!

Caso d'uso comune

L'API CrUX consente di eseguire query sulle metriche relative all'esperienza utente per un URI specifico, ad esempio "Ottieni metriche per l'origine https://example.com".

Chiave API CrUX

Per utilizzare l'API CrUX è necessaria una chiave API Google Cloud di cui è stato eseguito il provisioning per l'utilizzo di Chrome UX Report API.

Acquisizione e utilizzo di una chiave API

In alternativa, creane una nella pagina Credenziali.

Una volta ottenuta una chiave API, la tua applicazione può aggiungere il parametro di query key=yourAPIKey a tutti gli URL di richiesta.

La chiave API è sicura per l'incorporamento negli URL e non richiede alcuna codifica.

Consulta Query di esempio.

Modello dei dati

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

Registra

Un'informazione distinta su una pagina o un sito. Un record può contenere dati specifici per un identificatore e per una combinazione specifica 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 di quell'origine vengono aggregati. Ad esempio, supponiamo che l'origine http://www.example.com contenga pagine disposte come in 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 sul Chrome UX Report 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, aggregati insieme, perché si tratta di tutte le pagine di quell'origine.

URL

Se l'identificatore è un URL, verranno restituiti solo i dati relativi a quell'URL specifico. Torniamo alla 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 relativi a quella pagina.

Dimensioni

Le dimensioni identificano un gruppo specifico di dati in base ai quali 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 certo numero di valori e, implicitamente, la mancata specifica di quella dimensione significherà che la dimensione viene aggregata su tutti i valori. Ad esempio, se non specifichi alcun fattore di forma, il record contiene informazioni sui caricamenti avvenuti su qualsiasi fattore di forma.

Fattore di forma

La classe del dispositivo utilizzato dall'utente finale per accedere alla pagina. Si tratta di una classe generale di dispositivi suddivisa in PHONE, TABLET e DESKTOP.

Metrica

Riportiamo le metriche del report come aggregazioni statistiche, in istogrammi, percentili e frazioni.

I valori in virgola mobile vengono arrotondati a 4 cifre decimali (tieni presente che le metriche cumulative_layout_shift sono valori double codificati come stringa, quindi non sono considerati valori in virgola mobile e vengono riportati con 2 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 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 assumeremo millisecondi.

Inoltre, il 49,91% dei caricamenti pagina 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 che possono essere utili per ulteriori analisi. Riportiamo valori di metriche specifici al percentile indicato per quella metrica. Si basano sull'insieme completo di dati disponibili e non sui dati raggruppati finali, pertanto non corrispondono necessariamente a un percentile interpolato basato sull'istogramma raggruppato finale.

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

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

Frazioni

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

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

"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

Mappatura dei nomi delle metriche di BigQuery

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, puoi comprendere meglio i dati e capire se sono già stati aggiornati per quel giorno o se restituiscono gli stessi dati del giorno precedente.

Il periodo di raccolta è disponibile anche in PageSpeed Insights:

Inoltre, collectionPeriod mostrerà sempre 28 giorni, anche se i dati non coprono l'intero periodo di 28 giorni (ad esempio, se una pagina è stata lanciata meno di 28 giorni fa). collectionPeriod è il periodo di tempo in cui sono stati aggregati i dati CrUX, non necessariamente il periodo di tempo rappresentato dai dati.

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 della query come oggetto JSON nel corpo della richiesta POST:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Ad esempio, può essere chiamato 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
• interaction_to_next_paint
• largest_contentful_paint
• experimental_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (viene segnalato solo se nella richiesta non è specificato formFactor)
• experimental_ad_count (registrato solo per le pagine incluse nelle metriche degli annunci)
• experimental_ad_density (registrato solo per le pagine incluse nelle metriche degli annunci)
• experimental_ad_cpu (riportato solo per le pagine incluse nelle metriche degli annunci)
• experimental_ad_kilobytes (registrato solo per le pagine incluse nelle metriche degli annunci)

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

Per altri esempi di query, consulta Utilizzo dell'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 che diventino disponibili tramite l'API.

La media mobile

I dati nel Chrome UX Report sono una media mobile di 28 giorni delle metriche aggregate. Ciò significa che i dati presentati nel Chrome UX Report in un determinato momento sono in realtà i dati degli ultimi 28 giorni aggregati.

Questo processo è 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 in base al criterio del "best effort".

Schema

Esiste un singolo endpoint per l'API CrUX che accetta richieste HTTP POST. L'API restituisce un record che contiene uno o più metrics corrispondenti ai dati sul rendimento relativi all'origine o alla 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:

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

Ad esempio, per richiedere i valori di Largest Contentful Paint per computer per la home page della documentazione per lo sviluppo 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 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.

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

Metriche

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

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

o

{
  "fractions": {
    object (Fractions)
  }
}

Bin

Un bin è una porzione discreta di dati che va dall'inizio alla fine o, se non viene fornita una fine, dall'inizio all'infinito positivo.

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

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

Percentili

Percentiles contiene valori sintetici di una metrica in un determinato percentile statistico. Vengono utilizzati per stimare il valore di una metrica in base all'esperienza di una percentuale di utenti rispetto al numero totale di utenti.

{
  "P75": value
}

Frazioni

Fractions contiene frazioni etichettate che sommano a ~1. Ogni etichetta descrive in qualche modo un caricamento pagina, quindi le metriche rappresentate in questo modo possono essere considerate come 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
}

Analogamente ai valori di densità nei bin dell'istogramma, ogni fraction è un numero 0.0 <= value <= 1.0 e la loro somma è pari a circa 1,0.

UrlNormalization

Oggetto che rappresenta le azioni di normalizzazione intraprese per normalizzare un URL al fine di ottenere una maggiore probabilità di ricerca riuscita. Si tratta di modifiche di base e automatiche che vengono apportate quando si sa che la ricerca del url_pattern fornito non andrà a buon fine. Le azioni complesse, come seguire i reindirizzamenti, non vengono gestite.

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

Limiti di frequenza

L'API CrUX è limitata a 150 query al minuto per progetto Google Cloud, offerto senza costi. Questo limite e l'utilizzo attuale sono visibili nella console Google Cloud. Questa quota generosa dovrebbe essere sufficiente per la stragrande maggioranza dei casi d'uso e non è possibile pagare per un aumento della quota.