Крукс 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 .

Метрика

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

Значения с плавающей запятой округляются до 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-значный двойной знак процент сопоставление типа навигации с дробью типы навигации

Сопоставление имен метрик 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 н/д

Период сбора

По состоянию на октябрь 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 в любой момент времени, на самом деле представляют собой совокупные данные за последние 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_pattern — это основной идентификатор для поиска записи. Это может быть только одно из следующих:
origin

string

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

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

url

string

url url_pattern относится к шаблону 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.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

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

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

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

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.

Дроби округляются до 4 знаков после запятой.

Бин

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

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

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

(integer | string)

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

end

(integer | string)

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

density

number

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

Плотности округлены до 4 десятичных знаков.

процентили

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

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

(integer | string)

В 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 . Этой щедрой квоты должно быть достаточно для подавляющего большинства случаев использования, и невозможно заплатить за увеличение квоты.