W tym przewodniku omawiamy punkt końcowy interfejsu API do raportowania użytkowania Chrome UX (CrUX), który udostępnia ciągi czasowe danych o wydajności stron. Dane te są aktualizowane co tydzień i pokazują historię z około 6 miesięcy z 25 punktami danych rozłożonymi w tygodniach.
W połączeniu z codziennymi aktualizacjami z pierwotnego punktu końcowego CrUX API możesz teraz szybko zobaczyć zarówno najnowsze dane, jak i wcześniejsze dane. Dzięki temu jest to zaawansowane narzędzie do obserwowania zmian na stronach internetowych na przestrzeni czasu.
Wysyłaj codzienne zapytania dotyczące interfejsu CrUX API
Aby podsumować poprzedni artykuł o interfejsie CrUX API, możesz uzyskać w ten sposób migawkę danych pól dotyczących określonego ź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 zrzut zawiera wartości gęstości histogramu i wartości percentyla dla danego 28-dniowego okresu gromadzenia 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, w poleceniu curl zmień queryRecord w adresie URL na queryHistoryRecord. Można użyć tego samego klucza interfejsu API raportu CrUX co 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 istnieje znacznie więcej danych. Zamiast pojedynczego punktu danych utworzono teraz ciągi czasowe dla pól zawierających wartości 75 centyla (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 ciąg czasowy densities dla zasobnika o długości od 0 do 2500 ms wskaźnika największe wyrenderowanie treści (LCP) to [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Każda z tych gęstości zaobserwowana podczas odpowiadającego mu wpisu collectionPeriods. Na przykład piąta gęstość (0,9183) dotyczyła piątego okresu gromadzenia danych, który kończy się 3 września 2022 r., a 0,9187 w okresie kończącym się w kolejnym tygodniu.
Inaczej mówiąc, po interpretacji ostatnich wpisów ciągu czasowego w przykładzie dla strony https://web.dev stwierdzono, że od 14 sierpnia do 10 września 2022 r. 91,87% wczytań stron miało wartości LCP mniejsze niż 2500 ms, 5,27% miało wartości od 2500 do 2000 ms – 0,4%, a wartości od 2500 ms do 2000 ms – 0,85 ms,
Analogicznie istnieje ciąg czasowy dla wartości p75: wartość LCP p75 dla okresu od 14 sierpnia 2022 r. do 10 września 2022 r. wynosił 1377. Oznacza to, że w tym okresie 75% wrażeń użytkowników miało LCP krótszy niż 1377 ms, a w 25% – wartość LCP większą niż 1377 ms.
W przykładzie podano tylko 6 wpisów ciągu czasowego i okresów zbierania, ale odpowiedzi z interfejsu API zawierają 25 wpisów. Daty zakończenia dla każdego z tych okresów zbierania danych to soboty w odstępach 7 dni, więc obejmuje to 6 miesięcy.
W każdej odpowiedzi długość ciągu czasowego dla gęstości bin histogramu i dla wartości p75 będzie dokładnie taka sama jak długość tablicy w polu collectionPeriods: istnieje korespondencja 1:1 w tych tablicach na podstawie indeksu.
Wysyłanie zapytań o dane na poziomie strony
Oprócz danych na poziomie źródła interfejs CrUX History API umożliwia dostęp do historycznych danych na poziomie strony. Dane na poziomie źródła były wcześniej dostępne za pomocą zbioru danych na temat użytkowania Chrome w BigQuery (lub za pomocą panelu raportu na temat użytkowania Chrome), ale dane historyczne na poziomie strony były dostępne tylko w przypadku, gdy witryny samodzielnie zbierały i przechowywały te dane. Nowy interfejs API umożliwia teraz dostęp do danych historycznych na poziomie strony.
Zapytania o dane na poziomie strony można wysyłać w ten sam sposób, ale używając w ładunku parametru 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 poziomu źródła) podlegają tym samym wymaganiom co reszta raportu na temat użytkowania Chrome. Z tego powodu strony mogą nie mieć pełnego rekordu historycznego. W takich przypadkach „brakujące” dane będą reprezentowane przez "NaN" dla gęstości histogramTimeseries i null dla percentilesTimeseries. Przyczyną tej różnicy jest to, że gęstości histogramu zawsze są liczbami, a percentylami mogą być liczbami lub ciągami znaków (w CLS używane są ciągi tekstowe, nawet jeśli wyglądają jak liczby).
Wizualizacja danych
Możesz się więc zastanawiać, dlaczego dane są ukształtowane w taki sposób. Stwierdzono, że ułatwia to rysowanie wykresów. Oto przykładowy wykres wartości p75 dla interakcji do kolejnego wyrenderowania (INP) dla strony https://web.dev:
Na tym wykresie liniowym każda wartość na osi Y to wartość p75 z ciągu czasowego p75s. Oś X to czas, który jest ustawiany jako lastDate dla każdego okresu zbierania danych.
Poniżej przedstawiamy wykres dla wykresu binarnego histogramu, nazywanego wykresem potrójnym, ponieważ zawiera on 3 przedziały czasowe.
Oś X jest skonfigurowana jako lastDate dla każdego okresu zbierania danych. Jednak tym razem oś Y przedstawia procent wczytań stron, które mieszczą się w konkretnym zakresie danych INP. Pokazuje on skumulowany wykres słupkowy. Wykres 75 zapewnia krótkie podsumowanie, a na jednym wykresie można stosunkowo łatwo dodać wiele danych lub pokazać linie dla PHONE i DESKTOP na jednym wykresie. Wykres potrójny pokazuje rozkład wartości danych zmierzonych w każdym okresie gromadzenia danych.
Na przykład wykres p75 sugeruje, że wartość INP na stronie https://web.dev była prawie akceptowalna w okresie obserwacji, ale wykres potrójny pokazuje, że w przypadku niewielkiego odsetka wczytań stron wartość INP była niska. Na obu wykresach można stosunkowo łatwo wywnioskować, że wystąpił pogorszenie skuteczności, który rozpoczął się pod koniec października, a został rozwiązany do połowy listopada.
Aby samodzielnie wygenerować takie wykresy, utworzyliśmy przykładową usługę Colab. Colab, lub inaczej „Colaboratory”, umożliwia pisanie i uruchamianie Pythona w przeglądarce. Interfejs CrUX History API w Colab (źródło) używa Pythona do wywoływania interfejsu API i tworzenia wykresów danych.
Dzięki tej usłudze Colab możesz tworzyć wykresy p75 i trójbinowe, pobierać dane w formie tabelarycznej oraz wyświetlać parę żądań i odpowiedzi dla interfejsu CrUX API. Wystarczy, że wypełnisz krótki formularz. Nie trzeba być programistą, aby z tego korzystać, ale z pewnością możesz zajrzeć do kodu Pythona i zmodyfikować go w coś niesamowitego. Życzymy dobrej zabawy i dzielimy się opiniami na jej temat.
Oczywiście nie musisz ograniczać się do Colab ani Pythona – to tylko jeden z przykładów użycia nowego interfejsu API. Punkt końcowy HTTP HTTP, oparty na formacie JSON, umożliwia wykonywanie zapytań z dowolnej technologii.
Podsumowanie
Przed wprowadzeniem punktu końcowego interfejsu CrUX History API właściciele witryn mieli ograniczoną ilość informacji historycznych, które mogli uzyskiwać z CrUX. W BigQuery i panelu CrUX dostępne były miesięczne dane na poziomie źródła, ale dane tygodniowe i historyczne na poziomie strony nie były dostępne. Właściciele witryn mogli samodzielnie rejestrować te dane za pomocą codziennego interfejsu API, ale często dało się zauważyć potrzebę takiego działania dopiero po regresji danych.
Interfejs CrUX History API ma nadzieję, że dzięki temu właściciele witryn będą mogli lepiej zrozumieć zmieniające się dane ich witryn, a także korzystać z narzędzia diagnostycznego w razie wystąpienia problemów. Jeśli używasz nowego interfejsu API, zachęcamy do przekazywania opinii na grupie dyskusyjnej Google dotyczącej Raportu na temat użytkowania Chrome (Dyskusje).
Podziękowania
Baner powitalny autorstwa Dave'a Herringa na kanale Unsplash