Jak korzystać z interfejsu CrUX API

Dowiedz się, jak korzystać z interfejsu API raportu na temat użytkowania Chrome, aby uzyskać dostęp do danych o wrażeniach prawdziwych użytkowników na milionach witryn.

Rick Viscomi

Shane Exterkamp

Dane z raportu na temat użytkowania Chrome (CrUX) pokazują, jak popularne strony w internecie działają z perspektywy prawdziwych użytkowników Chrome. Od 2017 r., kiedy udostępniliśmy w BigQuery zbiór danych, do którego można kierować zapytania, dane zgromadzone przez CrUX zostały zintegrowane z narzędziami dla deweloperó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. Przez cały ten czas brakowało narzędzia, które zapewniałoby bezpłatny dostęp do danych CrUX w ramach interfejsu REST. Aby pomóc w tym zakresie, ogłaszamy wydanie zupełnie nowego interfejsu API raportów na temat UX w Chrome.

Ten interfejs API został stworzony, aby zapewnić deweloperom prosty, szybki i wszechstronny dostęp do danych CrUX. Interfejs CrUX API raportuje tylko dane o doświadczeniach użytkowników na podstawie danych zgromadzonych, w przeciwieństwie do dotychczasowego interfejsu PageSpeed Insights API, który raportuje też dane laboratoryjne z audytów wydajności Lighthouse. Interfejs CrUX API jest usprawniony i może szybko dostarczać dane o wrażeniach użytkowników, dzięki czemu doskonale nadaje się do aplikacji do audytu w czasie rzeczywistym.

Aby zapewnić deweloperom dostęp do wszystkich najważniejszych danych, czyli podstawowych wskaźników internetowych, interfejs CrUX API sprawdza i monitoruje wyrenderowanie największej części treści (LCP), czas do kolejnego wyrenderowania (INP) i skumulowane przesunięcie układu (CLS) zarówno na poziomie pochodzenia, jak i adresu URL.

Zobaczmy, jak z niego korzystać.

Wypróbuj interfejs API na tej stronie

Wypróbuj

Zapytania o dane źródła

Źródła w zbiorze danych CrUX obejmują wszystkie wrażenia na poziomie strony. Ten przykład pokazuje, jak za pomocą cURL-a w wierszu poleceń wykonać zapytanie do interfejsu CrUX API o dane dotyczące wygody użytkowników witryny źródłowej.

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 interfejsu API muszą zawierać wartość parametru key. W poprzednim przykładzie parametr [YOUR_API_KEY] jest podany jako element zastępczy. Uzyskaj 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. Adres URL punktu końcowego interfejsu API, w tym klucz prywatny interfejsu API wywołującego.
2. Nagłówek Content-Type: application/json, który wskazuje, że treść żądania zawiera dane w formacie JSON.
3. Treść żądania zakodowana w formacie JSON, która określa https://web.dev.

Aby zrobić to samo w JavaScript, użyj narzędzia CrUXApiUtil, które wykonuje wywołanie interfejsu API i zwraca odkodowaną odpowiedź (więcej funkcji, w tym obsługę historii i wykonywanych w grupach, znajdziesz w naszym wariancie na GitHub).

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, przekazując obiekt request body.

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

Jeśli istnieją dane dotyczące tego źródła, odpowiedź interfejsu API to obiekt zakodowany w formacie JSON, który zawiera dane przedstawiające rozkład doświadczeń użytkowników. Dane rozkładu to grupy 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 danych. Właściwość density przedstawia odsetek wrażeń użytkowników w danym zakresie. W tym przykładzie 79% LCP na wszystkich stronach web.dev ma czas poniżej 2500 milisekund, co jest dobrym progiem LCP. Wartość percentiles.p75 oznacza,że w ramach tej dystrybucji 75% użytkowników ma czas krótszy 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 źródła, odpowiada komunikatem 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 żądany adres domeny jest publicznie dostępny. Aby to sprawdzić, wpisz adres docelowy na pasku adresu przeglądarki i porównaj go z końcowym adresem URL po wszystkich przekierowaniach. Typowe problemy to niepotrzebne dodawanie lub pomijanie subdomeny oraz używanie niewłaściwego protokołu HTTP.

Błąd

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

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

Sukces

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

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

Jeśli żądany źródłowy plik audio to wersja z możliwością nawigacji, ten błąd może wystąpić również wtedy, gdy źródło ma niewystarczającą liczbę próbek. Wszystkie źródła i adresy URL zawarte w danym zbiorze danych muszą mieć wystarczającą liczbę próbek, aby umożliwić anonimizację poszczególnych użytkowników. Dodatkowo źródła i adresy URL muszą być publicznie indeksowane. Więcej informacji o tym, jak witryny są uwzględniane w zbiorze danych, znajdziesz w Metodologii dotyczącej użytkowania Chrome.

