Ta strona została przetłumaczona przez Cloud Translation API.

Jak korzystać z interfejsu CrUX API

Dowiedz się, jak używać interfejsu Chrome UX Report API, aby uzyskać dostęp do rzeczywistych danych o wrażeniach użytkowników w milionach witryn.

Rick Viscomi

Shane Exterkamp

Zbiór danych Raport na temat użytkowania Chrome (CrUX) przedstawia, jak prawdziwi użytkownicy Chrome korzystają z popularnych miejsc docelowych w internecie. Od 2017 roku, gdy po raz pierwszy udostępniono w BigQuery zbiór danych, do którego można utworzyć zapytania, dane pól z raportu CrUX zostały zintegrowane z takimi 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 w czasie rzeczywistym. Tym razem brakowało narzędzia, które umożliwia programistyczny bezpłatny, RESTowy dostęp do danych raportu CrUX. Z przyjemnością informujemy o udostępnieniu zupełnie nowego interfejsu Chrome UX Report API.

Ten interfejs API został stworzony z myślą o zapewnieniu deweloperom łatwego, szybkiego i kompleksowego dostępu do danych raportu CrUX. Interfejs CrUX API raportuje tylko dane o wrażeniach użytkowników pochodzące z pola, w przeciwieństwie do dotychczasowego interfejsu PageSpeed Insights API, który raportuje też dane lab z kontroli wydajności Lighthouse. Interfejs CrUX API jest uproszczony i może szybko obsługiwać dane dotyczące wrażeń użytkowników, dzięki czemu idealnie nadaje się do obsługi aplikacji kontroli w czasie rzeczywistym.

Aby deweloperzy mieli dostęp do wszystkich najważniejszych wskaźników – podstawowych wskaźników internetowych – interfejsu API CrUX przeprowadza kontrolę i monitorowanie: największe wyrenderowanie treści (LCP), interakcja z następnym wyrenderowaniem (INP) oraz skumulowane przesunięcie układu (CLS) na poziomie źródła i adresu URL.

Przyjrzyjmy się zatem i sprawdźmy, jak z tego korzystać.

Zapytanie o dane punktu początkowego

Źródła w zbiorze danych CrUX obejmują wszystkie podstawowe funkcje na poziomie strony. Z przykładu poniżej dowiesz się, jak wysyłać do interfejsu CrUX API zapytania o dane dotyczące wrażeń użytkowników źródła za pomocą polecenia cURL w wierszu poleceń.

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"}'

Uwaga: wszystkie żądania do interfejsu API muszą podawać wartość parametru key – w poprzednim przykładzie [YOUR_API_KEY] jest pozostawiany jako zmienna. Wygeneruj własny prywatny klucz interfejsu CrUX API zgodnie z opisem w dokumentacji interfejsu CrUX API.

Polecenie curl składa się z 3 części:

Punkt końcowy URL interfejsu API, w tym prywatny klucz interfejsu API wywołującego.
Nagłówek Content-Type: application/json, który wskazuje, że treść żądania zawiera plik JSON.
Treść żądania zakodowana w formacie JSON określająca źródło https://web.dev.

Aby zrobić to samo w języku JavaScript, użyj narzędzia CrUXApiUtil. który wywołuje interfejs API i zwraca zdekodowaną odpowiedź (zobacz też wariant GitHuba , aby uzyskać więcej funkcji, w tym historię i obsługę zbiorczą).

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 body body (Treść żądania).

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 to obiekt zakodowany w formacie JSON zawierający dane reprezentujące rozkład doświadczeń użytkownika. Wskaźniki rozkładu to przedziały i percentyle histogramu.

{
  "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, jakie użytkownicy widzą w przypadku poszczególnych danych. Właściwość density reprezentuje odsetek wrażeń użytkowników w danym zakresie. W tym przykładzie 79% wyświetleń zrealizowanych przez użytkowników LCP na wszystkich stronach web.dev trwa mniej niż 2500 milisekund, co stanowi „dobrą” wartość”. Próg LCP. Wartość percentiles.p75 oznacza,że 75% wrażeń użytkowników w przypadku tego rozkładu 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 dotyczących danego punktu początkowego, odpowiada komunikatowi o błędzie zakodowanym 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 miejsce początkowe jest dostępne publicznie. Aby to sprawdzić, wpisz źródło pochodzenia na pasku adresu przeglądarki i porównaj je z końcowym adresem URL po wszystkich przekierowaniach. Typowe problemy to niepotrzebne dodawanie lub pomijanie subdomeny oraz używanie nieprawidłowego protokołu HTTP.

Błąd

{"origin": "http://www.web.dev"}

To źródło nieprawidłowo zawiera protokół http:// i subdomenę www..

Sukces

{"origin": "https://web.dev"}

Po tym punkcie początkowym można poruszać się publicznie.

Jeśli żądanym źródłem jest wersja możliwa do nawigacji, ten błąd może też wystąpić, gdy źródło ma niewystarczającą liczbę próbek. Wszystkie źródła i adresy URL uwzględnione w zbiorze danych muszą mieć 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ć dostępne publicznie do indeksowania. Więcej informacji o uwzględnianiu witryn w zbiorze danych znajdziesz w metodologii raportu na temat użytkowania Chrome.

Dane dotyczące adresów URL zapytań

Wiesz już, jak wysyłać zapytania do interfejsu CrUX API w celu uzyskania ogólnych wrażeń 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 źródła, z tym że treść żądania używa parametru url, aby wskazać stronę, którą chcesz wyszukać.

Aby w JavaScripcie przesłać zapytanie o dane URL do interfejsu CrUX API, wywołaj funkcję CrUXApiUtil.query, używając 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 o tym adresie URL są dostępne 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
        }
      },
      // ...
    }
  }
}

