Ten przewodnik przedstawia interfejs Chrome UX Report (CrUX) History API, który udostępnia serię czasową danych o wydajności witryny. Dane te są aktualizowane co tydzień i pozwalają zobaczyć historię obejmującą około 6 miesięcy z 25 punktami danych rozmieszczonymi co tydzień.
Dzięki codziennym aktualizacjom z pierwotnego punktu końcowego interfejsu CrUX API możesz teraz szybko sprawdzać najnowsze dane i informacje o tym, co działo się wcześniej. Dzięki temu możesz dokładnie obserwować zmiany w witrynie na przestrzeni czasu.
Wypróbuj interfejs API na tej stronie
Wysyłanie zapytań do dziennego interfejsu CrUX API
Przypominamy, że w poprzednim artykule na temat interfejsu CrUX API można w ten sposób uzyskać migawkę danych polowych 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 percentylów w okresie zbierania danych obejmującym 28 dni, w tym przypadku od 27 grudnia 2022 r. do 23 stycznia 2023 r.
Wysyłanie zapytania do interfejsu CrUX History API
Aby wywołać punkt końcowy historii, w poleceniu curl zmień queryRecord na queryHistoryRecord w adresie URL. Użyj tego samego klucza interfejsu API Crux, którego użyto w poprzednim wywołaniu.
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"}'
Ogólny kształt odpowiedzi jest podobny, ale zawiera znacznie więcej danych. Zamiast pojedynczego punktu danych mamy teraz ciągi czasowe pól zawierających 75. percentyl (p75) i wartości 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 seria densities dla zakresu 0–2500 ms wskaźnika największego wyrenderowania treści (LCP) wynosi [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Każda z tych gęstości została zaobserwowana podczas odpowiadającego wpisu collectionPeriods. Na przykład gęstość 5, równa 0,9183, była gęstością w 5 okresie zbierania danych, który zakończył się 3 września 2022 r., a gęstość 6, równa 0,9187, była gęstością w okresie, który zakończył się tydzień później.
Inaczej mówiąc, na podstawie ostatnich wpisów serii czasowych w przykładzie dotyczącym witryny https://web.dev stwierdziliśmy, że od 14 sierpnia do 10 września 2022 r. 91, 87% wczytanych stron miało wartość LCP mniejszą niż 2500 ms, 5, 27% wartość między 2500 a 4000 ms, a 2, 85% wartość większą niż 4000 ms.
Podobnie jest w przypadku serii czasowych wartości p75: w okresie od 14 sierpnia do 10 września 2022 r. mediana LCP wynosiła 1377. Oznacza to, że w tym okresie w przypadku 75% użytkowników średni czas wczytywania (LCP) wynosił mniej niż 1377 ms, a w przypadku 25% użytkowników – więcej niż 1377 ms.
Przykład zawiera tylko 6 rekordów i okresów zbierania danych, ale odpowiedzi z interfejsu API zawierają 25 rekordów. Ponieważ daty zakończenia każdego z tych okresów zbierania danych przypadają w soboty w odstępie 7 dni, obejmują one 6 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 jednoznaczne powiązanie na podstawie indeksu tych tablic.
Wykonywanie zapytań dotyczących danych na poziomie strony
Oprócz danych na poziomie pochodzenia interfejs CrUX History API umożliwia też dostęp do historycznych danych na poziomie strony. Dane na poziomie pochodzenia były wcześniej dostępne w zbiorze danych CrUX w BigQuery (lub za pomocą panelu CrUX), ale dane historyczne na poziomie strony były dostępne tylko wtedy, gdy strony same je zbierały i przechowywały. Nowy interfejs API umożliwia teraz dostęp do historycznych danych na poziomie strony.
Dane na poziomie strony można wyszukiwać w taki sam sposób, ale z użyciem w pliku danych wartości 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 na poziomie pochodzenia) podlegają tym samym wymaganiom co pozostałe dane w CrUX, dlatego strony mogą nie mieć pełnego zapisu historycznego. W takich przypadkach dane „brakujące” będą reprezentowane przez wartość "NaN" dla gęstości histogramTimeseries i null dla gęstości percentilesTimeseries. Różnica polega na tym, że gęstości histogramu są zawsze liczbami, a procentyle 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
Możesz się zastanawiać, dlaczego dane mają taki kształt. Okazało się, że ułatwia to tworzenie wykresów. Oto na przykład wykres wartości p75 interakcji do kolejnego wyrenderowania (INP) w przypadku witryny https://web.dev:
Na tym wykresie liniowym każda wartość na osi Y to wartość p75 z ciągu czasowego p75s, a na osi X jest ustawiony czas, który jest ustawiony jako lastDate dla każdego okresu zbierania danych.
Oto wykres serii czasowych histogramu z 3 przedziałami, czyli 3-przedziałowego, ponieważ zawiera 3 przedziały.
Oś X jest ustawiona jako lastDate dla każdego okresu zbierania danych. Tym razem oś Y to odsetek wczytań stron, które mieszczą się w określonym zakresie danych INP, przedstawiony na wykresie słupkowym. Wykres p75 zapewnia szybki przegląd danych. Na jednym wykresie możesz łatwo dodawać wiele rodzajów danych lub wyświetlać linie dla PHONE i DESKTOP. Wykres z 3 kategoriami przedstawia rozkład wartości danych zmierzonych w każdym okresie zbierania danych.
Na przykład mimo że wykres p75 sugeruje, że w okresie obserwacji witryna https://web.dev miała prawie dopuszczalne wartości INP, wykres z 3 zakresami pokazuje, że w przypadku niewielkiej części wczytanych stron INP był w rzeczywistości niski. Na obu wykresach stosunkowo łatwo zauważyć, że nastąpił regres wydajności, który zaczął się pod koniec października i został naprawiony w połowie listopada.
Aby samodzielnie generować takie wykresy, możesz skorzystać z przykładowego pliku Colab. Colab, czyli „Colaboratory”, umożliwia pisanie i wykonywanie kodu Python bezpośrednio w przeglądarce. CrUX History API Colab (source) używa Pythona do wywoływania interfejsu API i tworzenia wykresów danych.
Ten dokument Colab umożliwia tworzenie wykresów p75 i wykresów trójkątnych, uzyskiwanie danych w formie tabelarycznej oraz wyświetlanie pary żądania i odpowiedzi dla interfejsu CrUX API. Aby z niego skorzystać, musisz wypełnić krótki formularz. Aby z niego korzystać, nie musisz być programistą, ale możesz zapoznać się z kodem Pythona i zmodyfikować go, aby uzyskać niesamowite efekty. Życzymy przyjemnej zabawy i zapraszamy do dzielenia się opiniami na temat znalezionych informacji.
Oczywiście nie musisz ograniczać się do Colab ani Pythona. To tylko jeden z dostępnych przykładów korzystania z nowego interfejsu API. Jako punkt końcowy HTTP oparty na JSON interfejs API jest dostępny z jakiejkolwiek technologii.
Podsumowanie
Przed wprowadzeniem punktu końcowego interfejsu CrUX History API właściciele witryn mieli ograniczony dostęp do informacji historycznych, które mogły być pobierane z raportu CrUX. Dane miesięczne na poziomie pochodzenia były dostępne za pomocą BigQuery i panelu CrUX, ale nie były dostępne dane tygodniowe ani dane historyczne na poziomie strony. Właściciele witryn mogli samodzielnie rejestrować te dane za pomocą interfejsu dziennego API, ale często potrzeba ich występowała dopiero po regresji danych.
Mamy nadzieję, że wprowadzenie tego interfejsu CrUX History API pozwoli właścicielom witryn lepiej zrozumieć zmieniające się dane o witrynie i będzie służyć jako narzędzie diagnostyczne w przypadku problemów. Jeśli używasz nowego interfejsu API, możesz przesłać opinię w grupie Chrome UX Report (Discussions) w Google Groups.
Podziękowania
Baner powitalny autorstwa Dave Herring na Unsplash