Über die CrUX History API erhalten Sie mit niedriger Latenz Zugriff auf Verlaufsdaten zur Nutzerfreundlichkeit von sechs Monaten auf Seiten- und Ursprungsebene.
Häufiger Anwendungsfall
Mit der CrUX History API können frühere Messwerte zur Nutzererfahrung für einen bestimmten URI abgefragt werden, z. B. „Bisherige UX-Trends für den https://example.com-Ursprung abrufen“.
Die History API hat dieselbe Struktur wie die tägliche CrUX API, nur dass Werte in einem Array angegeben und Schlüssel mit Pluralnamen gekennzeichnet werden, z. B. histogramTimeseries statt histogram oder p75s statt p75.
CrUX API-Schlüssel
Wie bei der Daily API ist für die Verwendung der CrUX History API ein Google Cloud API-Schlüssel erforderlich. Derselbe Schlüssel kann für die Daily API und die History API verwendet werden.
Sie können auf der Seite Anmeldedaten eine Anmeldedaten erstellen und sie für Chrome UX Report API bereitstellen.
Sobald Sie einen API-Schlüssel haben, kann Ihre Anwendung den Suchparameter key=[YOUR_API_KEY] an alle Anfrage-URLs anhängen (siehe Beispielabfragen).
Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.
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 angeordnet sind:
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. Der Formfaktor PHONE gibt beispielsweise an, dass der Datensatz Informationen zu Ladevorgängen enthält, die auf einem Mobilgerät ausgeführt wurden.
Die CrUX History API ist nur nach Formfaktordimension zusammengefasst verfügbar. Dies ist eine allgemeine Geräteklasse, die in die Kategorien PHONE, TABLET und DESKTOP unterteilt ist.
Messwert
Messwerte werden in Zeitreihen statistischer Aggregationen erfasst, bei denen es sich um Histogramme, Perzentile und Brüche handelt.
Histogramme
Wenn Messwerte in einem Histogramm-Array ausgedrückt werden, gibt jeder Zeitreiheneintrag den Prozentsatz der Seitenladevorgänge an, bei denen der Messwert in ein Intervall fällt, proportional zu allen Seitenladevorgängen. Die Datenpunkte werden in der Reihenfolge der Daten dargestellt, die ebenfalls von der API für den Erfassungszeitraum zurückgegeben werden. Der erste Punkt ist dabei der früheste Zeitraum und der letzte Punkt der jüngste Erfassungszeitraum.
Ein einfaches Histogramm mit drei Bins für einen Beispielmesswert sieht so aus:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
}
],
}
Diese Daten zeigen, dass im ersten Erfassungszeitraum bei 91,90% der Seitenladevorgänge der beispielhafte Messwertwert zwischen 0 ms und 2.500 ms im Verlauf liegt, gefolgt von 92,03%, 91,94%... Die Einheiten der Metrik sind in diesem Histogramm nicht enthalten. In diesem Fall gehen wir von Millisekunden aus.
Darüber hinaus hatten 5,21% der Seitenladevorgänge den Beispielmesswert im ersten Erfassungszeitraum zwischen 2.500 ms und 4.000 ms im Verlauf und 2,88% der Seitenladevorgänge einen Wert von über 4.000 ms im ersten Erfassungszeitraum im Verlauf.
Perzentile
Messwerte können auch Zeitreihen von Perzentilen enthalten, die für weitere Analysen nützlich sein können.
Die Datenpunkte werden in der Reihenfolge der Daten dargestellt, die ebenfalls von der API für den Erfassungszeitraum zurückgegeben werden. Der erste Punkt ist dabei der früheste Zeitraum und der letzte Punkt der jüngste Erfassungszeitraum.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Diese Perzentile können bestimmte Messwerte innerhalb des angegebenen Perzentils für diesen Messwert anzeigen. Sie basieren auf dem vollständigen Satz verfügbarer Daten und nicht auf den endgültigen gruppierten Daten, sodass sie nicht unbedingt mit einem interpolierten Perzentil übereinstimmen, das auf dem endgültigen gruppierten Histogramm basiert.
Brüche
Messwerte können als Zeitreihe von Brüchen mit Labels ausgedrückt werden. Jedes Label beschreibt einen Seitenaufbau auf eine bestimmte Weise. Die Datenpunkte werden in der Reihenfolge der Daten dargestellt, die ebenfalls von der API für den Erfassungszeitraum zurückgegeben werden. Der erste Punkt ist dabei der früheste Zeitraum und der letzte Punkt der jüngste Erfassungszeitraum.
Beispiel:
{
"fractionTimeseries": {
"desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
"phone": {"fractions": [0.6295, 0.7544, 0.8288]},
"tablet": {"fractions": [0.051, 0.0341, 0.029]}
}
}
In diesem Beispiel zeigt der neueste Datenpunkt, dass 14,21% der Seitenladevorgänge von Desktop-Computern und 82,88% von Smartphones stammen.
Messwerttypen
Da für die CrUX History API dieselben Messwerttypen verwendet werden, finden Sie in der täglichen Dokumentation zu den Messwerttypen der CrUX API weitere Informationen.
Erforderliche Messwerte
Aufgrund der Voraussetzungen ist ein Ursprung oder eine URL möglicherweise nur für einen Teil der Datenerfassungszeiträume zulässig, die von der CrUX History API abgedeckt werden. In diesen Fällen gibt die CrUX History API "NaN" für die histogramTimeseries-Dichten und null für die percentilesTimeseries für die Erfassungszeiträume zurück, für die keine geeigneten Daten vorliegen. Der Grund für den Unterschied ist, dass die Histogrammdichten immer Zahlen sind, während die Perzentile aus Zahlen oder Strings bestehen können (CLS verwendet Strings, auch wenn sie wie Zahlen aussehen).
Wenn für den zweiten Zeitraum beispielsweise keine geeigneten Daten vorliegen, wird dies so angezeigt:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
}
],
"percentilesTimeseries": {
"p75s": [1362, null, 1344, 1356, 1366, 1377]
},
}
Bei URLs oder Ursprüngen, die im Laufe der Zeit nicht mehr infrage kommen, werden möglicherweise viele Einträge fehlen.
Erfassungszeiträume
Die CrUX History API enthält ein collectionPeriods-Objekt mit einem Array aus firstDate- und endDate-Feldern, die das Start- und Enddatum jedes Aggregationsfensters darstellen. Beispiel:
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
Die Erfassungszeiträume sind in aufsteigender Reihenfolge angeordnet. Sie stellen den Zeitraum der einzelnen Datenpunkte in den anderen Abschnitten der Antwort dar.
Die History API wird jeden Montag aktualisiert und enthält Daten bis zum vorherigen Samstag (gemäß der standardmäßigen Verzögerung von 2 Tagen). Sie enthält die Daten der letzten 25 Wochen – ein Erhebungszeitraum pro Woche.
Da jeder Erhebungszeitraum die aggregierten Daten der letzten 28 Tage enthält und die Erfassungszeiträume pro Woche erfolgen, überschneiden sich die Erfassungszeiträume. Sie ähneln einem gleitenden Durchschnitt von Daten, wobei in jedem nachfolgenden Zeitraum Daten von drei Wochen erfasst werden und eine Woche anders ist.
Beispielabfragen
Abfragen werden als JSON-Objekte mit einer POST-Anfrage an https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" mit Abfragedaten als JSON-Objekt im POST-Text gesendet.
Beachten Sie, dass queryHistoryRecord die queryRecord der täglichen CrUX API ersetzt.
Hier ist ein Beispieltext:
{
"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:queryHistoryRecord?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_shiftfirst_contentful_paintfirst_input_delayinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesround_trip_timeform_factors(wird nur gemeldet, wenn in der Anfrage keinformFactorangegeben wurde)
Wenn kein formFactor-Wert angegeben wird, werden die Werte für alle Formfaktoren aggregiert.
Weitere Beispielabfragen finden Sie im Leitfaden CrUX History 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.
Die History API enthält eine Reihe von Erfassungszeiträumen, die jeweils 28 Tage umfassen. Da jeder Erhebungszeitraum die aggregierten Daten der letzten 28 Tage enthält und die Erfassungszeiträume pro Woche erfolgen, überschneiden sich die Erfassungszeiträume. Sie ähneln einem gleitenden Durchschnitt von Daten, wobei in jedem nachfolgenden Zeitraum Daten von drei Wochen erfasst werden und eine Woche anders ist.
Wöchentliche Updates
Die History API wird jeden Montag um etwa 04:00 Uhr (UTC) aktualisiert und enthält Daten bis zum vorherigen Samstag (gemäß der standardmäßigen Verzögerung von 2 Tagen). Sie enthält die Daten der letzten 25 Wochen (ca. 6 Monate) mit einem Erfassungszeitraum pro Woche.
Es gibt kein Service Level Agreement für Aktualisierungszeiten; es wird täglich nach dem Best-Effort-Prinzip ausgeführt.
Schema
Es gibt einen einzigen Endpunkt für die CrUX History 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:queryHistoryRecord
Die URL verwendet die Syntax der gRPC-Transcodierung.
Anfragetext
Für die CrUX History API werden dieselben Anfragetexte verwendet wie für die tägliche CrUX API, mit der Ausnahme, dass das Anfragefeld effectiveConnectionType nicht unterstützt wird.
So fordern Sie beispielsweise die Largest Contentful Paint-Werte für den Desktop für die web.dev-Startseite an:
{
"origin": "https://web.dev/",
"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": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377, ...
]
}
}
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}, {
...
}
]
}
}
Schlüssel
Key definiert alle Dimensionen, die diesen Datensatz als eindeutig identifizieren.
{
"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. |
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 |
„Origin“ gibt den Ursprung an, zu dem dieser Eintrag gehört. Hinweis: Bei der Angabe eines Ursprungs werden Daten für Ladevorgänge dieses Ursprungs auf allen Seiten in Daten zur Nutzererfahrung auf Ursprungsebene zusammengefasst. |
url |
Hinweis: Wenn du eine |
Messwerte
Ein metric besteht aus Daten zur Nutzererfahrung für einen einzelnen Leistungsmesswert im Web, z. B. „First Contentful Paint“. Sie enthält ein Histogramm der realen Nutzung von Chrome in Form einer Reihe von bins.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
oder
"fractionTimeseries": {
object (Fractions)
}
| Felder | |
|---|---|
histogramTimeseries[] |
Das Zeitreihen-Histogramm der Nutzererfahrungen für einen Messwert. Das Zeitreihen-Histogramm hat mindestens eine Klasse und die Dichten aller Klassen ergeben zusammen ~1. Fehlende Werte für diesen Erfassungszeitraum werden als |
percentilesTimeseries |
Gemeinsame nützliche Perzentile des Messwerts. Der Werttyp für die Perzentile entspricht den Werttypen, die für die Histogramm-Bins angegeben wurden. Fehlende Werte für diesen Erfassungszeitraum werden als |
fractionTimeseries |
Dieses Objekt enthält eine Zeitreihe von Brüchen mit Labels, die pro Eintrag bis zu ~ 1 ergeben. Brüche werden auf vier Dezimalstellen gerundet. Fehlende Einträge werden für alle Brüche als „NaN“ ausgedrückt. |
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,
"densities": [number, number, number...etc.]
}
| Felder | |
|---|---|
start |
„Start“ ist der Anfang der Datengruppe. |
end |
Das Ende ist das Ende der Datengruppe. Wenn für end nichts angegeben ist, hat der Container kein Ende und ist von „start“ bis „+inf“ gültig. |
densities |
Eine Zeitreihe des Anteils der Nutzer, bei denen der Wert dieser Klasse für den jeweiligen Messwert aufgetreten ist. 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 | |
|---|---|
p75s |
Zeitreihen der Werte, bei denen bei 75% der Seitenladevorgänge der angegebene Messwert mindestens diesem Wert entspricht. |
Brüche
Fractions enthält eine Zeitreihe von Brüchen mit Labels, die pro Eintrag zusammen etwa 1 ergeben.
Jedes Label beschreibt einen Seitenaufbau in irgendeiner Weise. So können Messwerte, die so dargestellt werden, als die Erzeugung unterschiedlicher Werte anstelle von numerischen Werten betrachtet werden. Die Bruchteile geben an, wie oft ein bestimmter bestimmter Wert gemessen wurde.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Ähnlich wie die Dichtewerte in Histogrammbins ist jedes fraction eine Zahl 0.0 <= value <= 1.0 und sie ergeben zusammen ca.1,0. Wenn der Messwert für einen bestimmten Erfassungszeitraum nicht verfügbar ist, lautet der entsprechende Eintrag in allen Arrays von Brüchen "NaN".
| Felder | |
|---|---|
p75s |
Zeitreihen der Werte, bei denen der angegebene Messwert bei 75% der Seitenladevorgänge niedriger oder niedriger als dieser Wert war. |
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. |
Ratenbegrenzungen
Für die CrUX History API gilt dasselbe Limit wie für die CrUX API für 150 Abfragen pro Minute pro Google Cloud-Projekt für beide APIs, 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. Ein höheres Kontingent kann nicht finanziell beglichen werden.