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 geben Aufschluss über einen Verlauf von etwa sechs Monaten mit 25 Datenpunkten in einer Woche.
Wenn Sie die täglichen Aktualisierungen des ursprünglichen CrUX API-Endpunkts verwenden, sehen Sie jetzt schnell sowohl die neuesten Daten als auch das, was zuvor passiert ist. So können Sie Änderungen an Webseiten im Zeitverlauf sehen.
Tägliche CrUX API abfragen
Wie in einem vorherigen Artikel zur CrUX API noch einmal zusammengefasst, 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 }
}
}
}
Diese Übersicht enthält Histogrammdichte- und Perzentilwerte für einen bestimmten 28-tägigen Erfassungszeitraum, 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 Gesamtform einer Antwort ist ähnlich – es gibt jedoch viel mehr Daten! Anstelle eines einzelnen Datenpunkts gibt es jetzt Zeitreihen für die Felder, die das 75. Perzentil (p75) und die Histogrammdichte enthalten.
{
"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 die Zeitachse densities für den Bucket von 0 bis 2.500 ms des Messwerts Largest Contentful Paint (LCP) [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. 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 Interpretation der letzten Zeitreiheneinträge im Beispiel für https://web.dev stellte sich heraus, dass zwischen dem 14. August 2022 und dem 10. September 2022 bei 91,87 % der Seitenaufrufe LCP-Werte unter 2.500 ms auftraten, 5,27 % Werte zwischen 2.500 ms und 4.008 ms hatten und dass Werte zwischen 2.500 ms und 4.008 ms größer als 4 ms waren.
Ähnlich gibt es eine Zeitachse für die p75-Werte: Der p75-LCP für den 14. August 2022 bis zum 10. September 2022 war 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.
Während im Beispiel nur 6 Zeitreiheneinträge und Sammlungszeiträume aufgeführt sind, liefern die Antworten der API 25 Zeitreiheneinträge. Da die Enddaten für jeden dieser Erfassungszeiträume Samstage sind, die 7 Tage auseinander liegen, umfasst dies 6 Monate.
In jeder Antwort entspricht die Länge der Zeitreihe für die Bin-Dichten des Histogramms und für p75-Werte genau der Länge des Arrays im Feld collectionPeriods: Auf dem Index dieser Arrays basiert eine 1:1-Übereinstimmung.
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, aber 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 wird das „fehlende“ Die Daten werden für die histogramTimeseries-Dichten durch "NaN" und für die percentilesTimeseries durch null 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 könnten sich also fragen, warum die Daten auf diese Weise geformt sind. Es hat sich herausgestellt, dass dadurch die grafische Darstellung von Grafiken vereinfacht wird. Hier sehen Sie als Beispiel ein Diagramm mit den p75-Werten 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 Histogrammbin-Zeitreihe – das sogenannte Tri-Bin-Diagramm –, da diese Histogramme drei Klassen haben.
Die X-Achse wird als lastDate für jeden Erfassungszeitraum eingerichtet. Dieses Mal stellt die Y-Achse jedoch den Prozentsatz der Seitenladevorgänge dar, die in einen bestimmten Bereich für den INP-Messwert fallen, und wird durch ein gestapeltes Balkendiagramm dargestellt. Das P75-Diagramm bietet einen schnellen Überblick und in einem einzelnen Diagramm können Sie relativ einfach mehrere Messwerte hinzufügen oder Linien für PHONE und DESKTOP anzeigen. Das Drei-Bin-Diagramm gibt Aufschluss über die Verteilung der Messwerte, die in den einzelnen Zeiträumen gemessen wurden.
Das p75-Diagramm deutet beispielsweise darauf hin, dass https://web.dev während des Beobachtungszeitraums fast akzeptable INP-Werte hatte. Das Tri-Bin-Diagramm zeigt jedoch, dass der INP-Wert 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.
Um solche Diagramme selbst zu generieren, haben wir ein Colab-Beispiel erstellt. Mit Colab (Colaboratory) können Sie Python in Ihrem Browser schreiben und ausführen. Die CrUX History API Colab (Quelle) verwendet Python, um die API aufzurufen und die Daten in einem Diagramm darzustellen.
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 standen Websiteinhabern nur beschränkt auf die Verlaufsdaten zur Verfügung, die sie aus CrUX-Tools erhalten konnten. Monatliche Daten auf Ursprungsebene waren mit BigQuery und dem CrUX-Dashboard verfügbar. Es waren jedoch weder wöchentliche Daten noch Verlaufsdaten auf Seitenebene verfügbar. Websiteinhaber konnten diese Daten mithilfe der Daily API selbst aufzeichnen. Häufig wurde dies jedoch erst nach einem Rückgang der Messwerte erkannt.
Die Einführung der CrUX History API soll es Websiteinhabern ermöglichen, ihre Änderungen an Websitemesswerten besser zu verstehen, und dass sie als Diagnosetool für mögliche Probleme dient. Wenn Sie die neue API verwenden, freuen wir uns über Ihr Feedback in der Google-Gruppe „Chrome UX Report (Diskussions)“.
Danksagungen
Hero-Image von Dave Herring auf Unsplash