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 prawdziwych użytkowników z milionów witryn.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Zbiór danych Raportu na temat użytkowania Chrome (CrUX) pokazuje, jak prawdziwi użytkownicy Chrome korzystają z popularnych miejsc docelowych w internecie. Od 2017 r., kiedy to w BigQuery udostępniliśmy pierwszy zestaw danych, które można było przeszukiwać, dane zgromadzone z CrUX są zintegrowane z narzędziami dla deweloperów, takimi jak PageSpeed Insights, oraz z raportem dotyczącym podstawowych wskaźników internetowych w Search Console. Dzięki temu deweloperzy mogą mierzyć i monitorować wrażenia użytkowników. Przez cały ten czas brakowało narzędzia, które zapewnia bezpłatny dostęp do danych CrUX za pomocą interfejsu REST API. Aby pomóc w przezwyciężeniu tej trudności, udostępniamy nowy interfejs Chrome UX Report API.

Ten interfejs API został stworzony z myślą o zapewnieniu programistom szybkiego i kompleksowego dostępu do danych CrUX. Interfejs CrUX API raportuje tylko dane o użytkowaniu, w przeciwieństwie do obecnego interfejsu PageSpeed Insights API, który raportuje też dane laboratoryjne z audytów wydajności Lighthouse. Interfejs CrUX API jest uproszczony i może szybko dostarczać dane o wygodzie użytkowników, dzięki czemu idealnie nadaje się do aplikacji do audytu w czasie rzeczywistym.

Aby zapewnić deweloperom dostęp do wszystkich najważniejszych wskaźników, czyli podstawowych wskaźników internetowych, interfejs CrUX API sprawdza i monitoruje największe wyrenderowanie treści (LCP), interakcję do kolejnego wyrenderowania (INP) i skumulowane przesunięcie układu (CLS) na poziomie źródła i adresu URL.

Zacznijmy więc i zobaczmy, jak z niego korzystać.

Wypróbuj interfejs API na tej stronie

Wypróbuj

Dane o źródle zapytania

Źródła w zbiorze danych CrUX obejmują wszystkie wrażenia użytkowników na poziomie strony. Poniższy przykład pokazuje, jak za pomocą polecenia curl w wierszu poleceń wysłać do interfejsu CrUX API zapytanie o dane dotyczące wygody użytkowników w przypadku danej domeny.

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:

  1. Adres URL punktu końcowego interfejsu API, w tym prywatny klucz interfejsu API wywołującego.
  2. Nagłówek Content-Type: application/json, który wskazuje, że treść żądania zawiera JSON.
  3. Zakodowana w formacie JSON treść żądania określająca https://web.dev pochodzenie.

Aby zrobić to samo w JavaScript, użyj narzędzia CrUXApiUtil, które wywołuje interfejs API i zwraca zdekodowaną odpowiedź (więcej funkcji, w tym obsługę historii i przetwarzania wsadowego, znajdziesz też w naszej wersji w GitHubie).

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 treści żądania.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Jeśli dla danego pochodzenia istnieją dane, interfejs API zwraca obiekt zakodowany w formacie JSON zawierający metriki reprezentujące rozkład wrażeń użytkowników. Dane o rozkładzie 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 uzyskują w przypadku danych. Właściwość density reprezentuje odsetek wrażeń użytkowników w danym zakresie. W tym przykładzie 79% wartości LCP na wszystkich stronach web.dev jest mniejszych niż 2500 milisekund, czyli mieści się w zakresie „dobrym”. Wartość percentiles.p75 oznacza,że 75% wrażeń użytkowników w tym rozkładzie jest krótszych niż 2216 milisekund. Więcej informacji o strukturze odpowiedzi znajdziesz w dokumentacji treści odpowiedzi.

Błędy

Gdy interfejs CrUX API nie ma danych o danym pochodzeniu, odpowiada zakodowanym w formacie JSON komunikatem o błędzie:

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

Aby rozwiązać ten problem, najpierw sprawdź, czy żądane źródło jest publicznie dostępne. Aby to sprawdzić, wpisz źródło na pasku adresu przeglądarki i porównaj je z końcowym adresem URL po 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"}

Ta domena jest dostępna publicznie.

Jeśli żądane źródło jest wersją, po której można się poruszać, ten błąd może też wystąpić, jeśli ź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 anonimizować poszczególnych użytkowników. Dodatkowo źródła i adresy URL muszą być dostępne do publicznego indeksowania. Więcej informacji o tym, jak witryny są uwzględniane w zbiorze danych, znajdziesz w metodologii CrUX.

