Эта страница переведена с помощью Cloud Translation API.

API истории CruX

Опубликовано: 7 февраля 2023 г., Последнее обновление: 11 апреля 2025 г.

API истории CrUX обеспечивает доступ с малой задержкой к шестимесячным историческим данным о реальном пользовательском опыте с детализацией страницы и источника.

Попробуйте!

Общий случай использования

API истории CrUX позволяет запрашивать исторические показатели пользовательского опыта для определенного URI, например «Получить исторические тенденции UX для источника https://example.com ».

History API имеет ту же структуру, что и ежедневный CrUX API, за исключением того, что значения задаются в массиве, а ключи помечены именами во множественном числе (например, histogramTimeseries вместо histogram или p75s вместо p75 ).

Ключ API CruX

Как и в случае с ежедневным API, для использования API истории CrUX требуется ключ API Google Cloud, предоставленный для использования Chrome UX Report API . Один и тот же ключ можно использовать для ежедневного и исторического 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 указывает на то, что запись содержит информацию о нагрузках, произошедших на мобильном устройстве.

Форм-фактор

API истории CrUX доступен только в совокупности по измерениям форм-фактора. Это общий класс устройств, разделенный на PHONE , TABLET и DESKTOP .

Метрика

Мы сообщаем показатели во временных рядах статистических агрегатов, которые представляют собой гистограммы, процентили и дроби.

Гистограммы

Когда метрики выражаются в виде массива гистограмм, каждая запись временного ряда представляет собой процент загрузок страниц, для которых метрика попала в интервал, пропорционально всем. Точки данных представлены в порядке дат периода сбора данных , также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

Гистограмма с тремя интервалами для примера метрики выглядит следующим образом:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
}

Эти данные показывают, что 91,90% загрузок страниц имели значение метрики примера от 0 мс до 2500 мс для первого периода сбора в истории, за которым следовали 92,03%, 91,94%... Единицы метрики не содержатся в этой гистограмме, в данном случае мы предполагаем миллисекунды.

Кроме того, в 5,21% загрузок страниц значение показателя примера составляло от 2500 до 4000 мс в первый период сбора в истории, а в 2,88% загрузок страниц наблюдалось значение, превышающее 4000 мс в первый период сбора в истории.

процентили

Метрики также могут содержать временные ряды процентилей, которые могут быть полезны для дополнительного анализа.

Точки данных представлены в порядке дат периода сбора данных , также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

Эти процентили могут отображать конкретные значения показателей в данном процентиле для этого показателя. Они основаны на полном наборе доступных данных, а не на окончательных распределенных данных, поэтому они не обязательно соответствуют интерполированному процентилю, основанному на окончательной объединенной гистограмме.

Фракции

Метрики могут быть выражены как временные ряды помеченных фракций; каждая метка определенным образом описывает загрузку страницы. Точки данных представлены в порядке дат периода сбора данных , также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

Пример:

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

В этом примере самые последние данные показывают, что 14,21% загрузок страниц приходилось на настольные компьютеры, а 82,88% — на телефоны.

Типы значений метрик

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

Соответствие метрике

В зависимости от критериев приемлемости источник или URL-адрес могут иметь право только на некоторые периоды сбора данных, охватываемые API истории CrUX. В этих случаях API истории CrUX вернет "NaN" для плотностей histogramTimeseries и null для percentilesTimeseries для периодов сбора, по которым нет подходящих данных. Причина различия в том, что плотности гистограмм всегда представляют собой числа, а процентили могут быть числами или строками (CLS использует строки, даже если они выглядят как числа).

Например, если во втором периоде не было подходящих данных, это будет выглядеть так:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

Для URL-адресов или источников, которые с течением времени попадают в список допустимых, вы можете заметить множество пропущенных записей.

Периоды сбора

API истории CrUX содержит объект collectionPeriods с массивом полей firstDate и endDate , представляющих даты начала и окончания каждого окна агрегации. Например:

    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day"