Data publikacji: 7 lutego 2023 r., ostatnia aktualizacja: 11 kwietnia 2025 r.
W tym przewodniku przedstawiamy punkt końcowy interfejsu Chrome UX Report (CrUX) History API, który udostępnia serie czasowe danych o wydajności witryny. Dane te są aktualizowane co tydzień i umożliwiają wyświetlanie historii z okresu około 6 miesięcy z 40 punktami danych rozłożonymi w odstępach tygodniowych.
W połączeniu z codziennymi aktualizacjami z oryginalnego punktu końcowego CrUX API możesz teraz szybko sprawdzać zarówno najnowsze dane, jak i informacje o tym, co wydarzyło się wcześniej. Dzięki temu jest to przydatne narzędzie do śledzenia zmian na stronach internetowych w czasie.
Wypróbuj interfejs API na tej stronie
Wysyłanie zapytań do interfejsu Daily CrUX API
Jak wspomnieliśmy w poprzednim artykule o interfejsie CrUX API, w ten sposób możesz uzyskać migawkę danych z terenu dla konkretnego źródła:
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 }
}
}
}
Ten przegląd zawiera wartości gęstości histogramu i wartości procentowe dla konkretnego 28-dniowego okresu zbierania danych, w tym przypadku od 27 grudnia 2022 r. do 23 stycznia 2023 r.
Wysyłanie zapytań do interfejsu CrUX History API
Aby wywołać punkt końcowy historii, zmień queryRecord w adresie URL na queryHistoryRecord w poleceniu curl. Użycie tego samego klucza interfejsu CrUX API co w przypadku poprzedniego wywołania będzie działać.
collectionPeriodCount określa liczbę wpisów w ciągu czasowym do zwrócenia; maksymalna wartość to 40. Jeśli nie podasz żadnej wartości, domyślnie zostanie użyta wartość 25.
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", "collectionPeriodCount": 40}'
Ogólny kształt odpowiedzi jest podobny, ale zawiera ona znacznie więcej danych. Zamiast pojedynczego punktu danych są teraz dostępne ciągi czasowe dla pól zawierających wartości 75 percentyla (p75) i gęstości histogramu.
{
"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 }
}
]
}
}
W tym przykładzie szereg czasowy densities dla przedziału od 0 do 2500 ms wskaźnika największego wyrenderowania treści (LCP) to [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Każda z tych gęstości została zaobserwowana w odpowiednim wpisie collectionPeriods. Na przykład piąta gęstość, 0,9183, była gęstością w piątym okresie zbierania danych, który zakończył się 3 września 2022 r., a 0,9187 była gęstością w okresie, który zakończył się w tydzień później.
Innymi słowy, interpretując ostatnie wpisy w przykładzie szeregu czasowego dla https://web.dev, stwierdzono, że od 14 sierpnia 2022 r. do 10 września 2022 r. 91,87% wczytań strony miało wartości LCP mniejsze niż 2500 ms, 5,27% – wartości między 2500 ms a 4000 ms, a 2,85% – wartości większe niż 4000 ms.
Podobnie istnieje szereg czasowy dla wartości p75: wartość LCP p75 od 14 sierpnia 2022 r. do 10 września 2022 r. wynosiła 1377. Oznacza to, że w tym okresie zbierania danych 75% użytkowników miało wartość LCP mniejszą niż 1377 ms, a 25% użytkowników miało wartość LCP większą niż 1377 ms.
W przykładzie wymieniono tylko 6 pozycji w ciągu czasowym i okresów zbierania danych, ale odpowiedzi z interfejsu API domyślnie zawierają 25 pozycji w ciągu czasowym, a maksymalnie 40 – gdy w żądaniu określono wartość "collectionPeriodCount": 40. Daty zakończenia każdego z tych okresów zbierania danych to soboty, które dzieli 7 dni, a "collectionPeriodCount": 40 obejmuje 10 miesięcy.
W każdej odpowiedzi długość szeregu czasowego dla gęstości przedziałów histogramu i wartości p75 będzie dokładnie taka sama jak długość tablicy w polu collectionPeriods: istnieje korespondencja jeden do jednego na podstawie indeksu w tych tablicach.
Wykonywanie zapytań o dane na poziomie strony
Interfejs CrUX History API umożliwia dostęp do danych historycznych na poziomie strony, a także do danych na poziomie źródła. Dane na poziomie źródła były wcześniej dostępne w zbiorze danych CrUX w BigQuery, ale dane historyczne na poziomie strony były dostępne tylko wtedy, gdy witryny same je zbierały i przechowywały. Nowy interfejs API odblokowuje teraz historyczne dane na poziomie strony.
O dane na poziomie strony można wysyłać zapytania w ten sam sposób, ale w ładunku należy użyć url zamiast origin:
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/"}'
Dane historyczne na poziomie strony (i źródła) podlegają tym samym wymaganiom co pozostałe dane CrUX, więc w przypadku niektórych stron może nie być pełnej historii. W takich przypadkach dane „brakujące” będą reprezentowane przez symbol "NaN" w przypadku gęstości histogramTimeseries i symbol null w przypadku percentilesTimeseries. Różnica wynika z tego, że gęstości histogramu są zawsze liczbami, a percentyle mogą być liczbami lub ciągami znaków (CLS używa ciągów znaków, nawet jeśli wyglądają jak liczby).
Wizualizacja danych
Najłatwiejszym sposobem wizualizacji danych jest CrUX Vis, czyli narzędzie stworzone specjalnie po to, aby pokazać możliwości interfejsu CrUX History API. Więcej informacji znajdziesz w dokumentacji CrUX Vis.
Aby samodzielnie wygenerować podobne wykresy, utworzyliśmy przykładowy Colab. Colab, czyli „Colaboratory”, umożliwia pisanie i wykonywanie kodu w języku Python bezpośrednio w przeglądarce. CrUX History API Colab (źródło) używa Pythona do wywoływania interfejsu API i tworzenia wykresów danych.
Ten Colab umożliwia tworzenie wykresów p75 i wykresów trójdzielnych, uzyskiwanie danych w formie tabelarycznej oraz wyświetlanie pary żądanie – odpowiedź dla interfejsu CrUX API po wypełnieniu krótkiego formularza. Nie musisz być programistą, aby z niego korzystać, ale możesz przejrzeć kod w Pythonie i zmodyfikować go w taki sposób, aby uzyskać niesamowite efekty. Zapoznaj się z nimi i nie wahaj się podzielić z nami swoją opinią.
Oczywiście nie musisz korzystać z Colab ani Pythona. To tylko jeden z przykładów użycia tego nowego interfejsu API. Interfejs API jest punktem końcowym HTTP opartym na JSON, więc można go używać w dowolnej technologii.
Podsumowanie
Przed wprowadzeniem punktu końcowego CrUX History API właściciele witryn mieli ograniczony dostęp do historycznych informacji z CrUX. Miesięczne dane na poziomie źródła były dostępne w BigQuery, ale dane tygodniowe i dane historyczne na poziomie strony nie były dostępne. Właściciele witryn mogą rejestrować te dane samodzielnie za pomocą interfejsu API, ale często potrzeba ta pojawia się dopiero po spadku wartości wskaźników.
Wprowadzenie tego interfejsu CrUX History API ma na celu umożliwienie właścicielom witryn lepszego zrozumienia zmieniających się danych witryny oraz wykorzystanie go jako narzędzia diagnostycznego w przypadku wystąpienia problemów. Jeśli korzystasz z nowego interfejsu API, możesz przesłać opinię na grupie dyskusyjnej Chrome UX Report.
Podziękowania
Baner powitalny autorstwa Dave’a Herringa z Unsplash