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

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

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

Набор данных Chrome UX Report (CrUX) отображает, как реальные пользователи Chrome видят популярные направления в Интернете. С 2017 года, когда запрашиваемый набор данных был впервые выпущен в BigQuery , полевые данные из CrUX были интегрированы в инструменты разработчика, такие как PageSpeed ​​Insights , CrUX Dashboard и отчет Core Web Vitals Search Console, что позволяет разработчикам измерять и отслеживать реальные впечатления пользователей. Частью, которой не хватало все это время, был инструмент, который предоставляет бесплатный и RESTful доступ к данным CrUX программным путем. Чтобы помочь заполнить этот пробел, мы рады объявить о выпуске совершенно нового 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

Вы увидели, как запросить CrUX API для общего пользовательского опыта на источнике. Чтобы ограничить результаты определенной страницей, используйте параметр запроса 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.error(response);
});

Если данные для этого URL существуют в наборе данных CrUX, API вернет ответ в кодировке JSON. Например 

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

Как и ожидалось, результаты показывают, что https://web.dev/fast/ имеет 85% «хороших» впечатлений LCP и 75-й процентиль 1947 миллисекунд, что немного лучше, чем распределение по всему источнику.

Нормализация URL-адресов

API CrUX может нормализовать запрошенные URL-адреса для лучшего соответствия списку известных URL-адресов. Например, запрос URL-адреса https://web.dev/fast/#measure-performance-in-the-field приведет к данным для https://web.dev/fast/ из-за нормализации. Когда это происходит, объект 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"
  }
}

Подробнее о нормализации URL-адресов читайте в документации CrUX.

Запрос по форм-фактору

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

API поддерживает три явных значения форм-фактора: DESKTOP , PHONE и TABLET . В дополнение к источнику или URL-адресу укажите одно из этих значений в теле запроса , чтобы ограничить результаты только этими пользовательскими интерфейсами. В этом примере показано, как запросить API по форм-фактору с помощью 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"}'

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

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

Пропуск параметра formFactor эквивалентен запросу данных для всех форм-факторов вместе взятых. 

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

Поле key ответа будет содержать конфигурацию запроса formFactor , подтверждающую, что включены только телефонные возможности.

Вспомните предыдущий раздел, что 85% пользовательских впечатлений на этой странице имели «хороший» LCP. Сравните это с телефонными впечатлениями, из которых только 78% считаются «хорошими». 75-й процентиль также медленнее среди телефонных впечатлений, с 1947 миллисекунд до 2366 миллисекунд. Сегментация по форм-фактору может выявить более существенные различия в пользовательских впечатлениях.

Оцените производительность основных веб-показателей

Программа Core Web Vitals определяет цели, которые помогают определить, можно ли считать пользовательский опыт или распределение опыта «хорошими». В следующем примере мы используем API CrUX и функцию CrUXApiUtil.query для оценки того, является ли распределение метрик Core Web Vitals (LCP, INP, CLS) веб-страницы «хорошим». 

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

Результаты показывают, что эта страница прошла оценку Core Web Vitals по всем трем показателям. 

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).

В сочетании с автоматизированным способом мониторинга результатов API данные из CrUX могут использоваться для обеспечения того, чтобы реальный пользовательский опыт стал быстрым и оставался быстрым . Для получения дополнительной информации о Core Web Vitals и способах их измерения ознакомьтесь с Web Vitals и Инструментами для измерения Core Web Vitals .

Что дальше?

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

  • Дополнительные метрики
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Дополнительные размеры
    • month
    • country
  • Дополнительная детализация
    • подробные гистограммы
    • больше процентилей

Ознакомьтесь с официальной документацией CrUX API, чтобы получить свой ключ API и изучить больше примеров приложений. Мы надеемся, что вы попробуете, и мы будем рады услышать любые ваши вопросы или отзывы, поэтому свяжитесь с нами на форуме обсуждения CrUX . А чтобы быть в курсе всего, что мы запланировали для CrUX API, подпишитесь на форум объявлений CrUX или следите за нами в Twitter по адресу @ChromeUXReport .