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

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

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

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

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

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

Попробуйте!

Запрос ежедневного API CrUX

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

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, что и для предыдущего вызова, будет работать. collectionPeriodCount указывает количество записей временного ряда для возврата; максимальное значение — 40. Если не указано, по умолчанию используется значение 25.

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", "collectionPeriodCount": 40}'

Общая форма ответа похожа, но данных гораздо больше! Вместо одной точки данных теперь есть временные ряды для полей, содержащих 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 мс метрики « Наибольшая отрисовка содержимого» (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 записей временного ряда по умолчанию и максимум 40 — когда в запросе указано "collectionPeriodCount": 40 Поскольку конечные даты для каждого из этих периодов сбора — субботы, отстоящие друг от друга на 7 дней, при "collectionPeriodCount": 40 это охватывает 10 месяцев.

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

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

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

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

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

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

Заключение

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

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

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

Главное изображение Дэйва Херринга на Unsplash