Über die CrUX API erhalten Sie mit niedriger Latenz Zugriff auf aggregierte Daten zur Nutzerfreundlichkeit auf Seiten- und Ursprungsebene.
Häufiger Anwendungsfall
Mit der CrUX API können Messwerte zur Nutzererfahrung für einen bestimmten URI wie „Messwerte für den Ursprung https://example.com
abrufen“ abgefragt werden.
CrUX API-Schlüssel
Zur Verwendung der CrUX API ist ein Google Cloud API-Schlüssel erforderlich, der für die Chrome UX Report API
-Nutzung bereitgestellt wird.
API-Schlüssel erhalten und nutzen
Schlüssel anfordernAlternativ können Sie auf der Seite "Anmeldedaten" einen Schlüssel erstellen.
Nachdem Sie einen API-Schlüssel haben, kann Ihre Anwendung den Abfrageparameter key=yourAPIKey
an alle Anfrage-URLs anhängen.
Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.
Siehe Beispielabfragen.
Datenmodell
In diesem Abschnitt wird die Struktur der Daten in Anfragen und Antworten beschrieben.
Eintrag
Eine eigenständige Information über eine Seite oder Website. Ein Datensatz kann Daten enthalten, die für eine Kennung und eine bestimmte Kombination von Dimensionen spezifisch sind. Ein Datensatz kann Daten für einen oder mehrere Messwerte enthalten.
IDs
IDs geben an, nach welchen Datensätzen gesucht werden soll. In CrUX sind diese Kennungen Webseiten und Websites.
Ursprung
Wenn es sich bei der Kennung um einen Ursprung handelt, werden alle für alle Seiten in diesem Ursprung vorhandenen Daten zusammengefasst. Angenommen, der Ursprung http://www.example.com
hat die Seiten, die in dieser Sitemap dargestellt werden:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Wenn also der UX-Bericht für Chrome abgefragt wird und der Ursprung auf http://www.example.com
gesetzt ist, werden Daten für http://www.example.com/
, http://www.example.com/foo.html
und http://www.example.com/bar.html
zurückgegeben, zusammengefasst, da dies alle Seiten unter diesem Ursprung sind.
URLs
Wenn die ID eine URL ist, werden nur Daten für diese spezifische URL zurückgegeben. Gehen Sie noch einmal zur Ursprungs-Sitemap http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Wenn die ID auf URL mit dem Wert http://www.example.com/foo.html
festgelegt ist, werden nur Daten für diese Seite zurückgegeben.
Abmessungen
Dimensionen identifizieren eine bestimmte Gruppe von Daten, mit denen ein Datensatz aggregiert wird. So gibt beispielsweise der Formfaktor PHONE
an, dass der Datensatz Informationen zu Ladevorgängen auf einem Mobilgerät enthält. Jede Dimension hat eine bestimmte Anzahl von Werten. Wenn diese Dimension nicht angegeben wird, wird sie über alle Werte aggregiert. Wenn Sie zum Beispiel keinen Formfaktor angeben, bedeutet dies, dass der Datensatz Informationen über Ladevorgänge enthält, die auf einem beliebigen Formfaktor stattgefunden haben.
Formfaktor
Die Geräteklasse, mit der der Endnutzer die Seite aufgerufen hat. Dies ist eine allgemeine Geräteklasse, die in die Kategorien PHONE
, TABLET
und DESKTOP
aufgeteilt ist.
Effektiver Anschlusstyp
Der effektive Verbindungstyp gibt die geschätzte Verbindungsqualität des Geräts beim Aufrufen der Seite an. Dies ist eine allgemeine Klasse, die in die Kategorien offline
, slow-2G
, 2G
, 3G
und 4G
unterteilt ist.
Messwert
Messwerte werden als statistische Aggregationen, als Histogramme, Perzentile und Brüche gemeldet.
Gleitkommawerte werden auf vier Dezimalstellen gerundet. Beachten Sie, dass die cumulative_layout_shift
-Messwerte doppelt als String codiert sind. Gleitkommazahlen werden daher nicht berücksichtigt und im String mit zwei Dezimalstellen gemeldet.
Histogramm
Wenn Messwerte in einem Histogramm dargestellt werden, sehen Sie die Prozentsätze der Seitenaufrufe, die bestimmte Bereiche für diesen Messwert.
Ein Histogramm mit drei Klassen für einen Beispielmesswert sieht so aus:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
Diese Daten zeigen an, dass bei 38,18% der Seitenladevorgänge der Beispielmesswert gemessen wurde. zwischen 0 ms und 1.000 ms. Die Einheiten des Messwerts sind in diesem Histogramm nicht enthalten, In diesem Fall gehen wir von Millisekunden aus.
Außerdem ergab sich bei 49,91% der Seitenaufrufe ein Messwert zwischen 1.000 ms und 3.000 ms und 11,92 %. einen Wert über 3.000 ms sahen.
Perzentile
Messwerte können auch Perzentile enthalten, die für weitere Analysen nützlich sein können. Für diesen Messwert werden bestimmte Werte nach dem angegebenen Perzentil erfasst. Sie basieren auf allen verfügbaren Daten und nicht auf den endgültigen gruppierten Daten, sodass sie nicht unbedingt mit einem interpolierten Perzentil übereinstimmen, das auf dem das endgültige gruppierte Histogramm.
{
"percentiles": {
"p75": 2063
}
}
In diesem Beispiel wurden mindestens 75% der Seitenaufrufe mit dem Messwert <= 2063
gemessen.
Brüche
Bruchteile geben die Prozentsätze der Seitenladevorgänge an, die mit einem bestimmten Label versehen werden können. In diesem Fall sind die Messwerte diese Labels.
Der Messwert form_factors
besteht beispielsweise aus einem fractions
-Objekt, das eine Aufschlüsselung der Formfaktoren (oder Geräte) auflistet, die die jeweilige Abfrage abdeckt:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
In diesem Fall wurden 3,77% der Seitenaufrufe auf einem Computer, 2,88% auf einem Tablet und 93,35% auf einem Smartphone gemessen, was insgesamt 100% entspricht.
Messwerttypen
Name des CrUX API-Messwerts | Datentyp | Metrische Einheiten | Statistische Aggregationen | Dokumentation |
---|---|---|---|---|
cumulative_layout_shift |
Zwei Dezimalstellen als String doppelt codiert | ohne Einheit | Histogramm mit drei Bins, Perzentile mit P75 | cls |
first_contentful_paint |
int | Millisekunden | Histogramm mit drei Bins, Perzentile mit P75 | FCP |
first_input_delay (eingestellt) |
int | Millisekunden | Histogramm mit drei Bins, Perzentile mit P75 | Fid |
interaction_to_next_paint |
int | Millisekunden | Histogramm mit drei Bins, Perzentile mit P75 | Inp |
largest_contentful_paint |
int | Millisekunden | Histogramm mit drei Bins, Perzentile mit P75 | lcp |
experimental_time_to_first_byte |
int | Millisekunden | Histogramm mit drei Bins, Perzentile mit P75 | ttfb |
form_factors |
Doppelte Stellen mit 4 Dezimalstellen | Prozent | Zuordnung vom Formfaktor zum Bruch | Formfaktoren |
navigation_types |
Doppelte Stellen mit 4 Dezimalstellen | Prozent | Zuordnung vom Navigationstyp zum Bruch | Navigationstypen |
round_trip_time |
int | Millisekunden | Perzentile mit P75 | rtt |
Zuordnung von BigQuery-Messwertnamen
Name des CrUX API-Messwerts | Name des BigQuery-Messwerts |
---|---|
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 |
– |
round_trip_time |
– |
Erfassungszeitraum
Seit Oktober 2022 enthält die CrUX API ein collectionPeriod
-Objekt mit den Feldern firstDate
und endDate
, die das Start- und Enddatum des Aggregationsfensters darstellen. Beispiel:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
So können Sie die Daten besser verstehen und feststellen, ob sie für diesen Tag noch aktualisiert wurden oder dieselben Daten wie gestern zurückgeben.
Die CrUX API liegt etwa zwei Tage hinter dem heutigen Datum, da sie auf die abgeschlossenen Daten für den Tag wartet. Außerdem ist eine gewisse Verarbeitungszeit erforderlich, bis die API in der API verfügbar ist. Als Zeitzone wird Pacific Standard Time (PST) verwendet. Die Sommerzeit wird nicht geändert.
Beispielabfragen
Abfragen werden als JSON-Objekte mit einer POST-Anfrage an https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
mit Abfragedaten als JSON-Objekt im POST-Text gesendet:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Dies kann beispielsweise über curl
mit der folgenden Befehlszeile aufgerufen werden (ersetzen Sie dabei API_KEY
durch Ihren Schlüssel):
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"]}'
Daten auf Seitenebene sind über die API verfügbar, indem in der Abfrage eine url
-Eigenschaft anstelle von origin
übergeben wird:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Wenn das Attribut metrics
nicht festgelegt ist, werden alle verfügbaren Messwerte zurückgegeben:
cumulative_layout_shift
first_contentful_paint
first_input_delay
(eingestellt)interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(wird nur gemeldet, wenn in der Anfrage keinformFactor
angegeben wurde)
Wenn kein formFactor
-Wert angegeben wird, werden die Werte für alle Formfaktoren aggregiert.
Weitere Beispielabfragen finden Sie unter Chrome UX Report API verwenden.
Datenpipeline
Das CrUX-Dataset wird über eine Pipeline verarbeitet, um die Daten zu konsolidieren, zu aggregieren und zu filtern, bevor sie über die API verfügbar werden.
Gleitender Durchschnitt
Bei den Daten im UX-Bericht für Chrome handelt es sich um einen gleitenden Durchschnitt aggregierter Messwerte über einen Zeitraum von 28 Tagen. Das bedeutet, dass es sich bei den Daten im UX-Bericht für Chrome zu einem bestimmten Zeitpunkt um Daten der letzten 28 Tage handelt.
Ähnlich wie im CrUX-Dataset in BigQuery werden monatliche Berichte zusammengefasst.
Tägliche Updates
Die Daten werden täglich um 4:00 Uhr (UTC) aktualisiert. Es gibt kein Service Level Agreement für Aktualisierungszeiten. jeden Tag auf Best-Effort-Basis ausgeführt.
Schema
Es gibt einen einzigen Endpunkt für die CrUX API, die POST
-HTTP-Anfragen akzeptiert. Die API gibt eine record
zurück, die mindestens eine metrics
enthält, die den Leistungsdaten zum angeforderten Ursprung oder der angeforderten Seite entspricht.
HTTP-Anfrage
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
Die URL verwendet die Syntax der gRPC-Transcodierung.
Anfragetext
Der Anfragetext sollte Daten mit folgender Struktur enthalten:
{
"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.
}
Felder | |
---|---|
effectiveConnectionType |
Der Typ der effektiven Verbindung ist eine Abfragedimension, die die effektive Netzwerkklasse angibt, zu der die Daten des Eintrags gehören sollen. In diesem Feld werden die Werte Hinweis: Wenn kein effektiver Verbindungstyp angegeben ist, wird ein spezieller Datensatz mit aggregierten Daten über alle effektiven Verbindungstypen zurückgegeben. |
formFactor |
Der Formfaktor ist eine Abfragedimension, die die Geräteklasse angibt, zu der die Daten des Eintrags gehören sollen. In diesem Feld werden die Werte Hinweis: Wenn kein Formfaktor angegeben ist, wird ein spezieller Datensatz mit aggregierten Daten über alle Formfaktoren zurückgegeben. |
metrics[] |
Die Messwerte, die in der Antwort enthalten sein sollen. Wenn keine angegeben sind, werden alle gefundenen Messwerte zurückgegeben. Zulässige Werte: |
Union-Feld url_ . url_pattern ist die Hauptkennung für die Suche nach Einträgen. Folgende Werte sind zulässig: |
|
origin |
Der „Ursprung“ Beispiele: |
url |
Das Beispiele: |
So fordern Sie beispielsweise die größten Contentful Paint-Werte für Computer für die Startseite der Chrome-Entwicklerdokumentation an:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Antworttext
Erfolgreiche Anfragen geben Antworten mit einem record
-Objekt und einem urlNormalizationDetails
in der folgenden Struktur zurück:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Die Antwort auf den Anfragetext in der vorherigen Anfrage könnte beispielsweise so aussehen:
{
"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
}
}
}
}
Schlüssel
Key
definiert alle Dimensionen, die diesen Datensatz als eindeutig identifizieren.
{
"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.
}
Felder | |
---|---|
formFactor |
Der Formfaktor ist die Geräteklasse, über die alle Nutzer für diesen Eintrag auf die Website zugegriffen haben. Wenn der Formfaktor nicht angegeben ist, werden aggregierte Daten für alle Formfaktoren zurückgegeben. |
effectiveConnectionType |
Der effektive Verbindungstyp ist die allgemeine Verbindungsklasse, die alle Nutzer für diesen Eintrag hatten. In diesem Feld werden die Werte ["offline", "slow-2G", "2G", "3G", "4G"] wie in https://wicg.github.io/netinfo/#effective-connection-types angegeben. Wenn der effektive Verbindungstyp nicht angegeben ist, werden aggregierte Daten für alle effektiven Verbindungstypen zurückgegeben. |
Union-Feld url_ . Das URL-Muster ist die URL, für die der Eintrag gilt. Für url_ ist nur einer der folgenden Werte zulässig: |
|
origin |
Hinweis: Wenn Sie eine |
url |
Hinweis: Wenn du eine |
Messwerte
Ein metric
besteht aus aggregierten Daten zur Nutzererfahrung für einen einzelnen Webleistungsmesswert, z. B. „First Contentful Paint“.
Sie kann ein Histogramm der realen Nutzung von Chrome in Form von bins
-spezifischen Perzentildaten enthalten.
(z. B. p75) oder Brüche mit Labels enthalten.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
oder
{
"fractions": {
object (Fractions)
}
}
Felder | |
---|---|
histogram[] |
Das Histogramm der Nutzerfreundlichkeit für einen Messwert. Das Histogramm hat mindestens eine Klasse und die Dichten aller Klassen ergeben zusammen ~1. |
percentiles |
Gemeinsame nützliche Perzentile des Messwerts. Der Werttyp für die Perzentile entspricht den Werttypen, die für die Histogramm-Bins angegeben wurden. |
fractions |
Dieses Objekt enthält Brüche mit Labels, die zusammen ~1 ergeben. Brüche werden auf vier Dezimalstellen gerundet. |
Klasse
Eine bin
ist ein diskreter Teil von Daten, der sich von Anfang bis Ende erstreckt, oder wenn kein Ende von Anfang bis positiv unendlich angegeben wird.
Die Start- und Endwerte einer Klasse werden im Werttyp der entsprechenden Metrik angegeben. First Contentful Paint wird beispielsweise in Millisekunden gemessen und als Ganzzahlen dargestellt. Daher verwenden die Messwert-Bins als Start- und Endtyp den Wert „int32“. Kumulative Layout Shifts werden jedoch in Dezimalzahlen ohne Einheit gemessen und als Dezimalzahl dargestellt und als String codiert. Daher verwenden die Messwert-Klassen Strings als Werttyp.
{
"start": value,
"end": value,
"density": number
}
Felder | |
---|---|
start |
„Start“ ist der Anfang der Datengruppe. |
end |
Das Ende ist das Ende der Datengruppe. Wenn end nicht ausgefüllt ist, hat der Container kein Ende und ist von „start“ bis +inf gültig. |
density |
Der Anteil der Nutzer, die den Bin-Wert für den jeweiligen Messwert erlebt haben. Dichten werden auf vier Dezimalstellen gerundet. |
Perzentile
Percentiles
enthält synthetische Werte eines Messwerts bei einem bestimmten statistischen Perzentil. Sie werden verwendet, um den Wert eines Messwerts zu schätzen, der von einem Prozentsatz der Nutzer bezogen auf die Gesamtzahl der Nutzer erlebt wird.
{
"P75": value
}
Felder | |
---|---|
p75 |
Bei 75% der Seitenladevorgänge lag der angegebene Messwert bei oder unter diesem Wert. |
Brüche
Fractions
enthält Brüche mit Labels, die zusammen eine Summe von ~1 ergeben. Jedes Label beschreibt ein
Seitenaufbau vor. Daher sind die so dargestellten Messwerte
wobei unterschiedliche Werte anstelle von numerischen Werten erzeugt werden, und die Brüche ausdrücken
wie oft ein bestimmter bestimmter Wert gemessen wurde.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Ähnlich wie bei den Dichtewerten in Histogrammklassen ist jeder fraction
eine Zahl.
0.0 <= value <= 1.0
, und sie ergeben in der Summe ca.1,0.
UrlNormalization
Objekt, das die Normalisierungsaktionen darstellt, die zum Normalisieren einer URL durchgeführt werden, um eine höhere Wahrscheinlichkeit für einen erfolgreichen Lookup zu erreichen. Dies sind einfache automatisierte Änderungen, die bei der Suche nach der bereitgestellten url_pattern
vorgenommen werden. Diese Änderungen würden scheitern. Komplexe Aktionen wie das Folgen von Weiterleitungen werden nicht berücksichtigt.
{
"originalUrl": string,
"normalizedUrl": string
}
Felder | |
---|---|
originalUrl |
Die ursprünglich angeforderte URL vor allen Normalisierungsaktionen. |
normalizedUrl |
Die URL nach allen Normalisierungsaktionen. Dies ist eine gültige URL für die Nutzererfahrung, die vernünftigerweise nachgeschlagen werden könnte. |
Ratenlimits
Die CrUX API ist auf 150 Abfragen pro Minute pro Google Cloud-Projekt beschränkt, die kostenlos angeboten werden. Dieses Limit und Ihre aktuelle Nutzung können Sie in der Google Cloud Console einsehen. Dieses großzügige Kontingent sollte für die meisten Anwendungsfälle ausreichen. Eine Erhöhung des Kontingents ist nicht möglich.