In diesem Leitfaden wird der Endpunkt der Chrome UX Report (CrUX) History API vorgestellt, der Zeitachsen mit Web-Leistungsdaten bereitstellt. Diese Daten werden wöchentlich aktualisiert und geben Aufschluss über den Verlauf von etwa 6 Monaten mit 25 Datenpunkten pro Woche.
Wenn Sie die täglichen Updates des ursprünglichen CrUX API-Endpunkts verwenden, erhalten Sie schnell einen Überblick über die neuesten und vorherigen Daten. Dies ist ein leistungsstarkes Tool, um Änderungen an Webseiten im Zeitverlauf zu sehen.
Tägliche CrUX API abfragen
Noch einmal in diesem Artikel zur CrUX API: Sie können folgendermaßen 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 Histogrammwerte für Dichte und Perzentile für einen bestimmten 28-tägigen Erhebungszeitraum, in diesem Fall vom 27. Dezember 2022 bis zum 23. Januar 2023.
CrUX History API abfragen
Ändern Sie queryRecord in der URL im Befehl curl in queryHistoryRecord, um den Verlaufsendpunkt aufzurufen. Sie können dafür 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"}'
Der Grundform einer Antwort ist ähnlich, aber es gibt noch 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 beträgt 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. 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 für die Dichte in der darauffolgenden Woche.
Mit anderen Worten: Bei der Interpretation der letzten Zeitachseneinträge im Beispiel für https://web.dev wurde festgestellt, dass vom 14. August 2022 bis zum 10. September 2022 bei 91,87% der Seitenladevorgänge LCP-Werte unter 2.500 ms, 5,27% Werte zwischen 2.500 ms und 40,0 ms und 40,0 ms größer als 8% waren.
Analog dazu gibt es eine Zeitreihe für die p75-Werte: Der LCP-75 für den 14. August 2022 bis zum 10. September 2022 war 1377. Das bedeutet, dass für diesen Erhebungszeitraum bei 75% der Nutzerfreundlichkeit ein LCP von weniger als 1.377 ms und bei 25% der Nutzerfreundlichkeit ein LCP von mehr als 1.377 ms aufgewiesen wurde.
Im Beispiel werden nur sechs Zeitreiheneinträge und Sammlungszeiträume aufgelistet. Die Antworten der API liefern 25 Zeitreiheneinträge. Da die Enddaten für jeden dieser Erfassungszeiträume Samstage sind, die sieben Tage auseinanderliegen, umfasst dies 6 Monate.
In jeder Antwort entspricht die Länge der Zeitreihe für die Histogramm-Bin-Dichten und die P75-Werte genau der Länge des Arrays im Feld collectionPeriods: Es gibt eine 1:1-Übereinstimmung 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. Bisher waren die Daten auf Ursprungsebene über das CrUX-Dataset in BigQuery (oder das CrUX-Dashboard) verfügbar. Die Verlaufsdaten auf Seitenebene waren aber nur verfügbar, wenn die Websites die Daten selbst erhoben und gespeichert haben. Mit der neuen API können Sie jetzt auf diese bisherigen Daten auf Seitenebene zugreifen.
Die Daten auf Seitenebene können auf dieselbe 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 Eignungsvoraussetzungen wie die übrigen Nutzererfahrung in Chrome. Daher weisen insbesondere Seiten unter Umständen keine vollständigen Verlaufsdaten auf. In diesen Fällen werden die „fehlenden“ Daten durch "NaN" für die histogramTimeseries-Dichte und durch null für die percentilesTimeseries dargestellt. Der Grund für den Unterschied besteht darin, dass die Histogrammdichte immer Zahlen sind, während die Perzentile Zahlen oder Strings sein können. Bei der CLS werden Strings verwendet, auch wenn sie wie Zahlen aussehen.
Die Daten visualisieren
Sie könnten sich also fragen, warum die Daten so geformt sind. Es hat sich gezeigt, dass dies die grafische Darstellung von Grafiken erleichtert. Hier sehen Sie als Beispiel 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 ist.
Hier sehen Sie ein Diagramm für die Histogramm-Bin-Zeitreihe – auch Tri-Bin-Diagramm genannt –, da diese Histogramme drei Klassen haben.
Die X-Achse wird als lastDate für jeden Erfassungszeitraum eingerichtet. Dieses Mal gibt die Y-Achse jedoch den Prozentsatz der Seitenladevorgänge an, die in einen bestimmten Bereich für den INP-Messwert fallen. Dieser Wert wird als gestapeltes Balkendiagramm dargestellt. Das p75-Diagramm bietet einen schnellen Überblick und innerhalb eines Diagramms ist es relativ einfach, mehrere Messwerte hinzuzufügen oder Linien für PHONE und DESKTOP anzuzeigen. Das Tribin-Diagramm gibt Aufschluss über die Verteilung der Messwerte, die in den einzelnen Erfassungszeiträumen gemessen wurden.
Beispiel: Obwohl das P75-Diagramm darauf hinweist, dass https://web.dev während des Beobachtungszeitraums fast akzeptable INP-Werte hatte, zeigt das Tri-Bin-Diagramm jedoch, dass der INP bei einem kleinen Teil der Seitenladevorgänge tatsächlich schlecht war. Aus beiden Diagrammen lässt sich relativ leicht schließen, dass es einen Leistungsabfall gab, der Ende Oktober begann und bis Mitte November behoben wurde.
Um solche Diagramme selbst zu generieren, haben wir ein Colab-Beispiel erstellt. Mit einem Colab oder „Colaboratory“ können Sie Python in Ihrem Browser schreiben und ausführen. Das CrUX History API Colab (Quelle) verwendet Python, um die API aufzurufen und die Daten in einem Diagramm darzustellen.
Mit diesem Colab können Sie P75-Diagramme und Tri-bin-Diagramme erstellen, Daten in Tabellenform abrufen und das Anfrage-/Antwort-Paar für die CrUX API sehen, indem Sie ein kurzes Formular ausfüllen. Dazu müssen Sie kein Programmierer sein, aber Sie können auf jeden Fall einen Blick auf den Python-Code werfen und ihn so modifizieren. Viel Spaß! Zögern Sie nicht, uns Feedback dazu zu geben!
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 begrenzte Verlaufsdaten zur Verfügung, die sie von CrUX erhalten konnten. Monatliche Daten auf Ursprungsebene waren mit BigQuery und dem Dashboard für Nutzererfahrung in Chrome verfügbar, aber wöchentliche Daten waren nicht verfügbar und es gab auch keine Verlaufsdaten auf Seitenebene. Websiteinhaber konnten diese Daten mithilfe der täglichen API selbst aufzeichnen. Oftmals wurde die Notwendigkeit jedoch erst durch eine Regression der Messwerte erkannt.
Mit der Einführung dieser CrUX History API möchten wir Websiteinhabern einen besseren Überblick über die sich ändernden Websitemesswerte bieten und als Diagnosetool bei Problemen dienen. Wenn Sie die neue API verwenden, freuen wir uns über Feedback in der Google-Gruppe „Chrome UX Report (Diskussions)“.
Danksagungen
Hero-Image von Dave Herring auf Unsplash