Dowiedz się, jak używać interfejsu Chrome UX Report API, aby uzyskać dostęp do danych o wrażeniach użytkowników korzystających z milionów stron internetowych.
Zbiór danych Raport na temat użytkowania Chrome (CrUX) pokazuje, w jaki sposób rzeczywiste osoby korzystają z popularnych stron internetowych w internecie. Od 2017 roku, gdy po raz pierwszy opublikowano w BigQuery zbiór danych, który można przeszukiwać, dane pól z CrUX zostały zintegrowane z narzędziami dla programistów takimi jak PageSpeed Insights, panel CrUX i raport dotyczący podstawowych wskaźników internetowych w Search Console. Dzięki temu deweloperzy mogą mierzyć i monitorować wrażenia użytkowników. Elementem, którego przez cały czas brakowało, było narzędzie zapewniające automatycznie bezpłatny, za pomocą architektury REST dostęp do danych raportu CrUX. Aby pomóc Ci wypełnić tę lukę, z przyjemnością ogłaszamy udostępnienie nowego interfejsu Chrome UX Report API.
Ten interfejs API został stworzony z myślą o zapewnieniu deweloperom prostego, szybkiego i kompleksowego dostępu do danych raportu na temat użytkowania Chrome. Interfejs CrUX API raportuje tylko pola danych o wrażeniach użytkowników, w odróżnieniu od dotychczasowego interfejsu PageSpeed Insights API, który raportuje też dane z laboratorium z audytów wydajności w Lighthouse. Interfejs CrUX API jest uproszczony i może szybko udostępniać dane dotyczące wrażeń użytkowników, dzięki czemu idealnie nadaje się do aplikacji kontrolnych w czasie rzeczywistym.
Aby deweloperzy mieli dostęp do wszystkich najważniejszych danych – podstawowych wskaźników internetowych – interfejs CrUX API kontroluje i monitoruje największe wyrenderowanie treści (LCP), opóźnienie przy pierwszym działaniu (FID) i skumulowane przesunięcie układu (CLS) zarówno na poziomie źródła, jak i na poziomie adresu URL.
Zobaczmy, jak z niej korzystać.
Zapytanie o dane punktu początkowego
Źródła w zbiorze danych raportu CrUX obejmują wszystkie podstawowe funkcje na poziomie strony. Poniższy przykład pokazuje, jak za pomocą narzędzia cURL w wierszu poleceń wysłać do interfejsu CrUX zapytanie o dane o wrażeniach użytkownika dotyczące ź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"}'
Polecenie curl
składa się z 3 części:
- Punkt końcowy URL interfejsu API, w tym prywatny klucz interfejsu API elementu wywołującego.
- Nagłówek
Content-Type: application/json
wskazujący, że treść żądania zawiera kod JSON. - Treść żądania zakodowana w formacie JSON, określająca źródło
https://web.dev
.
Aby zrobić to samo w skrypcie JavaScript, użyj narzędzia CrUXApiUtil
, które wykonuje wywołanie interfejsu API i zwraca zdekodowaną odpowiedź (więcej informacji, w tym historię i obsługę wsadową, znajdziesz w naszej wersji GitHuba).
const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
}
return fetch(CrUXApiUtil.API_ENDPOINT, {
method: 'POST',
body: JSON.stringify(requestBody)
}).then(response => response.json()).then(response => {
if (response.error) {
return Promise.reject(response);
}
return response;
});
};
Zastąp [YOUR_API_KEY]
swoim kluczem. Następnie wywołaj funkcję CrUXApiUtil.query
i przekaż obiekt żądania treści.
CrUXApiUtil.query({
origin: 'https://web.dev'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
Jeśli dla tego źródła istnieją dane, odpowiedź interfejsu API jest zakodowanym obiektem JSON zawierającym metrics reprezentujące rozkład wrażeń użytkowników. Dane rozkładu to przedziały histogramu i percentyle.
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.7925068547983514
},
{
"start": 2500,
"end": 4000,
"density": 0.1317422195536863
},
{
"start": 4000,
"density": 0.07575092564795324
}
],
"percentiles": {
"p75": 2216
}
},
// ...
}
}
}
Właściwości start
i end
obiektu histogram
reprezentują zakres wartości, które użytkownicy widzą w przypadku danego rodzaju danych. Właściwość density
reprezentuje odsetek wrażeń użytkowników w tym zakresie. W tym przykładzie 79% wrażenia użytkowników LCP na wszystkich stronach web.dev nie przekracza 2500 milisekund, co stanowi „dobry” próg LCP. Wartość percentiles.p75
oznacza,że 75% wrażeń użytkowników w tej dystrybucji trwa krócej niż 2216 milisekund. Więcej informacji o strukturze odpowiedzi znajdziesz w dokumentacji treści odpowiedzi.
Błędy
Gdy interfejs CrUX API nie ma żadnych danych o danym źródle, w odpowiedzi wyświetla komunikat o błędzie zakodowany w formacie JSON:
{
"error": {
"code": 404,
"message": "chrome ux report data not found",
"status": "NOT_FOUND"
}
}
Aby debugować ten błąd, najpierw sprawdź, czy żądane źródło jest dostępne publicznie. Aby to sprawdzić, wpisz adres źródła na pasku adresu przeglądarki i porównaj go z końcowym adresem URL po przekierowaniach. Typowe problemy to niepotrzebne dodanie lub pominięcie subdomeny i użycie niewłaściwego protokołu HTTP.
{"origin": "http://www.web.dev"}
{"origin": "https://web.dev"}
Jeśli żądane źródło to wersja z możliwością nawigowania, ten błąd może też wystąpić wtedy, gdy w źródle jest niewystarczająca liczba próbek. Wszystkie źródła i adresy URL uwzględnione w zbiorze danych muszą zawierać wystarczającą liczbę próbek, aby można było zanonimizować poszczególnych użytkowników. Dodatkowo źródła i adresy URL muszą być publicznie dostępne do indeksowania. Więcej informacji o sposobie uwzględniania witryn w zbiorze danych znajdziesz w sekcji Metodologia CrUX.
Wyślij zapytanie o dane adresu URL
Wiesz już, jak wysyłać zapytania do interfejsu CrUX API, aby uzyskać informacje o ogólnych wrażeniach użytkowników w źródle. Aby ograniczyć wyniki do konkretnej strony, użyj parametru żądania url
.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/fast/"}'
To polecenie cURL jest podobne do przykładu origin z tą różnicą, że w treści żądania, by wskazać stronę do wyszukania, treść żądania używa parametru url
.
Aby wysłać zapytanie o dane adresu URL z interfejsu CrUX API w JavaScript, wywołaj funkcję CrUXApiUtil.query
, korzystając z parametru url
w treści żądania.
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
Jeśli dane dotyczące tego adresu URL znajdują się w zbiorze danych CrUX, interfejs API zwróci odpowiedź zakodowaną w formacie JSON. Przykład
{
"record": {
"key": {
"url": "https://web.dev/fast/"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.8477304539092148
},
{
"start": 2500,
"end": 4000,
"density": 0.08988202359528057
},
{
"start": 4000,
"density": 0.062387522495501155
}
],
"percentiles": {
"p75": 1947
}
},
// ...
}
}
}
Wyniki pokazują, że https://web.dev/fast/
ma 85% „dobrych” wyników LCP i 75 centyl, który wynosi 1947 milisekund. Jest to nieco lepsze wyniki niż rozkład w całym źródle.
Normalizacja adresów URL
Interfejs CrUX API może znormalizować żądane adresy URL, aby lepiej pasowały do listy znanych adresów URL. Na przykład, ze względu na normalizację, odpytywanie o adres https://web.dev/fast/#measure-performance-in-the-field
spowoduje uzyskanie danych dla funkcji https://web.dev/fast/
. Gdy to nastąpi, do odpowiedzi zostanie dołączony obiekt urlNormalizationDetails
.
{
"record": {
"key": {
"url": "https://web.dev/fast/"
},
"metrics": { ... }
},
"urlNormalizationDetails": {
"normalizedUrl": "https://web.dev/fast/",
"originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
}
}
Więcej informacji o normalizacji adresów URL znajdziesz w dokumentacji raportu na temat użytkowania Chrome.
Zapytanie według formatu
Wygoda użytkowników może się znacznie różnić w zależności od optymalizacji witryny, warunków sieciowych i urządzeń użytkowników. Aby lepiej zrozumieć te różnice, przejdź do bardziej szczegółowego widoku skuteczności źródła i adresów URL za pomocą wymiaru formFactor
interfejsu CrUX API.
Interfejs API obsługuje 3 jawne wartości formatu: DESKTOP
, PHONE
i TABLET
. Oprócz źródła lub adresu URL określ jedną z tych wartości w treści żądania, aby ograniczyć wyniki tylko do tych treści dla użytkowników. Ten przykład pokazuje, jak przy użyciu cURL wysyłać zapytania do interfejsu API według formatu.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'
Aby za pomocą JavaScriptu wysłać zapytanie do interfejsu CrUX API o dane dotyczące konkretnego formatu, wywołaj funkcję CrUXApiUtil.query
, korzystając z parametrów url
i formFactor
w treści żądania.
CrUXApiUtil.query({
url: 'https://web.dev/fast/',
formFactor: 'PHONE'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
Pominięcie parametru formFactor
jest równoważne z żądaniem danych dla wszystkich formatów łącznie.
{
"record": {
"key": {
"url": "https://web.dev/fast/",
"formFactor": "PHONE"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.778631284916204
},
{
"start": 2500,
"end": 4000,
"density": 0.13943202979515887
},
{
"start": 4000,
"density": 0.08193668528864119
}
],
"percentiles": {
"p75": 2366
}
},
// ...
}
}
}
Pole key
odpowiedzi powtarza konfigurację żądania formFactor
, aby potwierdzić, że uwzględniane są tylko funkcje telefoniczne.
Przypomnijmy w poprzedniej sekcji, że 85% wrażeń użytkowników tej strony miało „dobry” wskaźnik LCP. Dla porównania w przypadku korzystania z telefonów tylko 78% uważa się za „dobre”. 75 centyl jest też wolniejszy podczas korzystania z telefonów – z 1947 milisekund do 2366 milisekund. Podział na segmenty według formatu może zwrócić uwagę na skrajne różnice w wrażeniach użytkowników.
Ocena skuteczności podstawowych wskaźników internetowych
Program Podstawowe wskaźniki internetowe określa cele, które pomagają określić, czy wrażenia użytkownika lub ich rozkład można uznać za „dobre”. W poniższym przykładzie używamy interfejsu CrUX API i funkcji CrUXApiUtil.query
, aby ocenić, czy dystrybucja podstawowych wskaźników internetowych (LCP, FID, CLS) na stronie jest dobra.
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
assessCoreWebVitals(response);
}).catch(response => {
console.error(response);
});
function assessCoreWebVitals(response) {
// See https://web.dev/vitals/#core-web-vitals.
const CORE_WEB_VITALS = [
'largest_contentful_paint',
'first_input_delay',
'cumulative_layout_shift'
];
CORE_WEB_VITALS.forEach(metric => {
const data = response.record.metrics[metric];
if (!data) {
console.log('No data for', metric);
return;
}
const p75 = data.percentiles.p75;
const threshold = data.histogram[0].end;
// A Core Web Vitals metric passes the assessment if
// its 75th percentile is under the "good" threshold.
const passes = p75 < threshold;
console.log(`The 75th percentile (${p75}) of ${metric} ` +
`${passes ? 'passes' : 'does not pass'} ` +
`the Core Web Vitals "good" threshold (${threshold}).`)
});
}
Z wyników wynika, że ta strona spełnia wszystkie 3 kryteria podstawowych wskaźników internetowych.
The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of first_input_delay passes the Core Web Vitals "good" threshold (100).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).
Dane pochodzące z CrUX w połączeniu z automatycznym sposobem monitorowania wyników interfejsu API można wykorzystać, aby zadbać o to, aby wrażenia użytkowników były szybkie i szybkie. Aby dowiedzieć się więcej o podstawowych wskaźnikach internetowych i sposobach ich pomiaru, zapoznaj się z artykułami Wskaźniki internetowe i Narzędzia do ich pomiaru.
Co dalej?
Funkcje dostępne we wstępnej wersji interfejsu CrUX API jedynie eksponują dane, które są dostępne w tym interfejsie. Użytkownicy zbioru danych na temat użytkowania Chrome w BigQuery mogą znać niektóre z bardziej zaawansowanych funkcji, w tym:
- Dodatkowe dane
first_paint
dom_content_loaded
onload
time_to_first_byte
notification_permissions
- Dodatkowe wymiary
month
country
effective connection type
(ECT)
- Dodatkowa szczegółowość
- szczegółowe histogramy
- więcej centylów
Zapoznaj się z oficjalnymi dokumentacją interfejsu API CrUX, aby uzyskać klucz interfejsu API i poznać więcej przykładowych aplikacji. Mamy nadzieję, że go wypróbujesz. Chętnie poznamy Twoją opinię i pytania. Skontaktuj się z nami na forum dyskusyjnym na temat użytkowania Chrome. Żeby być na bieżąco ze wszystkimi informacjami, które planujemy wprowadzić w interfejsie CrUX API, zasubskrybuj forum ogłoszeń na temat CrUX lub obserwuj nas na Twitterze: @ChromeUXReport.