Как использовать API истории CrUX

Йоханнес Хенкель
Жасмин Ян
Jasmine Yan
GitHub
Барри Поллард

В этом руководстве представлена ​​конечная точка API истории отчетов Chrome UX (CrUX) , которая предоставляет временные ряды данных о веб-производительности. Эти данные обновляются еженедельно и позволяют просматривать историю примерно за 6 месяцев с 25 точками данных, разнесенными по неделям.

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

Попробуйте API на этой странице

Попробуйте!

Запросить ежедневный API CrUX

Если вспомнить предыдущую статью о CrUX API , то получить снимок данных поля для конкретного источника можно таким способом:

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [{
          "start": 0, "end": 2500, "density": 0.9192
        }, {
          "start": 2500, "end": 4000, "density": 0.0513
        }, {
          "start": 4000, "density": 0.0294
        }],
        "percentiles": {
          "p75": 1303
        }
      }
      // ...
    },
    "collectionPeriod": {
      "firstDate": { "year": 2022, "month": 12, "day": 27 },
      "lastDate": { "year": 2023, "month": 1, "day": 23 }
    }
  }
}

Этот снимок включает значения плотности гистограммы и значения процентилей для определенного 28-дневного периода сбора данных, в данном случае с 27 декабря 2022 г. по 23 января 2023 г.

Запросить API истории CrUX

Чтобы вызвать конечную точку истории, измените queryRecord в URL-адресе на queryHistoryRecord в команде curl . Использование того же ключа API CrUX, что и для предыдущего вызова, будет работать.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"origin": "https://web.dev"}'

Общая форма ответа аналогична, но данных гораздо больше! Вместо одной точки данных теперь есть временные ряды для полей, содержащих значения 75-го процентиля (p75) и плотности гистограммы.

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "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
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377
          ]
        }
      }
      // ...
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]
  }
}

В этом примере временной ряд densities для сегмента от 0 до 2500 мс метрики Largest Contentful Paint (LCP) равен [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Каждая из этих плотностей наблюдалась во время соответствующей записи collectionPeriods . Например, пятая плотность, 0,9183, была плотностью пятого периода сбора данных, заканчивающегося 3 сентября 2022 года, а 0,9187 — плотностью периода, заканчивающегося через неделю после этого.

Другими словами, интерпретируя последние записи временного ряда в примере для https://web.dev , было обнаружено, что с 14 августа 2022 г. по 10 сентября 2022 г. 91,87% загрузок страниц имели значения LCP менее 2500 мс, 5,27. % имели значения от 2500 мс до 4000 мс, а 2,85% имели значения более 4000 мс.

Аналогичным образом существует временной ряд значений p75: LCP p75 с 14 августа 2022 г. по 10 сентября 2022 г. составлял 1377 . Это означает, что за этот период сбора данных в 75% случаев взаимодействия с пользователем LCP составляло менее 1377 мс, а в 25% случаев взаимодействия с пользователем значение LCP превышало 1377 мс.

Хотя в примере перечислены только 6 записей временных рядов и периодов сбора данных, ответы API предоставляют 25 записей временных рядов; поскольку конечными датами каждого из этих периодов сбора являются субботы с интервалом в 7 дней, это охватывает 6 месяцев.

В любом ответе длина временного ряда для плотностей интервалов гистограммы и значений p75 будет точно такой же, как длина массива в поле collectionPeriods : существует взаимно однозначное соответствие, основанное на индексе в этих ответах. массивы.

Запрос данных на уровне страницы

Помимо данных на уровне источника, API истории CrUX обеспечивает доступ к историческим данным на уровне страницы. Хотя данные на уровне источника ранее были доступны с использованием набора данных CrUX в BigQuery (или с помощью панели управления CrUX ), исторические данные на уровне страницы были доступны только в том случае, если сайты сами собирали и хранили данные. Новый API теперь разблокирует эти исторические данные на уровне страницы.

Данные на уровне страницы можно запросить таким же образом, но используя в полезных данных url вместо origin :

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"url": "https://web.dev/blog/"}'

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

Визуализируйте данные

Итак, вы можете спросить, почему данные имеют такую ​​форму? Было обнаружено, что это облегчает построение графиков. Например, вот график значений p75 для взаимодействия с следующей отрисовкой (INP) для https://web.dev :

График временных рядов значения p75, показывающий регресс примерно в ноябре 2022 года.

На этой линейной диаграмме каждое значение на оси Y представляет собой значение p75 из временного ряда p75s , а ось X — это время, которое установлено как lastDate для каждого периода сбора данных.

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

Составная гистограмма, показывающая, как с течением времени меняются относительные пропорции хорошего, нуждающегося в улучшении и плохого.

Ось X устанавливается как lastDate для каждого периода сбора данных. Однако на этот раз ось Y — это процент загрузок страниц, попадающих в определенный диапазон метрики INP, показанный в виде гистограммы с накоплением. Диаграмма p75 предоставляет краткий обзор, и на одной диаграмме относительно легко добавить несколько показателей или отобразить линии как для PHONE , так и для DESKTOP . Трехбинная диаграмма дает представление о распределении значений показателей, измеренных в течение каждого периода сбора данных.

Например, хотя диаграмма p75 показывает, что https://web.dev имел почти приемлемые значения INP в течение периода наблюдения, трехуровневая диаграмма показывает, что для небольшой части загрузок страниц INP на самом деле был плохим. На обоих графиках относительно легко сделать вывод, что произошел спад производительности, который начался ближе к концу октября и был зафиксирован к середине ноября.

Чтобы самостоятельно генерировать такие диаграммы, мы создали пример Colab . Colab, или «Колаборатория», позволяет вам писать и выполнять Python из вашего браузера. API истории CrUX Colab ( источник ) использует Python для вызовов API и построения диаграмм данных.

Этот Colab позволяет создавать диаграммы p75, тройные диаграммы, получать данные в табличной форме и просматривать пару запросов и ответов для CrUX API, заполнив краткую форму. Вам не обязательно быть программистом, чтобы использовать это, но вы, безусловно, можете просмотреть код Python и изменить его во что-то потрясающее! Пожалуйста, наслаждайтесь и не стесняйтесь оставлять отзывы о том, что вы найдете!

Конечно, вы не ограничены Colab или Python, и это всего лишь один пример использования этого нового API. Поскольку API является конечной точкой HTTP на основе JSON, его можно запрашивать из любой технологии.

Заключение

До появления конечной точки CrUX History API владельцы сайтов были ограничены в исторической информации, которую они могли получить от CrUX. Ежемесячные данные на уровне источника были доступны с помощью BigQuery и CrUX Dashboard, но еженедельные данные были недоступны, как и исторические данные на уровне страниц. Владельцы сайтов могли сами записывать эти данные с помощью ежедневного API, но зачастую необходимость в этом обнаруживалась только после регрессии метрик.

Надеемся, что введение этого API истории CrUX позволит владельцам сайтов лучше понять изменяющиеся показатели сайта, а также станет инструментом диагностики при возникновении проблем. Если вы используете новый API, отзывы приветствуются в группе Google Chrome UX Report (Discussions) .

Благодарности

Изображение героя от Дэйва Херринга на Unsplash