Крукс API

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

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

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

Ключ API CruX

Для использования CrUX API требуется ключ Google Cloud API. Вы можете создать его на странице «Учетные данные» и подготовить его для использования Chrome UX Report API .

Получив ключ API, ваше приложение может добавить параметр запроса key=[YOUR_API_KEY] ко всем 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 .

Метрика

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

Гистограмма

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

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

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.38179
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.49905
    },
    {
      "start": 3000,
      "density": 0.11916
    }
  ]
}

Эти данные показывают, что для 38,179% загрузок страниц показатель в примере измерялся в диапазоне от 0 до 1000 мс. Единицы метрики в этой гистограмме не содержатся, в данном случае мы будем считать миллисекунды.

Кроме того, в 49,905% загрузок страниц значение метрики составляло от 1000 до 3000 мс, а в 11,916% — значение, превышающее 3000 мс.

процентили

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

{
  "percentiles": {
    "p75": 2063
  }
}

В этом примере по крайней мере 75 % загрузок страниц были измерены со значением метрики <= 2063 .

Фракции

Дроби обозначают проценты загрузки страниц, которые можно пометить определенным образом. В данном случае значениями метрик являются эти метки. Пример:

"fractions": {
  "desktop": 0.0377,
  "tablet": 0.0288,
  "phone": 0.9335
}

При этом 3,77% загрузок страниц было измерено на настольном компьютере, 2,88% — на планшете и 93,35% — на телефоне, что в сумме составляет 100%.

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

Имя метрики API CrUX Тип данных Метрические единицы Статистические агрегаты Документация web.dev
cumulative_layout_shift дважды закодирован как строка безразмерный гистограмма с тремя интервалами, процентили с p75 клс
first_contentful_paint интервал миллисекунды гистограмма с тремя интервалами, процентили с p75 ФКП
first_input_delay интервал миллисекунды гистограмма с тремя интервалами, процентили с p75 фид
interaction_to_next_paint интервал миллисекунды гистограмма с тремя интервалами, процентили с p75 вход
largest_contentful_paint интервал миллисекунды гистограмма с тремя интервалами, процентили с p75 ЖКП
experimental_time_to_first_byte интервал миллисекунды гистограмма с тремя интервалами, процентили с 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
form_factors н/д

Период сбора

По состоянию на октябрь 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
  • 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 .

Тело запроса

Тело запроса должно содержать данные следующей структуры:

{
  "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

string

Эффективный тип соединения — это измерение запроса, определяющее эффективный класс сети, которому должны принадлежать данные записи.

В этом поле используются значения ["offline", "slow-2G", "2G", "3G", "4G"] как указано в спецификации API сетевой информации.

Примечание. Если эффективный тип соединения не указан, будет возвращена специальная запись с агрегированными данными по всем действующим типам соединения.

formFactor

enum ( FormFactor )

Форм-фактор — это измерение запроса, определяющее класс устройства, которому должны принадлежать данные записи.

В этом поле используются значения DESKTOP , PHONE или TABLET .

Примечание. Если форм-фактор не указан, будет возвращена специальная запись с агрегированными данными по всем форм-факторам.

metrics[]

string

Метрики, которые следует включить в ответ. Если ничего не указано, будут возвращены все найденные метрики.

Допустимые значения: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]

url_ pattern поля объединения. Шаблон URL-адреса является основным идентификатором для поиска записи. Это может быть один из нескольких типов значений. url_ pattern может быть только одним из следующих:
origin

string

Шаблон URL-адреса «источник» относится к шаблону URL-адреса, который является источником веб-сайта.

Примеры: "https://example.com" , "https://cloud.google.com"

url

string

Шаблон URL-адреса «url» относится к шаблону URL-адреса, который представляет собой любой произвольный URL-адрес.

Примеры: "https://example.com/ , https://cloud.google.com/why-google-cloud/"

Например, чтобы запросить самые большие значения отрисовки содержимого рабочего стола для домашней страницы документации разработчика 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.98148451581189577
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.010814353596591841
          },
          {
            "start": 4000,
            "density": 0.0077011305915124116
          }
        ],
        "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

enum ( FormFactor )

Форм-фактор — это класс устройства, который использовали все пользователи для доступа к сайту по этой записи.

Если форм-фактор не указан, будут возвращены агрегированные данные по всем форм-факторам.

effectiveConnectionType

string

Эффективный тип соединения — это общий класс соединения, который используют все пользователи для этой записи. В этом поле используются значения ["offline", "slow-2G", "2G", "3G", "4G"], как указано в: https://wicg.github.io/netinfo/#efficient-connection-types .

Если эффективный тип соединения не указан, будут возвращены агрегированные данные по всем действующим типам соединения.

url_ pattern поля объединения. Шаблон URL — это URL-адрес, к которому применяется запись. url_ pattern может быть только одним из следующих:
origin

string

Происхождение указывает происхождение, для которого предназначена эта запись.

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

url

string

URL-адрес указывает конкретный URL-адрес, для которого предназначена эта запись.

Примечание. При указании URL-адреса будут агрегироваться только данные для этого конкретного URL-адреса.

Метрики

metric — это набор агрегированных данных о пользовательском опыте для одной метрики веб-производительности, например первой отрисовки контента. Он может содержать сводную гистограмму реального использования Chrome в виде серии bins , определенные процентильные данные (например, p75) или может содержать помеченные дроби.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

или

{
  "fractions": {
    object (Fractions)
  }
}
Поля
histogram[]

object ( Bin )

Гистограмма пользовательского опыта для метрики. Гистограмма будет иметь хотя бы один интервал, а плотность всех интервалов составит ~1.

percentiles

object ( Percentiles )

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

fractions

object ( Fractions )

Этот объект содержит помеченные дроби, сумма которых равна ~1.

Бин

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

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

{
  "start": value,
  "end": value,
  "density": number
}
Поля
start

value ( Value format)

Начало — начало бункера данных.

end

value ( Value format)

Конец — конец бункера данных. Если конец не заполнен, то интервал не имеет конца и действителен от начала до +inf.

density

number

Доля пользователей, которые столкнулись со значением этого интервала для данного показателя.

процентили

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

{
  "P75": value
}
Поля
p75

value ( Value format)

У 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

string

Исходный запрошенный URL-адрес до любых действий по нормализации.

normalizedUrl

string

URL-адрес после любых действий по нормализации. Это действительный URL-адрес пользовательского интерфейса, который вполне можно найти.

Ограничения ставок

API CrUX ограничен 150 запросами в минуту для каждого проекта Google Cloud, который предлагается бесплатно. Этот лимит и текущее использование можно увидеть в Google Cloud Console . Этой щедрой квоты должно быть достаточно для подавляющего большинства случаев использования, и в настоящее время невозможно заплатить за увеличение квоты.