ReportOpts и его поля

Библиотека Web Vitals предоставляет возможность измерять ключевые метрики производительности веб-страниц, такие как LCP, FID, CLS и другие. Для передачи данных о метриках в сторонние системы используется объект конфигурации ReportOpts, который задаёт параметры поведения функции onReport. Понимание структуры ReportOpts критично для точного и корректного сбора аналитики.

Основная структура ReportOpts

Объект ReportOpts представляет собой JavaScript-объект с рядом полей, каждый из которых отвечает за определённый аспект работы мониторинга:

{
  onReport: function(metric) { ... },
  reportAllChanges: boolean,
  attribution: boolean,
  analyticsId: string,
  // дополнительные поля в зависимости от версии библиотеки
}

Поле onReport

  • Тип: function(metric: Metric) => void

  • Обязательное поле для большинства сценариев использования.

  • Определяет callback, который вызывается при каждом изменении метрики.

  • Параметр metric содержит объект метрики с полями:

    • name — название метрики (LCP, FID, CLS и т.д.)
    • value — числовое значение метрики
    • delta — изменение значения с предыдущего измерения
    • id — уникальный идентификатор конкретного измерения
    • entries — массив PerformanceEntry объектов, связанных с метрикой

Пример использования:

import { getLCP } from 'web-vitals';

getLCP(metric => {
  console.log(metric.name, metric.value);
});

Использование ReportOpts позволяет передавать этот callback централизованно для нескольких метрик.

Поле reportAllChanges

  • Тип: boolean
  • По умолчанию false.
  • Если true, callback onReport будет вызываться при каждом изменении значения метрики, а не только при первом измерении.
  • Полезно для динамически изменяющихся страниц, где LCP или CLS могут корректироваться после взаимодействия пользователя или подгрузки контента.

Пример:

getCLS(metric => {
  console.log(metric);
}, { reportAllChanges: true });

Поле attribution

  • Тип: boolean
  • Отвечает за включение расширенной информации о метрике, например, связывание с конкретными DOM-элементами или событиями.
  • При true в объект метрики добавляются данные для точного анализа источников задержек.

Пример:

import { getFID } from 'web-vitals';

getFID(metric => {
  console.log(metric.entries); // массив EventEntry с подробной информацией
}, { attribution: true });

Поле analyticsId

  • Тип: string
  • Используется для идентификации источника данных в аналитических системах.
  • Часто передаётся в инструменты типа Google Analytics или собственные системы мониторинга.
  • Позволяет группировать метрики по сайту, приложению или конкретному пользователю.

Пример:

getLCP(metric => sendToAnalytics(metric), { analyticsId: 'UA-XXXXX-Y' });

Особенности взаимодействия полей

  1. reportAllChanges + attribution: комбинация этих двух полей позволяет получать детализированные метрики при каждом изменении DOM, что важно для сложных SPA.
  2. onReport + analyticsId: обеспечивает централизованную отправку данных в сторонние сервисы, упрощая интеграцию аналитики.
  3. При отсутствии onReport библиотека не имеет способа сообщить о результатах измерений, даже если заданы остальные поля.

Рекомендации по использованию

  • Для базового мониторинга достаточно указать onReport.
  • Для детального анализа страниц с динамическим контентом следует включать reportAllChanges и attribution.
  • Если данные отправляются в стороннюю систему, использование analyticsId упрощает фильтрацию и агрегацию метрик.
  • Объединение всех полей ReportOpts обеспечивает максимально точное и гибкое управление сбором Web Vitals.

Механизм ReportOpts делает библиотеку Web Vitals не только инструментом измерения, но и платформой для построения сложной аналитики, позволяя учитывать уникальные особенности веб-приложений и их взаимодействие с пользователем.

Оглавление