Как использовать API Crux

Узнайте, как использовать API отчетов Chrome UX, чтобы получить доступ к реальным данным об опыте пользователей на миллионах веб-сайтов.

Рик Вискоми
Шейн Экстеркамп
Shane Exterkamp
X GitHub

Набор данных Chrome UX Report (CrUX) отражает, как реальные пользователи Chrome взаимодействуют с популярными веб-ресурсами. С 2017 года, когда этот набор данных был впервые выпущен в BigQuery , данные полей из CrUX были интегрированы в инструменты разработчиков, такие как PageSpeed ​​Insights и отчет Core Web Vitals в Search Console, что позволяет разработчикам измерять и отслеживать реальный пользовательский опыт. Всё это время не хватало инструмента, предоставляющего бесплатный программный доступ к данным CrUX на основе REST. Чтобы помочь восполнить этот пробел, мы рады объявить о выпуске совершенно нового API Chrome UX Report !

Этот API был создан с целью предоставить разработчикам быстрый и полный доступ к данным CrUX. API CrUX предоставляет только данные о пользовательском опыте, полученные в ходе полевых испытаний , в отличие от существующего API PageSpeed ​​Insights , который также предоставляет лабораторные данные аудита производительности Lighthouse. API CrUX оптимизирован и позволяет быстро предоставлять данные о пользовательском опыте, что делает его идеально подходящим для приложений аудита в режиме реального времени.

Чтобы гарантировать разработчикам доступ ко всем наиболее важным показателям — основным веб-показателям — API CrUX проверяет и отслеживает отрисовку самого большого контента (LCP), взаимодействие со следующей отрисовкой (INP) и кумулятивный сдвиг макета (CLS) как на уровне источника, так и на уровне URL.

Давайте же углубимся и посмотрим, как этим пользоваться!

Попробуйте API на этой странице

Попробуйте!

Запрос данных об источнике

Источники в наборе данных CrUX охватывают все базовые элементы интерфейса на уровне страницы. В следующем примере показано, как запросить данные об интерфейсе пользователя источника к API CrUX с помощью curl в командной строке.

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

Команда curl состоит из трех частей:

  1. URL-адрес конечной точки API, включая закрытый ключ API вызывающего абонента.
  2. Заголовок Content-Type: application/json , указывающий, что тело запроса содержит JSON.
  3. Тело запроса в кодировке JSON, указывающее источник https://web.dev .

Чтобы сделать то же самое в JavaScript, используйте утилиту CrUXApiUtil , которая выполняет вызов API и возвращает декодированный ответ (см. также наш вариант на 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;
  });
};

Замените [YOUR_API_KEY] на свой ключ . Затем вызовите функцию CrUXApiUtil.query и передайте объект тела запроса .

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

Если данные для этого источника существуют, ответ API представляет собой JSON-кодированный объект, содержащий метрики, отражающие распределение пользовательского опыта. Метрики распределения представляют собой гистограммы и процентили.

{
  "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
        }
      },
      // ...
    }
  }
}

start и end значения объекта histogram представляют диапазон значений, которые пользователи получают для данной метрики. Свойство density отображает долю пользовательских впечатлений в этом диапазоне. В данном примере 79% пользовательских впечатлений LCP на всех страницах web.dev составляют менее 2500 миллисекунд, что соответствует пороговому значению LCP « хорошо ». Значение percentiles.p75 означает, что 75% пользовательских впечатлений в этом распределении составляют менее 2216 миллисекунд. Подробнее о структуре ответа см. в документации по телу ответа .

Ошибки

Если API CrUX не имеет данных для указанного источника, он отвечает сообщением об ошибке в формате JSON:

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

Чтобы устранить эту ошибку, сначала убедитесь, что запрошенный источник доступен для навигации. Это можно проверить, введя источник в адресную строку браузера и сравнив его с конечным URL после любых перенаправлений. К распространённым проблемам относятся ненужное добавление или исключение поддомена, а также использование неправильного протокола HTTP.

Ошибка 
{"origin": "http://www.web.dev"}

Этот источник ошибочно включает протокол http:// и поддомен www.

Успех 
{"origin": "https://web.dev"}

Этот источник находится в общественном доступе.

Если запрошенный источник является версией с возможностью навигации, эта ошибка также может возникнуть, если в источнике недостаточно выборок. Все источники и URL-адреса, включённые в набор данных, должны иметь достаточное количество выборок для анонимизации отдельных пользователей. Кроме того, источники и URL-адреса должны быть общедоступными для индексации . Подробнее о том, как веб-сайты включаются в набор данных, см. в методологии CrUX.

Запрос данных URL

Вы узнали, как запрашивать данные об общем пользовательском опыте на сайте-источнике через API CrUX. Чтобы ограничить результаты конкретной страницей, используйте параметр запроса 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/"}'

Эта команда curl похожа на пример с источником, за исключением того, что в теле запроса используется параметр url для указания страницы для поиска.

Чтобы запросить данные URL из API CrUX в JavaScript, вызовите функцию CrUXApiUtil.query , используя параметр url в теле запроса.

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