Wykonywanie zapytań o dane adresów URL

W poprzednim kroku pokazaliśmy, jak wysłać zapytanie do interfejsu CrUX API, aby uzyskać ogólne informacje o 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 z użyciem adresu docelowego, z tym wyjątkiem, że treść żądania używa parametru url do określenia strony, którą chcesz wyszukać.

Aby zapytać o dane adresu 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 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
        }
      },
      // ...
    }
  }
}

Zgodnie z oczekiwaniami wyniki wskazują, że https://web.dev/fast/ ma w 85% przypadków „dobry” czas LCP i 75-procentyl wynoszący 1947 ms, co jest nieco lepsze niż rozkład na poziomie pochodzenia.

Normalizacja adresów URL

Interfejs API CrUX może normalizować żądane adresy URL, aby lepiej pasowały do listy znanych adresów URL. Na przykład zapytanie o adres URL https://web.dev/fast/#measure-performance-in-the-field spowoduje, że z powodu normalizacji zostaną zwrócone dane o adresie https://web.dev/fast/. W takim przypadku odpowiedź będzie zawierać 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 dotyczącej CrUX.

Zapytania według formatu

Kluczowe pojęcie: format to typ urządzenia, na którym użytkownik odwiedza witrynę. Typy urządzeń to m.in. komputery, telefony i tablety.

Wrażenia użytkowników mogą się znacznie różnić w zależności od optymalizacji witryny, warunków sieci i urządzeń użytkowników. Aby lepiej zrozumieć te różnice, przejdź do szczegółowych informacji o wydajności pochodzenia i adresu URL za pomocą wymiaru formFactor w interfejsie CrUX API.

Interfejs API obsługuje 3 wyraźne wartości form factor: DESKTOP, PHONE i TABLET. Oprócz pochodzenia lub adresu URL podaj jedną z tych wartości w ciele żądania, aby ograniczyć wyniki tylko do tych doświadczeń użytkownika. Ten przykład pokazuje, jak wysłać zapytanie do interfejsu API według formatu za pomocą 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ą JavaScript wysłać zapytanie do interfejsu CrUX API o dane dotyczące 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 jest równoznaczne z wysłaniem żądania dotyczącego wszystkich typów urządzeń.

{
  "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ędnione są tylko działania związane z telefonem.

Uwaga: im bardziej szczegółowe jest żądanie, np. określona kombinacja adresu URL i formu, tym mniej wrażeń użytkownika będzie ono obejmować. Może to prowadzić do częstszego występowania błędów „Nie znaleziono”, zwłaszcza w przypadku zapytań o mniej popularne adresy URL lub mniej popularne typy tabletów.

Z poprzedniej sekcji wynika, że w przypadku 85% użytkowników na tej stronie LCP było „dobre”. Porównaj to z opiniami dotyczącymi konkretnych telefonów, z których tylko 78% uważa się za „dobre”. W przypadku telefonów 75. procentyl jest też wolniejszy, wzrósł z 1947 ms do 2366 ms. Podział na segmenty według typu urządzenia może uwidocznić większe różnice w doświadczeniach użytkowników.

Ocena wyników podstawowych wskaźników internetowych

Program podstawowych wskaźników internetowych definiuje cele, które pomagają określić, czy wrażenia użytkownika lub rozkład wrażeń można uznać za „dobre”. W tym przykładzie używamy interfejsu CrUX API i funkcji CrUXApiUtil.query, aby ocenić, czy rozkład danych Core Web Vitals (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}).`)
  });
}

Najważniejsza uwaga: interfejs API może być wywoływany tylko z jedną domeną źródłową lub jednym adresem URL naraz. Aby ocenić wiele witryn lub stron, wywołaj interfejs API osobno.

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 można wykorzystać do zapewnienia użytkownikom szybkiego i utrzymania szybkości. 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 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 percentyli

Aby uzyskać klucz interfejsu API i zobaczyć więcej przykładowych aplikacji, zapoznaj się z oficjalną dokumentacją interfejsu Crux API. Mamy nadzieję, że zechcesz wypróbować tę funkcję. Czekamy na Twoje pytania i opinie. Możesz je przesłać na forum dyskusyjnym poświęconym Crux. Aby być na bieżąco ze wszystkimi nowościami dotyczącymi interfejsu CrUX API, zasubskrybuj forum z ogłoszeniami dotyczącymi CrUX lub obserwuj nas na Twitterze @ChromeUXReport.