In diesem Leitfaden wird der Endpunkt der Chrome UX Report (CrUX) History API vorgestellt, der Zeitreihen von Web-Leistungsdaten liefert. 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
Ändern Sie im Befehl curl in der URL queryRecord in queryHistoryRecord, um den Verlaufsendpunkt aufzurufen. Sie können denselben CrUX API-Schlüssel wie für den 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. So war beispielsweise die fünfte Dichte, 0, 9183, die Dichte des fünften Erfassungszeitraums, der am 3. September 2022 endete, und 0, 9187 die Dichte in der darauffolgenden Woche.
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 während dieses Erfassungszeitraums 75% der Nutzererfahrungen einen LCP von weniger als 1.377 ms und 25% einen LCP von über 1.377 ms hatten.
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 den Zugriff auf Verlaufsdaten auf Seitenebene. Die Daten auf Ursprungsebene waren bisher mit dem CrUX-Dataset in BigQuery (oder über das CrUX-Dashboard) verfügbar. Verlaufsdaten auf Seitenebene waren jedoch nur verfügbar, wenn die Websites die Daten selbst erhoben und gespeichert haben. Mit der neuen API werden diese Verlaufsdaten jetzt auf Seitenebene verfügbar.
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 Seitenebene und auf Ursprungsebene unterliegen denselben Eignungsvoraussetzungen wie der Rest von CrUX. Daher gibt es unter Umständen keine vollständigen Verlaufsdaten für Seiten. 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 aus Zahlen oder Strings bestehen können (CLS verwendet Strings, auch wenn sie wie Zahlen aussehen).
Daten visualisieren
Sie fragen sich vielleicht, warum die Daten so aussehen. Es hat sich herausgestellt, dass dadurch die grafische Darstellung von Grafiken vereinfacht wird. 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 und die X-Achse ist die Zeit, die für jeden Erfassungszeitraum als lastDate festgelegt wird.
Hier sehen Sie ein Diagramm für die Zeitachse der Histogrammbin-Zeitreihen – das sogenannte Tri-Bin-Diagramm –, da diese Histogramme drei Klassen 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 P75-Diagramm bietet einen schnellen Überblick und in einem einzelnen Diagramm ist es relativ einfach, mehrere Messwerte hinzuzufügen oder Linien für PHONE und DESKTOP anzuzeigen. Das Dreifach-Bin-Diagramm gibt einen Überblick ü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 schlussfolgern, dass es gegen Ende Oktober einen Leistungsabfall gab und dieser bis 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.
Mit Colab können Sie P75-Diagramme und Tri-Bin-Diagramme erstellen, Daten in Tabellenform abrufen und sich das Anfrage- und Antwortpaar für die CrUX API ansehen, indem Sie ein kurzes Formular ausfüllen. Sie müssen kein Programmierer sein, um dies zu verwenden – aber Sie können auf jeden Fall den Python-Code betrachten und ihn in etwas Tolles modifizieren! Wir wünschen dir viel Spaß und freuen uns über dein Feedback.
Natürlich sind Sie nicht auf Colab oder Python beschränkt und dies ist nur ein Beispiel für die Verwendung dieser neuen API. Als JSON-basierter HTTP-Endpunkt kann die API von jeder Technologie aus 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 die Einführung dieser CrUX History API Websiteinhabern dabei helfen wird, ihre sich ändernden Websitemesswerte besser zu verstehen und bei Problemen ein Diagnosetool zu 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