Ten przewodnik przedstawia interfejs Chrome UX Report (CrUX) History API, który udostępnia serię czasową danych o wydajności witryn. 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 z poprzedniego artykułu 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 percentylowe za określony 28-dniowy okres zbierania danych, 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 komendach 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 są teraz dostępne 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 odpowiedniego wpisu collectionPeriods. Na przykład piąta gęstość, 0,9183, była gęstością w 5 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ę tydzień później.
Inaczej mówiąc, na podstawie interpretacji ostatnich wpisów w serii czasowej w przykładzie dotyczącym witryny https://web.dev stwierdzono, że od 14 sierpnia 2022 r. do 10 września 2022 r. 91, 87% wczytanych stron miało wartości LCP mniejsze niż 2500 ms, 5, 27% wartości między 2500 a 4000 ms, a 2, 85% wartości większe 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) był krótszy niż 1377 ms, a w przypadku 25% użytkowników – dłuższy 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 dokładne 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 za pomocą zbioru danych CrUX w BigQuery (lub za pomocą panelu CrUX), ale dane historyczne na poziomie strony były dostępne tylko wtedy, gdy strony same zbierały i przechowywały dane. 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 wartość null dla 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 czasowej histogramu z 3 przedziałami, czyli 3 histogramami, ponieważ mają 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 przedziałami 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 można stosunkowo łatwo zauważyć, że na przełomie października i listopada nastąpiła regresja wydajności, która została naprawiona 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 (źródło) 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 przyjemnego korzystania 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 może być używany do wysyłania zapytań z użyciem dowolnej 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 Daily API, ale często potrzeba ich występowała dopiero po regresji danych.
Mamy nadzieję, że wprowadzenie 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