Wykonywanie zapytań o dane z adresu URL

Wiesz już, jak wysyłać zapytania do interfejsu CrUX API, aby uzyskać ogólne informacje o ocenie funkcjonalności w przypadku danej domeny. 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 dotyczącego źródła, z tym wyjątkiem, że treść żądania używa parametru url do określenia strony, którą należy wyszukać.

Aby wysłać zapytanie o dane URL z interfejsu CrUX API w JavaScript, 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 dla 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
        }
      },
      // ...
    }
  }
}

Zgodnie z oczekiwaniami wyniki pokazują, że https://web.dev/fast/ ma 85% „dobrych” wyników LCP i 75 percentyl wynoszący 1947 milisekund, co jest nieco lepsze niż rozkład w całej domenie.

Normalizacja adresu URL

Interfejs CrUX API może normalizować żądane adresy URL, aby lepiej dopasować je do listy znanych adresów URL. Na przykład zapytanie o adres URL https://web.dev/fast/#measure-performance-in-the-field spowoduje zwrócenie danych dla adresu https://web.dev/fast/ ze względu na normalizację. W takim przypadku 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 CrUX.

Zapytania według formatu

Wrażenia użytkowników mogą 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, przeanalizuj szczegółowo skuteczność pochodzenia i adresu URL, korzystając z wymiaru formFactor interfejsu CrUX API.

Interfejs API obsługuje 3 wartości formatu: DESKTOP, PHONE i TABLET. Oprócz pochodzenia lub adresu URL podaj w treści żądania jedną z tych wartości, aby ograniczyć wyniki tylko do tych wrażeń użytkowników. Ten przykład pokazuje, jak wysyłać zapytania do interfejsu API według rodzaju urządzenia za pomocą polecenia 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 wysłać do interfejsu CrUX API zapytanie o dane dotyczące konkretnego typu urządzenia za pomocą JavaScriptu, 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 jest równoznaczne z żądaniem danych dla wszystkich typów urządzeń łą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 w odpowiedzi będzie odzwierciedlać konfigurację żądania formFactor, aby potwierdzić, że uwzględniono tylko urządzenia mobilne.

Z poprzedniej sekcji wiesz, że w 85% przypadków LCP na tej stronie było „dobre”. Dla porównania, tylko 78% funkcji na telefonach jest uznawanych za „dobre”. 75 percentyl jest też wolniejszy na telefonach – wzrósł z 1947 milisekund do 2366 milisekund. Segmentowanie według rodzaju urządzenia może uwidocznić większe różnice w sposobie korzystania z usługi przez użytkowników.

Ocena wyników podstawowych wskaźników internetowych

Program Podstawowe wskaźniki internetowe określa wartości docelowe, które pomagają ustalić, czy wrażenia użytkowników lub ich rozkład można uznać za „dobre”. W tym przykładzie używamy interfejsu CrUX API i funkcji CrUXApiUtil.query, aby ocenić, czy rozkład danych dotyczących podstawowych wskaźników internetowych (LCP, INP, CLS) na stronie 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/articles/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 wymagania dotyczące wszystkich 3 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 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 monitorowaniem wyników interfejsu API dane z CrUX mogą służyć do zapewnienia, że użytkownicy szybko i niezawodnie korzystają z witryny. Więcej informacji o podstawowych wskaźnikach internetowych i sposobach ich pomiaru znajdziesz w artykułach Web Vitals i Narzędzia do pomiaru podstawowych wskaźników internetowych.

Co dalej?

Funkcje zawarte w początkowej wersji interfejsu CrUX API to tylko niewielka część statystyk, które można uzyskać za pomocą CrUX. 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
  • Dodatkowa szczegółowość
    • szczegółowe histogramy,
    • więcej percentyli,

Aby uzyskać klucz interfejsu API i poznać więcej przykładowych aplikacji, zapoznaj się z oficjalną dokumentacją interfejsu CrUX API. Mamy nadzieję, że wypróbujesz tę funkcję. Jeśli masz pytania lub uwagi, skontaktuj się z nami na forum dyskusyjnym CrUX. Aby być na bieżąco ze wszystkimi planowanymi zmianami w interfejsie CrUX API, zasubskrybuj forum ogłoszeń CrUX lub obserwuj nas na Twitterze – @ChromeUXReport.