@guardian/core-web-vitals


Installation


``bash
yarn add @guardian/core-web-vitals
`

or

`bash
npm install @guardian/core-web-vitals
`

then

`js
import {
initCoreWebVitals,
bypassCoreWebVitalsSampling,
} from '@guardian/core-web-vitals';
`

$3

This package uses ES2020.

If your target environment does not support that, make sure you transpile this package when bundling your application.

Usage

_By default, a sampling rate is set at 1% for which Core Web Vitals will be
gathered and sent. It is possible to set this sampling to a different value
at initialisation or bypass it asynchronously (see below)._

`js
import { initCoreWebVitals, getCookie } from '@guardian/core-web-vitals';

// browserId & pageViewId are needed to join up the data downstream.
const init: InitCoreWebVitalsOptions = {
browserId: getCookie({ name: 'bwid', shouldMemoize: true }),
pageViewId: guardian.config.ophan.pageViewId,

// Whether to use CODE or PROD endpoints.
isDev: window.location.hostname !== 'www.theguardian.com',
};

initCoreWebVitals(init);
`

$3

Sets a sampling rate for which to send data to the logging endpoint.

Defaults to 1 / 100.

`ts
const init: InitCoreWebVitalsOptions = {
isDev: false,

// Send data for 20% of page views. Inform Data Tech team about expected
// spikes in data ingestion
sampling: 20 / 100,
};

initCoreWebVitals(init);
`

$3

Optional team name to log whether the payload has been successfully queued for
transfer.

`ts
const init: InitCoreWebVitalsOptions = {
isDev: false,
sampling: 100 / 100,
team: 'dotcom',
};

initCoreWebVitals(init);

// should call log('dotcom', 'Core Web Vitals payload successfully queued […]')
`

$3

Optional platform which is passed through to the events-collector and can be
used to segment data downstream. Defaults to dcr in the events-collector if
not specified.

`ts
const init: InitCoreWebVitalsOptions = {
isDev: false,
platform: 'support',
};

initCoreWebVitals(init);
`

$3

Allows to asynchronously bypass the sampling rate.

Takes an optional team name for which to print logs for.

`ts
/ … after having called initCoreWebVitals() … /

addEventListener('some-event', () => {
// CWV will be sent for all page views where some-event was triggered
bypassCoreWebVitalsSampling();
});
`

Types

$3

`ts
type CoreWebVitalsPayload = {
page_view_id: string | null;
browser_id: string | null;
fid: null | number;
cls: null | number;
lcp: null | number;
fcp: null | number;
ttfb: null | number;
};
`

$3

`ts
type InitCoreWebVitalsOptions = {
isDev: boolean;

browserId?: string | null;
pageViewId?: string | null;

sampling?: number;
team?: TeamName;
};
``