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 .
Метрика
Мы сообщаем показатели в виде статистических агрегатов, в гистограммах, процентилях и дробях.
Значения с плавающей запятой округляются до 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 | ФКП |
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 | Метрика RTT |
largest_contentful_paint_resource_type | 4-значный двойной знак | процент | сопоставление типа навигации с дробью | Типы ресурсов LCP |
largest_contentful_paint_image_time_to_first_byte | интервал | миллисекунды | процентили с p75 | Подразделения ЛКП |
largest_contentful_paint_image_resource_load_delay | интервал | миллисекунды | процентили с p75 | Подразделения ЛКП |
largest_contentful_paint_image_resource_load_duration | интервал | миллисекунды | процентили с p75 | Подразделения ЛКП |
largest_contentful_paint_image_element_render_delay | интервал | миллисекунды | процентили с p75 | Подразделения ЛКП |
Сопоставление имен метрик BigQuery
| Имя метрики API CrUX | Имя метрики BigQuery |
|---|---|
cumulative_layout_shift | layout_instability.cumulative_layout_shift |
first_contentful_paint | first_contentful_paint |
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 | round_trip_time |
largest_contentful_paint_resource_type | н/д |
largest_contentful_paint_image_time_to_first_byte | н/д |
largest_contentful_paint_image_resource_load_delay | н/д |
largest_contentful_paint_image_resource_load_duration | н/д |
largest_contentful_paint_image_element_render_delay | н/д |
Период сбора
По состоянию на октябрь 2022 года API CrUX содержит объект collectionPeriod с полями firstDate и endDate , представляющими даты начала и окончания окна агрегации. Например:
"collectionPeriod": { "firstDate": { "year": 2022, "month": 9, "day": 12 }, "lastDate": { "year": 2022, "month": 10, "day": 9 } } Это позволяет лучше понять данные и определить, были ли они обновлены за этот день или возвращают те же данные, что и вчера.
Период сбора данных также доступен в PageSpeed Insights:

