Web Vitals

Для сбора Web Vitals подключите модуль Performance. Запросить подключение можно через чат поддержки.

Инициализация модуля

Установите библиотеку web-vitals и передайте её функции в initTracerPerformanceWebVitals. Модуль подключит сбор метрик, а для их отправки будет использоваться общий модуль Performance. В состав SDK библиотека web-vitals не входит.

Например, для подключения версии 4.2.4:

npm install @apptracer/sdk web-vitals@4.2.4

import { onCLS, onFCP, onLCP, onINP, onTTFB } from 'web-vitals';
import { initTracerPerformanceWebVitals, initTracerPerformanceUploader } from '@apptracer/sdk';

const webVitals = { onCLS, onFCP, onLCP, onINP, onTTFB };

initTracerPerformanceWebVitals({ webVitals });

initTracerPerformanceUploader({
    versionName: BUILD_VERSION_NAME, // строка с версией приложения из вашей сборки
    appToken: 'appToken из настроек в Трейсере',
});

Конфигурация initTracerPerformanceWebVitals

Параметр	Тип	Описание
`webVitals`	`ITracerWebVitals`	Обязательный объект с функциями `onCLS`, `onFCP`, `onLCP`, `onINP`, `onTTFB`. Каждая принимает callback метрики и необязательные настройки с `reportAllChanges`.
`webVitalsMetricAttributes?`	`(metric) => ITracerPerformanceAttributes`	Добавляет пользовательские атрибуты. Получает исходную метрику с типами и дополнительными полями выбранного источника.

Подключение проверено с версиями 4.2.4 и 6.2.2. Если вы выбрали 6.2.2, установите web-vitals@6.2.2 — код инициализации SDK останется тем же. Используйте одну версию библиотеки в приложении. Для других версий проверьте, подходят ли их функции для этого интерфейса и корректно ли собираются метрики.

Если нужны дополнительные данные о метриках, передайте те же пять функций из web-vitals/attribution. В webVitalsMetricAttributes будут доступны их дополнительные поля с соответствующими типами. Состав полей зависит от версии библиотеки.

CLS сохраняется как безразмерное значение. Остальные метрики переводятся из миллисекунд в наносекунды.

Для CLS, FCP, INP и TTFB сохраняется delta, а для LCP — и delta, и value. Нулевые и отрицательные значения пропускаются. Например, если CLS равен нулю, соответствующего замера в Tracer не будет.

К вашим атрибутам SDK добавляет rating, navigationType и, при наличии данных, сведения о DOM-элементах. Если имена совпадают, используются значения SDK.

Общая инициализация и типы

При использовании initTracerSdk передайте тот же объект webVitals в общую конфигурацию.
Чтобы обработчик метрик сохранил точные типы выбранной библиотеки, укажите тип объекта у инициализатора:

import { onCLS, onFCP, onLCP, onINP, onTTFB } from 'web-vitals';
import { initTracerSdk, initTracerPerformanceWebVitals, initTracerPerformanceUploader } from '@apptracer/sdk';

const webVitals = { onCLS, onFCP, onLCP, onINP, onTTFB };

initTracerSdk(
    {
        webVitals,
        webVitalsMetricAttributes: function (metric) {
            return { metricId: metric.id };
        },
        versionName: BUILD_VERSION_NAME, // строка с версией приложения из вашей сборки
        appToken: 'appToken из настроек в Трейсере',
    },
    initTracerPerformanceWebVitals<typeof webVitals>,
    initTracerPerformanceUploader,
);

Подключайте Web Vitals один раз: повторный вызов инициализатора вызовет исключение. При disableTracerModules() SDK перестаёт принимать метрики, а enableTracerModules() возобновляет их приём без повторного подключения обработчиков. Наблюдатели самой библиотеки работают и во время паузы.

Убедитесь, что выбранная версия web-vitals поддерживает ваши браузеры. При необходимости настройте её транспиляцию и добавьте полифилы в приложение: Legacy-сборка SDK этого не делает.

Без Map, Promise или PerformanceObserver SDK не подключает сбор метрик.

Миграция

Замены имён и порядок перехода собраны в руководстве по миграции.