API CrUX обеспечивает доступ с малой задержкой к агрегированным данным об опыте реальных пользователей на уровне страницы и источника.
Общий случай использования
API CrUX позволяет запрашивать показатели пользовательского опыта для определенного URI, например «Получить метрики для источника https://example.com
».
Ключ API CruX
Для использования CrUX API требуется ключ Google Cloud API, предоставленный для использования Chrome UX Report API
.
Получение и использование ключа API
Получить ключИли создайте его на странице «Учетные данные» .
После того как у вас есть ключ API, ваше приложение может добавить параметр запроса key= yourAPIKey
ко всем URL-адресам запроса.
Ключ API можно безопасно встраивать в URL-адреса; ему не нужна никакая кодировка.
См. Примеры запросов .
Модель данных
В этом разделе подробно описана структура данных в запросах и ответах.
Записывать
Отдельный фрагмент информации о странице или сайте. Запись может содержать данные, специфичные для идентификатора и определенной комбинации измерений. Запись может содержать данные для одной или нескольких метрик.
Идентификаторы
Идентификаторы указывают, какие записи следует искать. В CrUX этими идентификаторами являются веб-страницы и веб-сайты.
Источник
Если идентификатор является источником, все данные, имеющиеся для всех страниц в этом источнике, объединяются вместе. Например, предположим, что в источнике http://www.example.com
были страницы, представленные в этой карте сайта:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Это будет означать, что при запросе отчета Chrome UX с источником, установленным на http://www.example.com
, данные для http://www.example.com/
, http://www.example.com/foo.html
и http://www.example.com/bar.html
будут возвращены вместе, поскольку все это страницы этого источника.
URL-адреса
Если идентификатором является URL-адрес, будут возвращены только данные для этого конкретного URL-адреса. Снова взглянем на исходную карту сайта http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Если идентификатор установлен на URL со значением http://www.example.com/foo.html
, будут возвращены только данные для этой страницы.
Размеры
Измерения определяют конкретную группу данных, по которым агрегируется запись. Например, форм-фактор PHONE
указывает, что запись содержит информацию о нагрузках, которые имели место на мобильном устройстве. Каждое измерение будет иметь определенное количество значений, и отсутствие указания этого измерения неявно будет означать, что измерение агрегируется по всем значениям. Например, отсутствие указания форм-фактора означает, что запись содержит информацию о нагрузках, имевших место в любом форм-факторе.
Форм-фактор
Класс устройства, который конечный пользователь использовал для перехода на страницу. Это общий класс устройств, разделенный на PHONE
, TABLET
и DESKTOP
.
Эффективный тип соединения
Эффективный тип соединения — это предполагаемое качество соединения устройства при переходе на страницу. Это общий класс, разделенный на offline
, slow-2G
, 2G
, 3G
и 4G
.
Метрика
Мы сообщаем показатели в виде статистических агрегатов, в гистограммах, процентилях и дробях.
Значения с плавающей запятой округляются до 4 десятичных знаков (обратите внимание, что метрики cumulative_layout_shift
имеют двойное кодирование в виде строки, поэтому не считаются числами с плавающей запятой и сообщаются с точностью до 2 десятичных знаков внутри строки).
Гистограмма
Когда метрики выражаются в виде гистограммы, мы показываем процент загрузок страниц, попадающих в определенные диапазоны для этой метрики.
Гистограмма с тремя интервалами для примера метрики выглядит следующим образом:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
Эти данные показывают, что для 38,18% загрузок страниц показатель в примере измерялся в диапазоне от 0 до 1000 мс. Единицы метрики в этой гистограмме не содержатся, в данном случае мы будем считать миллисекунды.
Кроме того, в 49,91% загрузок страниц значение показателя составляло от 1000 до 3000 мс, а в 11,92% — значение, превышающее 3000 мс.
процентили
Метрики также могут содержать процентили, которые могут быть полезны для дополнительного анализа. Мы сообщаем конкретные значения показателей в заданном процентиле для этого показателя. Они основаны на полном наборе доступных данных, а не на окончательных распределенных данных, поэтому они не обязательно соответствуют интерполированному процентилю, основанному на окончательной объединенной гистограмме.
{
"percentiles": {
"p75": 2063
}
}
В этом примере не менее 75 % загрузок страниц были измерены со значением метрики <= 2063
.
Фракции
Дроби обозначают проценты загрузки страниц, которые можно пометить определенным образом. В данном случае значениями метрик являются эти метки.
Например, метрика form_factors
состоит из объекта fractions
, в котором перечислены форм-факторы (или устройства), которые охватывает данный запрос:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
В данном случае 3,77% загрузок страниц было измерено на настольном компьютере, 2,88% — на планшете и 93,35% — на телефоне, что в сумме составляет 100%.
Типы значений показателей
Имя метрики API CrUX | Тип данных | Метрические единицы | Статистические агрегаты | Документация |
---|---|---|---|---|
cumulative_layout_shift | 2 десятичных знака дважды закодированы как строка | безразмерный | гистограмма с тремя интервалами, процентили с p75 | клс |
first_contentful_paint | интервал | миллисекунды | гистограмма с тремя интервалами, процентили с p75 | ФКП |
first_input_delay (устарело) | интервал | миллисекунды | гистограмма с тремя интервалами, процентили с p75 | фид |
interaction_to_next_paint | интервал | миллисекунды | гистограмма с тремя интервалами, процентили с p75 | вход |
largest_contentful_paint | интервал | миллисекунды | гистограмма с тремя интервалами, процентили с p75 | ЖКП |
experimental_time_to_first_byte | интервал | миллисекунды | гистограмма с тремя интервалами, процентили с p75 | ттфб |
form_factors | 4-значный знак двойной | процент | отображение форм-фактора на дробь | форм-факторы |
navigation_types | 4-значный знак двойной | процент | сопоставление типа навигации с дробью | типы навигации |
round_trip_time | интервал | миллисекунды | процентили с p75 | ртт |
Сопоставление имен метрик BigQuery
Имя метрики API CrUX | Имя метрики BigQuery |
---|---|
cumulative_layout_shift | layout_instability.cumulative_layout_shift |
first_contentful_paint | first_contentful_paint |
first_input_delay | first_input.delay |
interaction_to_next_paint | interaction_to_next_paint |
largest_contentful_paint | largest_contentful_paint |
experimental_time_to_first_byte | experimental.time_to_first_byte |
navigation_types | navigation_types |
form_factors | н/д |
round_trip_time | н/д |
Период сбора
По состоянию на октябрь 2022 года API CrUX содержит объект collectionPeriod
с полями firstDate
и endDate
, представляющими даты начала и окончания окна агрегации. Например:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
Это позволяет лучше понять данные и узнать, были ли они обновлены за этот день или возвращают те же данные, что и вчера.
Обратите внимание, что API CrUX отстает примерно на два дня от сегодняшней даты, поскольку он ожидает полных данных за день, и требуется некоторое время на обработку, прежде чем они станут доступны в API. Используемый часовой пояс — тихоокеанское стандартное время (PST) без изменений для перехода на летнее время.
Примеры запросов
Запросы отправляются как объекты JSON с использованием запроса POST к https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
с данными запроса в виде объекта JSON в теле POST:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Например, это можно вызвать из curl
с помощью следующей командной строки (заменив API_KEY
своим ключом):
curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'
Данные уровня страницы доступны через API, если в запросе передается свойство url
вместо origin
:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Если свойство metrics
не установлено, будут возвращены все доступные метрики:
-
cumulative_layout_shift
-
first_contentful_paint
-
first_input_delay
(устарело) -
interaction_to_next_paint
-
largest_contentful_paint
-
experimental_time_to_first_byte
-
navigation_types
-
form_factors
(сообщается только в том случае, если в запросе не указанformFactor
)
Если значение formFactor
не указано, значения будут агрегированы по всем форм-факторам.
Дополнительные примеры запросов см. в разделе «Использование Chrome UX Report API» .
Конвейер данных
Набор данных CrUX обрабатывается через конвейер для консолидации, агрегирования и фильтрации данных, прежде чем они станут доступны с помощью API.
Скользящее среднее
Данные в отчете Chrome UX представляют собой 28-дневное скользящее среднее агрегированных показателей. Это означает, что данные, представленные в отчете Chrome UX Report в любой момент времени, на самом деле представляют собой данные за последние 28 дней, агрегированные вместе.
Это похоже на то, как набор данных CrUX в BigQuery объединяет ежемесячные отчеты.
Ежедневные обновления
Данные обновляются ежедневно около 04:00 UTC. Для времени обновления не существует соглашения об уровне обслуживания; он выполняется каждый день с максимальной отдачей.
Схема
Для API CrUX существует единственная конечная точка, которая принимает HTTP-запросы POST
. API возвращает record
, содержащую одну или несколько metrics
, соответствующих данным производительности запрошенного источника или страницы.
HTTP-запрос
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
URL-адрес использует синтаксис транскодирования gRPC .
Тело запроса
Тело запроса должно содержать данные следующей структуры:
{
"effectiveConnectionType": string,
"formFactor": enum (FormFactor),
"metrics": [
string
],
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
Поля | |
---|---|
effectiveConnectionType | Эффективный тип соединения — это измерение запроса, определяющее эффективный класс сети, которому должны принадлежать данные записи. В этом поле используются значения Примечание. Если эффективный тип соединения не указан, будет возвращена специальная запись с агрегированными данными по всем действующим типам соединения. |
formFactor | Форм-фактор — это измерение запроса, определяющее класс устройства, которому должны принадлежать данные записи. В этом поле используются значения Примечание. Если форм-фактор не указан, будет возвращена специальная запись с агрегированными данными по всем форм-факторам. |
metrics[] | Метрики, которые следует включить в ответ. Если ничего не указано, будут возвращены все найденные метрики. Допустимые значения: |
url_ pattern поля объединения. url_pattern — это основной идентификатор для поиска записи. Это может быть только одно из следующих: | |
origin | Примеры: |
url | Примеры: |
Например, чтобы запросить самые большие значения отрисовки содержимого рабочего стола для домашней страницы документации разработчика Chrome:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Тело ответа
Успешные запросы возвращают ответы с объектом record
и urlNormalizationDetails
в следующей структуре:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Например, ответ на тело запроса в предыдущем запросе может быть таким:
{
"record": {
"key": {
"formFactor": "DESKTOP",
"url": "https://developer.chrome.com/docs/"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.9815
},
{
"start": 2500,
"end": 4000,
"density": 0.0108
},
{
"start": 4000,
"density": 0.0077
}
],
"percentiles": {
"p75": 651
}
}
},
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
}
}
Ключ
Key
определяет все измерения, которые идентифицируют эту запись как уникальную.
{
"effectiveConnectionType": string,
"formFactor": enum (FormFactor),
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
Поля | |
---|---|
formFactor | Форм-фактор — это класс устройства, который использовали все пользователи для доступа к сайту по этой записи. Если форм-фактор не указан, будут возвращены агрегированные данные по всем форм-факторам. |
effectiveConnectionType | Эффективный тип соединения — это общий класс соединения, который используют все пользователи для этой записи. В этом поле используются значения ["offline", "slow-2G", "2G", "3G", "4G"], как указано в: https://wicg.github.io/netinfo/#efficient-connection-types . Если эффективный тип соединения не указан, будут возвращены агрегированные данные по всем действующим типам соединений. |
url_ pattern поля объединения. Шаблон URL-адреса — это URL-адрес, к которому применяется запись. url_ pattern может быть только одним из следующих: | |
origin | Примечание. При указании |
url | Примечание. При указании |
Метрики
metric
— это набор агрегированных данных о пользовательском опыте для одной метрики веб-производительности, например первой отрисовки контента. Он может содержать сводную гистограмму реального использования Chrome в виде серии bins
, определенные процентильные данные (например, p75) или может содержать помеченные дроби.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
или
{
"fractions": {
object (Fractions)
}
}
Поля | |
---|---|
histogram[] | Гистограмма пользовательского опыта для метрики. Гистограмма будет иметь хотя бы один интервал, а плотность всех интервалов составит ~1. |
percentiles | Общие полезные процентили Метрики. Тип значения для процентилей будет таким же, как типы значений, заданные для ячеек гистограммы. |
fractions | Этот объект содержит помеченные дроби, сумма которых равна ~1. Дроби округляются до 4 знаков после запятой. |
Бин
bin
— это дискретная часть данных, охватывающая от начала до конца или, если конец не указан, от начала до положительной бесконечности.
Начальное и конечное значения интервала задаются в типе значения метрики, которую он представляет. Например, первая отрисовка содержимого измеряется в миллисекундах и отображается как целые числа, поэтому его метрические ячейки будут использовать int32 для начальных и конечных типов. Однако совокупный сдвиг макета измеряется в десятичных дробях без единиц измерения и отображается как десятичное число, закодированное в виде строки, поэтому его метрические ячейки будут использовать строки в качестве типа значения.
{
"start": value,
"end": value,
"density": number
}
Поля | |
---|---|
start | Начало — начало бункера данных. |
end | Конец — конец бункера данных. Если конец не заполнен, то интервал не имеет конца и действителен от начала до +inf. |
density | Доля пользователей, которые столкнулись со значением этого интервала для данного показателя. Плотности округлены до 4 десятичных знаков. |
процентили
Percentiles
содержат синтетические значения показателя для данного статистического процентиля. Они используются для оценки значения показателя, воспринимаемого процентом пользователей от общего числа пользователей.
{
"P75": value
}
Поля | |
---|---|
p75 | В 75% загрузок страниц данный показатель был равен этому значению или меньше. |
Фракции
Fractions
содержат помеченные дроби, сумма которых равна ~1. Каждая метка каким-то образом описывает загрузку страницы, поэтому метрики, представленные таким образом, можно рассматривать как производящие отдельные значения вместо числовых значений, а дроби выражают частоту измерения определенного отдельного значения.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Подобно значениям плотности в интервалах гистограммы, каждая fraction
представляет собой число 0.0 <= value <= 1.0
, и в сумме они дают ~1,0.
Нормализация URL
Объект, представляющий действия по нормализации, предпринятые для нормализации URL-адреса, чтобы повысить вероятность успешного поиска. Это простые автоматические изменения, которые вносятся в случае, если поиск по предоставленному url_pattern
, как известно, не удался. Сложные действия, такие как следующие перенаправления, не обрабатываются.
{
"originalUrl": string,
"normalizedUrl": string
}
Поля | |
---|---|
originalUrl | Исходный запрошенный URL-адрес до любых действий по нормализации. |
normalizedUrl | URL-адрес после любых действий по нормализации. Это действительный URL-адрес пользовательского интерфейса, который вполне можно найти. |
Ограничения ставок
API CrUX ограничен 150 запросами в минуту для каждого проекта Google Cloud, который предлагается бесплатно. Этот лимит и текущее использование можно увидеть в Google Cloud Console . Этой щедрой квоты должно быть достаточно для подавляющего большинства случаев использования, и платить за увеличение квоты невозможно.