Узнайте, как использовать API отчетов Chrome UX, чтобы получить доступ к реальным данным об опыте пользователей на миллионах веб-сайтов.
Набор данных 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 состоит из трех частей:
- 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
Вы узнали, как запрашивать данные об общем пользовательском опыте на сайте-источнике через 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.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
-
- Дополнительная детализация
- подробные гистограммы
- больше процентилей
Ознакомьтесь с официальной документацией по API CrUX , чтобы получить свой ключ API и ознакомиться с другими примерами приложений. Мы надеемся, что вы попробуете, и будем рады любым вопросам и отзывам. Свяжитесь с нами на форуме обсуждения CrUX . Чтобы быть в курсе всех наших планов по API CrUX, подпишитесь на форум объявлений CrUX или следите за нами в Твиттере: @ChromeUXReport .