feat: Add initCoreWebVitals method (#280)

# initCoreWebVitals

add method & documentation

- bypassing sampling is always async
- Update CODEOWNERS

## Deps

- add web-vitals @ 2
- reorder package.json
- make web-vitals a peer dependency


## Tests
- dispatch events
- check endpoint tests
- Math.random mock

Co-authored-by: Alex Sanders <[email protected]>
Co-authored-by: Oliver Lloyd <[email protected]>

.github/CODEOWNERS

@@ -2,3 +2,5 @@
 # please add yourself in a PR
 
 * @guardian/client-side-infra @gtrufitt
+
+src/coreWebVitals*  @guardian/guardian-frontend-team @guardian/commercial-dev

package.json

@@ -31,6 +31,9 @@
     "tsc": "tsc --noEmit --project tsconfig.dev.json",
     "validate": "npm-run-all tsc lint test build"
   },
+  "peerDependencies": {
+    "web-vitals": "^2"
+  },
   "devDependencies": {
     "@guardian/eslint-config": "0.6.0",
     "@guardian/eslint-config-typescript": "0.6.0",
@@ -56,7 +59,8 @@
     "ts-node": "10.2.1",
     "tslib": "2.3.1",
     "typescript": "4.3.5",
-    "wcag-contrast": "^3.0.0"
+    "wcag-contrast": "^3.0.0",
+    "web-vitals": "^2"
   },
   "publishConfig": {
     "access": "public"

src/coreWebVitals.README.md

@@ -0,0 +1,108 @@
+# Core Web Vitals
+
+Reports on Core Web Vitals using Google’s [`web-vitals`] library, and send the
+metrics to an logging endpoint when the user leaves the page.
+
+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
+as initialisation or bypass it asynchronously.
+
+[`web-vitals`]: https://github.com/GoogleChrome/web-vitals
+
+## Usage
+
+```js
+import { initCoreWebVitals, getCookie } from '@guardian/libs';
+
+// browserId & pageViewId are needed to join up the data downstream.
+const init: InitCoreWebVitalsOptions = {
+    browserId : getCookie({ name: 'bwid', shouldMemoize: true}),
+    pageViewId: guardian.ophan.config.pageViewId,
+
+    // Whether to use CODE or PROD endpoints.
+    isDev: window.location.hostname !== 'www.theguardian.com',
+}
+
+initCoreWebVitals(init)
+```
+
+### `init.sampling`
+
+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)
+```
+
+### `init.team`
+
+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 […]')
+```
+
+### `bypassCoreWebVitalsSampling`
+
+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
+
+### `CoreWebVitalsPayload`
+
+```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;
+};
+```
+
+### `InitCoreWebVitalsOptions`
+
+```ts
+type InitCoreWebVitalsOptions = {
+	isDev: boolean;
+
+	browserId?: string | null;
+	pageViewId?: string | null;
+
+	sampling?: number;
+	team?: TeamName;
+};
+```