In diesem Leitfaden wird der Endpunkt der Chrome UX Report History API (CrUX) vorgestellt, über den Zeitreihen mit Webleistungsdaten bereitgestellt werden. Diese Daten werden wöchentlich aktualisiert und umfassen einen Zeitraum von etwa sechs Monaten mit 25 Datenpunkten, die jeweils eine Woche auseinanderliegen.
In Kombination mit den täglichen Aktualisierungen vom ursprünglichen CrUX API-Endpunkt können Sie jetzt schnell sowohl die neuesten Daten als auch die bisherigen Ereignisse sehen. Dies ist ein leistungsstarkes Tool, um Webseitenänderungen im Zeitverlauf zu beobachten.
API auf dieser Seite testen
Tägliche CrUX API abfragen
Wie in einem früheren Artikel zur CrUX API erläutert, können Sie so einen Snapshot der Felddaten für einen bestimmten Ursprung abrufen:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Dieser Snapshot enthält Histogrammdichtewerte und Prozentrangwerte für einen bestimmten Erfassungszeitraum von 28 Tagen, in diesem Fall vom 27. Dezember 2022 bis zum 23. Januar 2023.
CrUX History API abfragen
Wenn Sie den Verlaufsendpunkt aufrufen möchten, ändern Sie queryRecord in der URL in queryHistoryRecord im Befehl curl. Sie können denselben CrUX API-Schlüssel wie beim vorherigen Aufruf verwenden.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev"}'
Die allgemeine Struktur einer Antwort ist ähnlich, aber es gibt viel mehr Daten. Anstelle eines einzelnen Datenpunkts gibt es jetzt Zeitreihen für die Felder mit dem 75. Perzentil (p75) und den Histogrammdichtewerten.
{
"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 }
}
]
}
}
In diesem Beispiel ist [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. die densities-Zeitreihe für den Bucket von 0 bis 2.500 ms des Messwerts Largest Contentful Paint (LCP). Jede dieser Dichten wurde während des entsprechenden collectionPeriods-Eintrags beobachtet. Die fünfte Dichte, 0,9183, war beispielsweise die Dichte für den fünften Erhebungszeitraum, der am 3. September 2022 endete, und 0,9187 war die Dichte im Zeitraum, der in der Woche darauf endete.
Mit anderen Worten: Bei der Auswertung der letzten Zeitreiheneinträge im Beispiel für https://web.dev wurde festgestellt, dass vom 14. August 2022 bis zum 10. September 2022 91,87% der Seitenladezeiten LCP-Werte unter 2.500 ms hatten, 5,27% Werte zwischen 2.500 ms und 4.000 ms und 2,85% Werte über 4.000 ms.
Ebenso gibt es eine Zeitreihe für die Werte des P75: Der LCP-P75 vom 14. August 2022 bis zum 10. September 2022 betrug 1377. Das bedeutet, dass bei 75% der Nutzererfahrungen in diesem Erfassungszeitraum der LCP unter 1.377 Millisekunden lag und bei 25% der Nutzererfahrungen über 1.377 Millisekunden.
Im Beispiel sind nur sechs Zeitreiheneinträge und Erfassungszeiträume aufgeführt. Die Antworten der API enthalten jedoch 25 Zeitreiheneinträge. Da die Enddaten für jeden dieser Erfassungszeiträume Samstage sind, die sieben Tage auseinander liegen, umfasst dies einen Zeitraum von sechs Monaten.
In jeder Antwort ist die Länge der Zeitreihe für die Histogramm-Bin-Dichten und für die p75-Werte genau gleich der Länge des Arrays im Feld collectionPeriods. Es gibt eine Eins-zu-Eins-Beziehung basierend auf dem Index in diesen Arrays.
Daten auf Seitenebene abfragen
Neben Daten auf Ursprungsebene ermöglicht die CrUX History API auch den Zugriff auf Verlaufsdaten auf Seitenebene. Die Daten auf Ursprungsebene waren bisher über das CrUX-Dataset in BigQuery oder über das CrUX-Dashboard verfügbar. Die Verlaufsdaten auf Seitenebene waren nur verfügbar, wenn die Daten von den Websites selbst erfasst und gespeichert wurden. Mit der neuen API können Sie jetzt auf diese Verlaufsdaten auf Seitenebene zugreifen.
Die Daten auf Seitenebene können auf die gleiche Weise abgefragt werden, jedoch mit url anstelle von origin in der Nutzlast:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Verlaufsdaten auf Seiten- und Ursprungsebene unterliegen denselben Teilnahmevoraussetzungen wie der Rest von CrUX. Daher sind für Seiten möglicherweise keine vollständigen Verlaufsdaten verfügbar. In diesen Fällen werden die „fehlenden“ Daten durch "NaN" für die histogramTimeseries-Dichten und null für die percentilesTimeseries dargestellt. Der Grund für den Unterschied ist, dass die Histogrammdichten immer Zahlen sind, während die Perzentile Zahlen oder Strings sein können. In CLS werden Strings verwendet, auch wenn sie wie Zahlen aussehen.
Daten visualisieren
Sie fragen sich vielleicht, warum die Daten so aussehen. Es wurde festgestellt, dass dies das Zeichnen von Grafiken erleichtert. Hier ist beispielsweise ein Diagramm für die p75-Werte für Interaction to Next Paint (INP) für https://web.dev:
In diesem Liniendiagramm ist jeder Wert auf der y-Achse ein p75-Wert aus der Zeitreihe p75s. Die x-Achse ist die Zeit, die für jeden Erfassungszeitraum als lastDate festgelegt ist.
Hier sehen Sie ein Diagramm für die Zeitreihe der Histogramm-Bins, auch als Drei-Bin-Diagramm bezeichnet, da diese Histogramme drei Bins haben.
Die x-Achse ist für jeden Erfassungszeitraum als lastDate eingerichtet. Dieses Mal ist die y-Achse jedoch der Prozentsatz der Seitenladezeiten, die in einen bestimmten Bereich für den Messwert „Inhalte mit hoher Nachfrage“ fallen. Dieser wird in einem gestapelten Balkendiagramm dargestellt. Das Diagramm „p75“ bietet einen schnellen Überblick. Innerhalb eines einzelnen Diagramms können Sie relativ einfach mehrere Messwerte hinzufügen oder Linien für PHONE und DESKTOP anzeigen. Das Dreifach-Bin-Diagramm gibt Aufschluss über die Verteilung der Messwerte, die in jedem Erfassungszeitraum erfasst wurden.
Obwohl das Diagramm für den P75 beispielsweise darauf hindeutet, dass https://web.dev während des Beobachtungszeitraums fast akzeptable INP-Werte hatte, zeigt das Dreifach-Bin-Diagramm, dass die INP bei einem kleinen Teil der Seitenladevorgänge tatsächlich schlecht war. In beiden Diagrammen lässt sich relativ leicht ableiten, dass es eine Leistungsregression gab, die Ende Oktober begann und Mitte November behoben wurde.
Wenn Sie solche Diagramme selbst erstellen möchten, haben wir ein Beispiel-Colab für Sie erstellt. Mit einem Colab (kurz für „Colaboratory“) können Sie Python-Code direkt in Ihrem Browser schreiben und ausführen. Im CrUX History API Colab (Quelle) werden Python-Aufrufe an die API gesendet und die Daten in Diagrammen dargestellt.
In diesem Colab können Sie P75-Diagramme, Dreifach-Bin-Diagramme erstellen, Daten in Tabellenform abrufen und das Anfrage- und Antwortpaar für die CrUX API aufrufen, indem Sie ein kurzes Formular ausfüllen. Sie müssen kein Programmierer sein, um diese Funktion zu verwenden. Sie können sich aber den Python-Code ansehen und ihn zu etwas Besonderem umwandeln. Viel Spaß beim Entdecken und gib uns gerne Feedback zu deinen Eindrücken.
Natürlich sind Sie nicht auf Colab oder Python beschränkt. Dies ist nur ein Beispiel dafür, wie Sie diese neue API verwenden können. Da es sich um einen JSON-basierten HTTP-Endpunkt handelt, kann die API mit jeder Technologie abgefragt werden.
Fazit
Vor der Einführung des CrUX History API-Endpunkts waren die Verlaufsinformationen, die Websiteinhaber über CrUX abrufen konnten, begrenzt. Mit BigQuery und dem CrUX-Dashboard waren monatliche Daten auf Herkunftsebene verfügbar, aber keine wöchentlichen Daten und keine Verlaufsdaten auf Seitenebene. Websiteinhaber konnten diese Daten selbst mit der täglichen API erfassen. Oft wurde dies jedoch erst nach einer Regression der Messwerte erforderlich.
Wir hoffen, dass Websiteinhaber mit der Einführung dieser CrUX History API ihre sich ändernden Websitemesswerte besser nachvollziehen und bei Problemen ein Diagnosetool zur Hand haben. Wenn Sie die neue API verwenden, freuen wir uns über Feedback in der Google-Gruppe Chrome UX Report (Discussions).
Danksagungen
Hero-Image von Dave Herring auf Unsplash