Кроме того, в collectionPeriod всегда будет отображаться 28 дней, даже если данные не относятся к полным 28 дням (например, если страница была запущена менее 28 дней назад). collectionPeriod — это период времени, за который данные CrUX были агрегированы, а не обязательно период времени, который представляют данные.
Примеры запросов
Запросы отправляются как объекты 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 -
interaction_to_next_paint -
largest_contentful_paint -
experimental_time_to_first_byte -
largest_contentful_paint_resource_type -
largest_contentful_paint_image_time_to_first_byte -
largest_contentful_paint_image_resource_load_delay -
largest_contentful_paint_image_resource_load_duration -
largest_contentful_paint_image_element_render_delay -
navigation_types -
round_trip_time -
form_factors(сообщается только в том случае, если в запросе не указанformFactor)
Если значение formFactor не указано, значения будут агрегированы по всем форм-факторам.
Дополнительные примеры запросов см. в разделе «Использование Chrome UX Report API» .
Конвейер данных
Набор данных CrUX обрабатывается через конвейер для консолидации, агрегирования и фильтрации данных, прежде чем они станут доступны с помощью API.
Скользящее среднее
Данные в отчете Chrome UX представляют собой 28-дневное скользящее среднее агрегированных показателей. Это означает, что данные, представленные в отчете Chrome UX в любой момент времени, на самом деле представляют собой совокупные данные за последние 28 дней.
Это похоже на то, как набор данных CrUX в BigQuery объединяет ежемесячные отчеты.
Ежедневные обновления
Данные обновляются ежедневно около 04:00 UTC. Для времени обновления не существует соглашения об уровне обслуживания; он выполняется каждый день с максимальной отдачей.
Схема
Для API CrUX существует единственная конечная точка, которая принимает HTTP-запросы POST . API возвращает record , содержащую одну или несколько metrics , соответствующих данным производительности запрошенного источника или страницы.
HTTP-запрос
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord URL-адрес использует синтаксис транскодирования gRPC .
Тело запроса
Тело запроса должно содержать данные следующей структуры:
{ "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. } | Поля | |
|---|---|
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 определяет все измерения, которые идентифицируют эту запись как уникальную.
{ "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 | Форм-фактор — это класс устройства, который использовали все пользователи для доступа к сайту по этой записи. Если форм-фактор не указан, будут возвращены агрегированные данные по всем форм-факторам. |
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 . Этой щедрой квоты должно быть достаточно для подавляющего большинства случаев использования, и невозможно заплатить за увеличение квоты.
,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 .
Метрика
Мы сообщаем показатели в виде статистических агрегирований, в гистограммах, процентилях и дробях.
Значения с плавающей запятой округляются до 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 | ФКП |
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 | Метрика RTT |
largest_contentful_paint_resource_type | 4-значный двойной знак | процент | сопоставление типа навигации с дробью | Типы ресурсов LCP |
largest_contentful_paint_image_time_to_first_byte | интервал | миллисекунды | процентили с p75 | Подразделения ЛКП |
largest_contentful_paint_image_resource_load_delay | интервал | миллисекунды | процентили с p75 | Подразделения ЛКП |
largest_contentful_paint_image_resource_load_duration | интервал | миллисекунды | процентили с p75 | Подразделения ЛКП |
largest_contentful_paint_image_element_render_delay | интервал | миллисекунды | процентили с p75 | Подразделения ЛКП |
Сопоставление имен метрик BigQuery
| Имя метрики API CrUX | Имя метрики BigQuery |
|---|---|
cumulative_layout_shift | layout_instability.cumulative_layout_shift |
first_contentful_paint | first_contentful_paint |
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 | round_trip_time |
largest_contentful_paint_resource_type | н/д |
largest_contentful_paint_image_time_to_first_byte | н/д |
largest_contentful_paint_image_resource_load_delay | н/д |
largest_contentful_paint_image_resource_load_duration | н/д |
largest_contentful_paint_image_element_render_delay | н/д |
Период сбора
По состоянию на октябрь 2022 года API CrUX содержит объект collectionPeriod с полями firstDate и endDate , представляющими даты начала и окончания окна агрегации. Например:
"collectionPeriod": { "firstDate": { "year": 2022, "month": 9, "day": 12 }, "lastDate": { "year": 2022, "month": 10, "day": 9 } } Это позволяет лучше понять данные и узнать, были ли они обновлены за этот день или возвращают те же данные, что и вчера.
Период сбора данных также доступен в PageSpeed Insights:

Кроме того, в collectionPeriod всегда будет отображаться 28 дней, даже если данные не относятся к полным 28 дням (например, если страница была запущена менее 28 дней назад). collectionPeriod — это период времени, за который данные CrUX были агрегированы, а не обязательно период времени, который представляют данные.
Примеры запросов
Запросы отправляются как объекты 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 -
interaction_to_next_paint -
largest_contentful_paint -
experimental_time_to_first_byte -
largest_contentful_paint_resource_type -
largest_contentful_paint_image_time_to_first_byte -
largest_contentful_paint_image_resource_load_delay -
largest_contentful_paint_image_resource_load_duration -
largest_contentful_paint_image_element_render_delay -
navigation_types -
round_trip_time -
form_factors(сообщается только в том случае, если в запросе не указанformFactor)
Если значение formFactor не указано, значения будут агрегированы по всем форм-факторам.
Дополнительные примеры запросов см. в разделе «Использование Chrome UX Report API» .
Конвейер данных
Набор данных CrUX обрабатывается через конвейер для консолидации, агрегирования и фильтрации данных, прежде чем они станут доступны с помощью API.
Скользящее среднее
Данные в отчете Chrome UX представляют собой 28-дневное скользящее среднее агрегированных показателей. Это означает, что данные, представленные в отчете Chrome UX в любой момент времени, на самом деле представляют собой совокупные данные за последние 28 дней.
Это похоже на то, как набор данных CrUX в BigQuery объединяет ежемесячные отчеты.
Ежедневные обновления
Данные обновляются ежедневно около 04:00 UTC. Для времени обновления не существует соглашения об уровне обслуживания; он выполняется каждый день с максимальной отдачей.
Схема
Для API CrUX существует единственная конечная точка, которая принимает HTTP-запросы POST . API возвращает record , содержащую одну или несколько metrics , соответствующих данным производительности запрошенного источника или страницы.
HTTP-запрос
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord URL-адрес использует синтаксис транскодирования gRPC .
Тело запроса
Тело запроса должно содержать данные следующей структуры:
{ "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. } | Поля | |
|---|---|
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 определяет все измерения, которые идентифицируют эту запись как уникальную.
{ "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 | Форм-фактор — это класс устройства, который использовали все пользователи для доступа к сайту по этой записи. Если форм-фактор не указан, будут возвращены агрегированные данные по всем форм-факторам. |
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 . Этой щедрой квоты должно быть достаточно для подавляющего большинства случаев использования, и невозможно заплатить за увеличение квоты.