Узнайте, как использовать Chrome UX Report API, чтобы получить доступ к реальным данным об опыте пользователей на миллионах веб-сайтов.
Набор данных Chrome UX Report (CrUX) показывает, как реальные пользователи Chrome взаимодействуют с популярными местами в Интернете. С 2017 года, когда набор запрашиваемых данных был впервые выпущен на BigQuery , данные полей из CrUX были интегрированы в инструменты разработчика, такие как PageSpeed Insights , панель управления CrUX и отчет Core Web Vitals в Search Console, что позволяет разработчикам измерять и отслеживать взаимодействие с реальными пользователями. Частью, которой не хватало все это время, был инструмент, который обеспечивает бесплатный и RESTful доступ к данным CrUX программным способом. Чтобы восполнить этот пробел, мы рады объявить о выпуске совершенно нового Chrome UX Report API !
Этот API был создан с целью предоставить разработчикам простой, быстрый и комплексный доступ к данным CrUX. API CrUX сообщает только данные об опыте работы пользователей на местах , в отличие от существующего API PageSpeed Insights , который также сообщает лабораторные данные аудита производительности Lighthouse. API CrUX оптимизирован и может быстро предоставлять данные о пользовательском опыте, что делает его идеально подходящим для приложений аудита в реальном времени.
Чтобы гарантировать, что разработчики имеют доступ ко всем наиболее важным метрикам — основным веб-показателям — API CrUX проверяет и отслеживает самую большую отрисовку контента (LCP), задержку первого ввода (FID) и совокупный сдвиг макета (CLS) на обоих уровень происхождения и URL-адреса.
Итак, давайте углубимся и посмотрим, как его использовать!
Данные об источнике запроса
Источники в наборе данных CrUX охватывают все базовые возможности уровня страницы. В следующем примере показано, как запросить у CrUX API данные об опыте пользователя источника с помощью 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 состоит из трех частей:
- Конечная точка URL API, включая закрытый ключ API вызывающей стороны.
- Заголовок
Content-Type: application/json, указывающий, что тело запроса содержит JSON. - Тело запроса в формате 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-адреса из CrUX API в 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 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"}'
Чтобы запросить у CrUX API данные, специфичные для форм-фактора, с помощью 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
Программа Core Web Vitals определяет цели, которые помогают определить, можно ли считать пользовательский опыт или распространение опыта «хорошим». В следующем примере мы используем CrUX API и функцию CrUXApiUtil.query , чтобы оценить, является ли распределение на веб-странице показателей Core Web Vitals (LCP, FID, CLS) «хорошим».
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
assessCoreWebVitals(response);
}).catch(response => {
console.error(response);
});
function assessCoreWebVitals(response) {
// See https://web.dev/vitals/#core-web-vitals.
const CORE_WEB_VITALS = [
'largest_contentful_paint',
'first_input_delay',
'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 first_input_delay passes the Core Web Vitals "good" threshold (100).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).
В сочетании с автоматизированным способом мониторинга результатов API данные из CrUX можно использовать для обеспечения быстрого и быстрого взаимодействия с реальными пользователями. Для получения дополнительной информации об основных веб-показателях и способах их измерения ознакомьтесь с веб-показателями и инструментами для измерения основных веб-показателей .
Что дальше?
Функции, включенные в первоначальную версию CrUX API, лишь поверхностно отражают те идеи, которые возможны с помощью CrUX. Пользователи набора данных CrUX в BigQuery могут быть знакомы с некоторыми более продвинутыми функциями, включая:
- Дополнительные метрики
-
first_paint -
dom_content_loaded -
onload -
time_to_first_byte -
notification_permissions
-
- Дополнительные размеры
-
month -
country -
effective connection type(ECT)
-
- Дополнительная детализация
- подробные гистограммы
- больше процентилей
Ознакомьтесь с официальной документацией по API CrUX , чтобы получить ключ API и изучить дополнительные примеры приложений. Мы надеемся, что вы попробуете, и будем рады услышать любые ваши вопросы или отзывы, поэтому свяжитесь с нами на дискуссионном форуме CrUX . А чтобы быть в курсе всего, что мы запланировали для CrUX API, подпишитесь на форум объявлений CrUX или следите за нами в Твиттере @ChromeUXReport .