CrUX API и программный доступ

CrUX (Chrome User Experience Report) представляет собой набор данных, собираемых на основе реального взаимодействия пользователей с веб-страницами в браузере Chrome. Эти данные включают показатели производительности, такие как Core Web Vitals (LCP, FID, CLS) и позволяют анализировать опыт пользователей на миллионах сайтов без необходимости проведения собственных измерений.

Программный доступ к CrUX осуществляется через CrUX API, который предоставляет данные в структурированном виде, готовые для обработки в JavaScript. API поддерживает выборку данных по URL, домену или категории URL, а также фильтрацию по типу устройства, стране и браузеру.

Основные возможности CrUX API

  1. Получение показателей Core Web Vitals API возвращает агрегированные метрики для каждой страницы или группы страниц:

    • Largest Contentful Paint (LCP) – время загрузки основного содержимого страницы.
    • First Input Delay (FID) – задержка первой интерактивной операции пользователя.
    • Cumulative Layout Shift (CLS) – суммарное смещение элементов на странице.

  2. Фильтрация данных по контексту пользователя Данные можно запрашивать с учетом:

    • Типа устройства (desktop, mobile).
    • Географического региона.
    • Типа сети (4G, 3G и др.).

  3. Агрегация и категории Метрики предоставляются в виде распределений по percentiles (например, 75-й перцентиль LCP), что позволяет оценивать качество UX для большинства пользователей.

Использование CrUX API в JavaScript

Для работы с CrUX API в JavaScript требуется HTTP-запрос к API с указанием URL и ключа доступа (API key). Пример запроса:

const API_KEY = 'YOUR_API_KEY';
const url = 'https://www.googleapis.com/crux/v1/records:queryRecord?key=' + API_KEY;

const body = {
  "url": "https://example.com",
  "formFactor": "PHONE"
};

fetch(url, {
  method: 'POST',
  body: JSON.stringify(body),
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => {
  console.log('CrUX data:', data);
})
.catch(error => console.error('Error fetching CrUX data:', error));

В ответе API возвращает объект с метриками LCP, FID, CLS и распределениями по категориям fast, moderate, slow (для LCP и FID) и good, needsImprovement, poor (для CLS).

Структура ответа CrUX API

Типичный JSON-ответ содержит несколько ключевых разделов:

{
  "record": {
    "key": {
      "url": "https://example.com",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "percentiles": { "p75": 2500 },
        "histogram": [
          { "start": 0, "end": 2500, "density": 0.7 },
          { "start": 2500, "end": 4000, "density": 0.2 },
          { "start": 4000, "end": 10000, "density": 0.1 }
        ]
      },
      "first_input_delay": {
        "percentiles": { "p75": 15 },
        "histogram": [
          { "start": 0, "end": 100, "density": 0.95 },
          { "start": 100, "end": 300, "density": 0.04 },
          { "start": 300, "end": 1000, "density": 0.01 }
        ]
      },
      "cumulative_layout_shift": {
        "percentiles": { "p75": 0.05 },
        "histogram": [
          { "start": 0, "end": 0.1, "density": 0.9 },
          { "start": 0.1, "end": 0.25, "density": 0.08 },
          { "start": 0.25, "end": 1, "density": 0.02 }
        ]
      }
    }
  }
}

Ключевые моменты:

  • percentiles показывают значение метрики для указанного перцентиля пользователей.
  • histogram позволяет визуализировать распределение пользователей по диапазонам показателей.

Валидация и обработка данных

При работе с CrUX API необходимо учитывать:

  • Отсутствие данных для малопосещаемых страниц – API возвращает значения только для страниц с достаточным количеством взаимодействий.
  • Необходимость асинхронной обработки – данные приходят через HTTP-запрос, поэтому требуется использование async/await или Promise.
  • Корректная интерпретация распределений – для анализа UX важны не отдельные показатели, а совокупность метрик и их распределения.

Пример асинхронной обработки:

async function getCruxMetrics(url) {
  const response = await fetch('https://www.googleapis.com/crux/v1/records:queryRecord?key=' + API_KEY, {
    method: 'POST',
    body: JSON.stringify({ url, formFactor: 'PHONE' }),
    headers: { 'Content-Type': 'application/json' }
  });
  const data = await response.json();
  const metrics = data.record.metrics;
  return {
    LCP: metrics.largest_contentful_paint.percentiles.p75,
    FID: metrics.first_input_delay.percentiles.p75,
    CLS: metrics.cumulative_layout_shift.percentiles.p75
  };
}

getCruxMetrics('https://example.com').then(console.log);

Применение данных CrUX

Программный доступ к CrUX позволяет:

  • Автоматизировать мониторинг Core Web Vitals для сотен страниц.
  • Сравнивать производительность различных форм-факторов и регионов.
  • Интегрировать данные UX в аналитические панели и системы отчетности.
  • Оптимизировать страницы на основе реальных показателей пользователей, а не синтетических тестов.

Эта интеграция делает CrUX API мощным инструментом для анализа и улучшения пользовательского опыта с помощью JavaScript, позволяя строить данные решения на основе агрегированных метрик реальных пользователей.

Оглавление