Jak korzystać z interfejsu CrUX API

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.

Rick Viscomi

Shane Exterkamp

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

Uwaga: wszystkie żądania do interfejsu API muszą podawać wartość parametru key – w poprzednim przykładzie pole [YOUR_API_KEY] jest zmienną. 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:

1. Punkt końcowy URL interfejsu API, w tym prywatny klucz interfejsu API elementu wywołującego.
2. Nagłówek Content-Type: application/json wskazujący, że treść żądania zawiera kod JSON.
3. 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.

Błąd

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

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

Gotowe

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

To źródło jest dostępne publicznie.

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

Kluczowy termin: format to typ urządzenia, na którym użytkownik odwiedza stronę internetową. Typowe rodzaje urządzeń to komputery, telefony i tablety.

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.

Uwaga: im bardziej szczegółowe żądanie, np. konkretna kombinacja adresu URL i formatu, tym mniej wrażeń użytkowników. Może to powodować częstsze błędy typu „nie znaleziono”, zwłaszcza w przypadku zapytań o mniej popularne adresy URL lub mniej popularne tablety.

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

Ważne: interfejs API może być wywoływany tylko z jednym źródłem lub adresem URL naraz. Aby ocenić wiele witryn lub stron, utwórz osobne wywołania interfejsu API.

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.