Jeśli wynik jest zgodny z prawdą, wyniki pokazują, że wynik „https://web.dev/fast/” jest „dobry” w 85% LCP i 75 centyl wynoszący 1947 milisekund, co jest nieco lepszym wynikiem niż w przypadku całego miejsca źródłowego.

Normalizacja adresu URL

Interfejs CrUX API może znormalizować żądane adresy URL, aby lepiej dopasować je do listy znanych adresów URL. Na przykład w wyniku normalizacji zapytanie o adres URL https://web.dev/fast/#measure-performance-in-the-field skutkuje zwróceniem danych dotyczących adresu https://web.dev/fast/. Gdy tak się stanie, w odpowiedzi zostanie uwzględniony 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 zależności użytkowników urządzenia. Aby lepiej zrozumieć te różnice, przeanalizuj szczegółowo dane o źródle i skuteczności adresów URL za pomocą wymiaru formFactor interfejsu CrUX API.

Interfejs API obsługuje 3 jednoznaczne 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 elementów, z których korzystają użytkownicy. Ten przykład pokazuje, jak tworzyć zapytania do interfejsu API za pomocą formatu cURL.

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ć do interfejsu CrUX API zapytanie o dane dotyczące konkretnego formatu, wywołaj funkcję CrUXApiUtil.query, używając 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 oznacza żądanie 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ędnione są tylko funkcje telefonu.

Jak wspominaliśmy w poprzedniej sekcji, 85% odczuć użytkowników na tej stronie było „dobrych”. LCP. Porównaj to z wygodą obsługi telefonów, z czego tylko 78% uznaje się za „dobrych”. 75 centyl jest też wolniejszy w przypadku telefonów – z 1947 do 2366 milisekund. Podział na segmenty według formatu może uwydatnić bardziej skrajne różnice w wrażeniach użytkowników.

Ocena wydajności podstawowych wskaźników internetowych

Program Podstawowe wskaźniki internetowe określa wartości docelowe, które pomagają określić, czy wrażenia użytkowników lub ich dystrybucja można uznać za „dobrą”. W poniższym przykładzie używamy interfejsu CrUX API i funkcji CrUXApiUtil.query, aby ocenić, czy rozkład podstawowych wskaźników internetowych (LCP, INP, CLS) strony internetowej jest „dobry”.

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',
    'interaction_to_next_paint',
    '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}).`)
  });
}

Wyniki pokazują, że ta strona spełnia wszystkie 3 podstawowe wskaźniki internetowe.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

W połączeniu z automatycznym sposobem monitorowania wyników interfejsu API dane z raportu CrUX mogą pomóc zapewnić szybkie i szybkie działanie użytkownikom. Więcej informacji o podstawowych wskaźnikach internetowych i sposobach ich pomiaru znajdziesz w artykułach Wskaźniki internetowe i Narzędzia do pomiaru tych wskaźników.

Co dalej?

Funkcje zawarte w pierwszej wersji interfejsu CrUX API to tylko wierzchołek góry lodowej, jeśli chodzi o możliwości, jakie oferuje ten interfejs. Użytkownicy zbioru danych CRUX w BigQuery mogą znać niektóre z bardziej zaawansowanych funkcji, takich jak:

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 centyli

Aby uzyskać klucz interfejsu API i poznać więcej przykładowych aplikacji, zapoznaj się z oficjalną dokumentacją interfejsu API CrUX. Mamy nadzieję, że wypróbujesz tę usługę. Chętnie poznamy Twoją opinię na jej temat. Skontaktuj się z nami na forum dyskusyjnym na temat użytkowania Chrome. Żeby być na bieżąco ze wszystkimi planami dotyczącymi interfejsu CrUX API, zasubskrybuj forum poświęcone ogłoszeniem na temat Chrome lub obserwuj nas na Twitterze: @ChromeUXReport.