@guardian/commercial-core 0.41.0 → 1.0.0

package/dist/cjs/index.d.ts

@@ -5,7 +5,7 @@ export { twitter } from './third-party-tags/twitter-uwt';
 export { inizio } from './third-party-tags/inizio';
 export { remarketing } from './third-party-tags/remarketing';
 export { EventTimer } from './EventTimer';
-export { sendCommercialMetrics } from './sendCommercialMetrics';
+export { bypassCommercialMetricsSampling, initCommercialMetrics, } from './sendCommercialMetrics';
 export type { ThirdPartyTag } from './types';
 export { adSizes, getAdSize } from './ad-sizes';
 export type { SizeKeys, AdSizeString, AdSize } from './ad-sizes';

package/dist/cjs/index.js

@@ -20,7 +20,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pickTargetingValues = exports.getViewportTargeting = exports.getSharedTargeting = exports.getSessionTargeting = exports.getPersonalisedTargeting = exports.getContentTargeting = exports.constants = exports.disabledAds = exports.buildAdsConfigWithConsent = exports.getPermutivePFPSegments = exports.getPermutiveSegments = exports.clearPermutiveSegments = exports.isAdBlockInUse = exports.getAdSize = exports.adSizes = exports.sendCommercialMetrics = exports.EventTimer = exports.remarketing = exports.inizio = exports.twitter = exports.fbPixel = exports.permutive = exports.ias = void 0;
+exports.pickTargetingValues = exports.getViewportTargeting = exports.getSharedTargeting = exports.getSessionTargeting = exports.getPersonalisedTargeting = exports.getContentTargeting = exports.constants = exports.disabledAds = exports.buildAdsConfigWithConsent = exports.getPermutivePFPSegments = exports.getPermutiveSegments = exports.clearPermutiveSegments = exports.isAdBlockInUse = exports.getAdSize = exports.adSizes = exports.initCommercialMetrics = exports.bypassCommercialMetricsSampling = exports.EventTimer = exports.remarketing = exports.inizio = exports.twitter = exports.fbPixel = exports.permutive = exports.ias = void 0;
 var ias_1 = require("./third-party-tags/ias");
 Object.defineProperty(exports, "ias", { enumerable: true, get: function () { return ias_1.ias; } });
 var permutive_1 = require("./third-party-tags/permutive");
@@ -36,7 +36,8 @@ Object.defineProperty(exports, "remarketing", { enumerable: true, get: function
 var EventTimer_1 = require("./EventTimer");
 Object.defineProperty(exports, "EventTimer", { enumerable: true, get: function () { return EventTimer_1.EventTimer; } });
 var sendCommercialMetrics_1 = require("./sendCommercialMetrics");
-Object.defineProperty(exports, "sendCommercialMetrics", { enumerable: true, get: function () { return sendCommercialMetrics_1.sendCommercialMetrics; } });
+Object.defineProperty(exports, "bypassCommercialMetricsSampling", { enumerable: true, get: function () { return sendCommercialMetrics_1.bypassCommercialMetricsSampling; } });
+Object.defineProperty(exports, "initCommercialMetrics", { enumerable: true, get: function () { return sendCommercialMetrics_1.initCommercialMetrics; } });
 var ad_sizes_1 = require("./ad-sizes");
 Object.defineProperty(exports, "adSizes", { enumerable: true, get: function () { return ad_sizes_1.adSizes; } });
 Object.defineProperty(exports, "getAdSize", { enumerable: true, get: function () { return ad_sizes_1.getAdSize; } });

package/dist/cjs/sendCommercialMetrics.d.ts

@@ -1 +1,43 @@
-export declare function sendCommercialMetrics(pageViewId: string, browserId: string | undefined, isDev: boolean, adBlockerInUse?: boolean): boolean;
+declare type Metric = {
+    name: string;
+    value: number;
+};
+declare type Property = {
+    name: string;
+    value: string;
+};
+declare type TimedEvent = {
+    name: string;
+    ts: number;
+};
+declare type EventProperties = {
+    type?: ConnectionType;
+    downlink?: number;
+    effectiveType?: string;
+};
+declare enum Endpoints {
+    CODE = "//performance-events.code.dev-guardianapis.com/commercial-metrics",
+    PROD = "//performance-events.guardianapis.com/commercial-metrics"
+}
+/**
+ * A method to asynchronously send metrics after initialization.
+ */
+export declare function bypassCommercialMetricsSampling(): void;
+/**
+ * A method to initialise metrics.
+ * @param init.pageViewId - identifies the page view. Usually available on `guardian.config.ophan.pageViewId`. Defaults to `null`
+ * @param init.browserId - identifies the browser. Usually available via `getCookie({ name: 'bwid' })`. Defaults to `null`
+ * @param init.isDev - used to determine whether to use CODE or PROD endpoints.
+ * @param init.adBlockerInUse - indicates whether or not ann adblocker is being used.
+ */
+export declare function initCommercialMetrics(pageViewId: string, browserId: string | undefined, isDev: boolean, adBlockerInUse?: boolean, sampling?: number): boolean;
+export declare const _: {
+    Endpoints: typeof Endpoints;
+    setEndpoint: (isDev: boolean) => Endpoints;
+    filterUndefinedProperties: <T>(transformedProperties: [string, T | undefined][]) => [string, T][];
+    mapEventTimerPropertiesToString: (properties: Array<[string, string | number]>) => Property[];
+    roundTimeStamp: (events: TimedEvent[]) => Metric[];
+    transformToObjectEntries: (eventTimerProperties: EventProperties) => Array<[string, string | number | undefined]>;
+    reset: () => void;
+};
+export type { Property, TimedEvent, Metric };

package/dist/cjs/sendCommercialMetrics.js

@@ -1,44 +1,150 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sendCommercialMetrics = void 0;
+exports._ = exports.initCommercialMetrics = exports.bypassCommercialMetricsSampling = void 0;
 const libs_1 = require("@guardian/libs");
 const EventTimer_1 = require("./EventTimer");
-function sendCommercialMetrics(pageViewId, browserId, isDev, adBlockerInUse) {
-    const devProperties = isDev
-        ? [{ name: 'isDev', value: window.location.hostname }]
-        : [];
-    const adBlockerProperties = adBlockerInUse !== undefined
-        ? [
-            {
-                name: 'adBlockerInUse',
-                value: adBlockerInUse.toString(),
-            },
-        ]
-        : [];
-    const endpoint = isDev
-        ? '//performance-events.code.dev-guardianapis.com/commercial-metrics'
-        : '//performance-events.guardianapis.com/commercial-metrics';
-    if (document.visibilityState !== 'hidden')
-        return false;
-    const eventTimer = EventTimer_1.EventTimer.get();
-    const events = eventTimer.events;
-    const properties = Object.entries(eventTimer.properties)
-        .filter(([, value]) => typeof value !== 'undefined')
-        .map(([name, value]) => ({ name, value: String(value) }))
-        .concat(devProperties)
-        .concat(adBlockerProperties);
-    const metrics = events.map(({ name, ts }) => ({
+var Endpoints;
+(function (Endpoints) {
+    Endpoints["CODE"] = "//performance-events.code.dev-guardianapis.com/commercial-metrics";
+    Endpoints["PROD"] = "//performance-events.guardianapis.com/commercial-metrics";
+})(Endpoints || (Endpoints = {}));
+let commercialMetricsPayload = {
+    page_view_id: undefined,
+    browser_id: undefined,
+    platform: 'NEXT_GEN',
+    metrics: [],
+    properties: [],
+};
+let devProperties = [];
+let adBlockerProperties = [];
+let initialised = false;
+let endpoint;
+const setEndpoint = (isDev) => (endpoint = isDev ? Endpoints.CODE : Endpoints.PROD);
+const setDevProperties = (isDev) => (devProperties = isDev
+    ? [{ name: 'isDev', value: window.location.hostname }]
+    : []);
+const setAdBlockerProperties = (adBlockerInUse) => {
+    adBlockerProperties =
+        adBlockerInUse !== undefined
+            ? [
+                {
+                    name: 'adBlockerInUse',
+                    value: adBlockerInUse.toString(),
+                },
+            ]
+            : [];
+};
+const transformToObjectEntries = (eventTimerProperties) => {
+    // Transforms object {key: value} pairs into an array of [key, value] arrays
+    return Object.entries(eventTimerProperties);
+};
+const filterUndefinedProperties = (transformedProperties) => transformedProperties.reduce((acc, [key, value]) => {
+    if (typeof value !== 'undefined') {
+        acc.push([key, value]);
+    }
+    return acc;
+}, []);
+const mapEventTimerPropertiesToString = (properties) => {
+    return properties.map(([name, value]) => ({
+        name: String(name),
+        value: String(value),
+    }));
+};
+const roundTimeStamp = (events) => {
+    return events.map(({ name, ts }) => ({
         name,
         value: Math.ceil(ts),
     }));
-    const commercialMetrics = {
-        browser_id: browserId,
-        page_view_id: pageViewId,
-        platform: 'NEXT_GEN',
-        metrics,
-        properties,
-    };
-    (0, libs_1.log)('commercial', 'About to send commercial metrics', commercialMetrics);
-    return navigator.sendBeacon(endpoint, JSON.stringify(commercialMetrics));
+};
+function sendMetrics() {
+    (0, libs_1.log)('commercial', 'About to send commercial metrics', commercialMetricsPayload);
+    return navigator.sendBeacon(endpoint, JSON.stringify(commercialMetricsPayload));
+}
+function gatherMetricsOnPageUnload() {
+    // Assemble commercial properties and metrics
+    const eventTimer = EventTimer_1.EventTimer.get();
+    const transformedEntries = transformToObjectEntries(eventTimer.properties);
+    const filteredEventTimerProperties = filterUndefinedProperties(transformedEntries);
+    const mappedEventTimerProperties = mapEventTimerPropertiesToString(filteredEventTimerProperties);
+    const properties = mappedEventTimerProperties
+        .concat(devProperties)
+        .concat(adBlockerProperties);
+    commercialMetricsPayload.properties = properties;
+    const metrics = roundTimeStamp(eventTimer.events);
+    commercialMetricsPayload.metrics = metrics;
+    sendMetrics();
+}
+const listener = (e) => {
+    switch (e.type) {
+        case 'visibilitychange':
+            if (document.visibilityState === 'hidden') {
+                gatherMetricsOnPageUnload();
+            }
+            return;
+        case 'pagehide':
+            gatherMetricsOnPageUnload();
+            return;
+    }
+};
+const addVisibilityListeners = () => {
+    // Report all available metrics when the page is unloaded or in background.
+    window.addEventListener('visibilitychange', listener);
+    // Safari does not reliably fire the `visibilitychange` on page unload.
+    window.addEventListener('pagehide', listener);
+};
+/**
+ * A method to asynchronously send metrics after initialization.
+ */
+function bypassCommercialMetricsSampling() {
+    if (!initialised) {
+        console.warn('initCommercialMetrics not yet initialised');
+        return;
+    }
+    addVisibilityListeners();
+}
+exports.bypassCommercialMetricsSampling = bypassCommercialMetricsSampling;
+/**
+ * A method to initialise metrics.
+ * @param init.pageViewId - identifies the page view. Usually available on `guardian.config.ophan.pageViewId`. Defaults to `null`
+ * @param init.browserId - identifies the browser. Usually available via `getCookie({ name: 'bwid' })`. Defaults to `null`
+ * @param init.isDev - used to determine whether to use CODE or PROD endpoints.
+ * @param init.adBlockerInUse - indicates whether or not ann adblocker is being used.
+ */
+function initCommercialMetrics(pageViewId, browserId, isDev, adBlockerInUse, sampling = 1 / 100) {
+    commercialMetricsPayload.page_view_id = pageViewId;
+    commercialMetricsPayload.browser_id = browserId;
+    setEndpoint(isDev);
+    setDevProperties(isDev);
+    setAdBlockerProperties(adBlockerInUse);
+    if (initialised) {
+        return false;
+    }
+    initialised = true;
+    const userIsInSamplingGroup = Math.random() <= sampling;
+    if (isDev || userIsInSamplingGroup) {
+        addVisibilityListeners();
+        return true;
+    }
+    return false;
 }
-exports.sendCommercialMetrics = sendCommercialMetrics;
+exports.initCommercialMetrics = initCommercialMetrics;
+exports._ = {
+    Endpoints,
+    setEndpoint,
+    filterUndefinedProperties,
+    mapEventTimerPropertiesToString,
+    roundTimeStamp,
+    transformToObjectEntries,
+    reset: () => {
+        initialised = false;
+        commercialMetricsPayload = {
+            page_view_id: undefined,
+            browser_id: undefined,
+            platform: 'NEXT_GEN',
+            metrics: [],
+            properties: [],
+        };
+        removeEventListener('visibilitychange', listener);
+        removeEventListener('pagehide', listener);
+    },
+};

package/dist/esm/index.d.ts

@@ -5,7 +5,7 @@ export { twitter } from './third-party-tags/twitter-uwt';
 export { inizio } from './third-party-tags/inizio';
 export { remarketing } from './third-party-tags/remarketing';
 export { EventTimer } from './EventTimer';
-export { sendCommercialMetrics } from './sendCommercialMetrics';
+export { bypassCommercialMetricsSampling, initCommercialMetrics, } from './sendCommercialMetrics';
 export type { ThirdPartyTag } from './types';
 export { adSizes, getAdSize } from './ad-sizes';
 export type { SizeKeys, AdSizeString, AdSize } from './ad-sizes';

package/dist/esm/index.js

@@ -6,7 +6,7 @@ export { twitter } from './third-party-tags/twitter-uwt';
 export { inizio } from './third-party-tags/inizio';
 export { remarketing } from './third-party-tags/remarketing';
 export { EventTimer } from './EventTimer';
-export { sendCommercialMetrics } from './sendCommercialMetrics';
+export { bypassCommercialMetricsSampling, initCommercialMetrics, } from './sendCommercialMetrics';
 export { adSizes, getAdSize } from './ad-sizes';
 export { isAdBlockInUse } from './detectAdBlocker';
 export { clearPermutiveSegments, getPermutiveSegments, getPermutivePFPSegments, } from './permutive';

package/dist/esm/sendCommercialMetrics.d.ts

@@ -1 +1,43 @@
-export declare function sendCommercialMetrics(pageViewId: string, browserId: string | undefined, isDev: boolean, adBlockerInUse?: boolean): boolean;
+declare type Metric = {
+    name: string;
+    value: number;
+};
+declare type Property = {
+    name: string;
+    value: string;
+};
+declare type TimedEvent = {
+    name: string;
+    ts: number;
+};
+declare type EventProperties = {
+    type?: ConnectionType;
+    downlink?: number;
+    effectiveType?: string;
+};
+declare enum Endpoints {
+    CODE = "//performance-events.code.dev-guardianapis.com/commercial-metrics",
+    PROD = "//performance-events.guardianapis.com/commercial-metrics"
+}
+/**
+ * A method to asynchronously send metrics after initialization.
+ */
+export declare function bypassCommercialMetricsSampling(): void;
+/**
+ * A method to initialise metrics.
+ * @param init.pageViewId - identifies the page view. Usually available on `guardian.config.ophan.pageViewId`. Defaults to `null`
+ * @param init.browserId - identifies the browser. Usually available via `getCookie({ name: 'bwid' })`. Defaults to `null`
+ * @param init.isDev - used to determine whether to use CODE or PROD endpoints.
+ * @param init.adBlockerInUse - indicates whether or not ann adblocker is being used.
+ */
+export declare function initCommercialMetrics(pageViewId: string, browserId: string | undefined, isDev: boolean, adBlockerInUse?: boolean, sampling?: number): boolean;
+export declare const _: {
+    Endpoints: typeof Endpoints;
+    setEndpoint: (isDev: boolean) => Endpoints;
+    filterUndefinedProperties: <T>(transformedProperties: [string, T | undefined][]) => [string, T][];
+    mapEventTimerPropertiesToString: (properties: Array<[string, string | number]>) => Property[];
+    roundTimeStamp: (events: TimedEvent[]) => Metric[];
+    transformToObjectEntries: (eventTimerProperties: EventProperties) => Array<[string, string | number | undefined]>;
+    reset: () => void;
+};
+export type { Property, TimedEvent, Metric };

package/dist/esm/sendCommercialMetrics.js

@@ -1,40 +1,145 @@
 import { log } from '@guardian/libs';
 import { EventTimer } from './EventTimer';
-export function sendCommercialMetrics(pageViewId, browserId, isDev, adBlockerInUse) {
-    const devProperties = isDev
-        ? [{ name: 'isDev', value: window.location.hostname }]
-        : [];
-    const adBlockerProperties = adBlockerInUse !== undefined
-        ? [
-            {
-                name: 'adBlockerInUse',
-                value: adBlockerInUse.toString(),
-            },
-        ]
-        : [];
-    const endpoint = isDev
-        ? '//performance-events.code.dev-guardianapis.com/commercial-metrics'
-        : '//performance-events.guardianapis.com/commercial-metrics';
-    if (document.visibilityState !== 'hidden')
-        return false;
-    const eventTimer = EventTimer.get();
-    const events = eventTimer.events;
-    const properties = Object.entries(eventTimer.properties)
-        .filter(([, value]) => typeof value !== 'undefined')
-        .map(([name, value]) => ({ name, value: String(value) }))
-        .concat(devProperties)
-        .concat(adBlockerProperties);
-    const metrics = events.map(({ name, ts }) => ({
+var Endpoints;
+(function (Endpoints) {
+    Endpoints["CODE"] = "//performance-events.code.dev-guardianapis.com/commercial-metrics";
+    Endpoints["PROD"] = "//performance-events.guardianapis.com/commercial-metrics";
+})(Endpoints || (Endpoints = {}));
+let commercialMetricsPayload = {
+    page_view_id: undefined,
+    browser_id: undefined,
+    platform: 'NEXT_GEN',
+    metrics: [],
+    properties: [],
+};
+let devProperties = [];
+let adBlockerProperties = [];
+let initialised = false;
+let endpoint;
+const setEndpoint = (isDev) => (endpoint = isDev ? Endpoints.CODE : Endpoints.PROD);
+const setDevProperties = (isDev) => (devProperties = isDev
+    ? [{ name: 'isDev', value: window.location.hostname }]
+    : []);
+const setAdBlockerProperties = (adBlockerInUse) => {
+    adBlockerProperties =
+        adBlockerInUse !== undefined
+            ? [
+                {
+                    name: 'adBlockerInUse',
+                    value: adBlockerInUse.toString(),
+                },
+            ]
+            : [];
+};
+const transformToObjectEntries = (eventTimerProperties) => {
+    // Transforms object {key: value} pairs into an array of [key, value] arrays
+    return Object.entries(eventTimerProperties);
+};
+const filterUndefinedProperties = (transformedProperties) => transformedProperties.reduce((acc, [key, value]) => {
+    if (typeof value !== 'undefined') {
+        acc.push([key, value]);
+    }
+    return acc;
+}, []);
+const mapEventTimerPropertiesToString = (properties) => {
+    return properties.map(([name, value]) => ({
+        name: String(name),
+        value: String(value),
+    }));
+};
+const roundTimeStamp = (events) => {
+    return events.map(({ name, ts }) => ({
         name,
         value: Math.ceil(ts),
     }));
-    const commercialMetrics = {
-        browser_id: browserId,
-        page_view_id: pageViewId,
-        platform: 'NEXT_GEN',
-        metrics,
-        properties,
-    };
-    log('commercial', 'About to send commercial metrics', commercialMetrics);
-    return navigator.sendBeacon(endpoint, JSON.stringify(commercialMetrics));
+};
+function sendMetrics() {
+    log('commercial', 'About to send commercial metrics', commercialMetricsPayload);
+    return navigator.sendBeacon(endpoint, JSON.stringify(commercialMetricsPayload));
+}
+function gatherMetricsOnPageUnload() {
+    // Assemble commercial properties and metrics
+    const eventTimer = EventTimer.get();
+    const transformedEntries = transformToObjectEntries(eventTimer.properties);
+    const filteredEventTimerProperties = filterUndefinedProperties(transformedEntries);
+    const mappedEventTimerProperties = mapEventTimerPropertiesToString(filteredEventTimerProperties);
+    const properties = mappedEventTimerProperties
+        .concat(devProperties)
+        .concat(adBlockerProperties);
+    commercialMetricsPayload.properties = properties;
+    const metrics = roundTimeStamp(eventTimer.events);
+    commercialMetricsPayload.metrics = metrics;
+    sendMetrics();
+}
+const listener = (e) => {
+    switch (e.type) {
+        case 'visibilitychange':
+            if (document.visibilityState === 'hidden') {
+                gatherMetricsOnPageUnload();
+            }
+            return;
+        case 'pagehide':
+            gatherMetricsOnPageUnload();
+            return;
+    }
+};
+const addVisibilityListeners = () => {
+    // Report all available metrics when the page is unloaded or in background.
+    window.addEventListener('visibilitychange', listener);
+    // Safari does not reliably fire the `visibilitychange` on page unload.
+    window.addEventListener('pagehide', listener);
+};
+/**
+ * A method to asynchronously send metrics after initialization.
+ */
+export function bypassCommercialMetricsSampling() {
+    if (!initialised) {
+        console.warn('initCommercialMetrics not yet initialised');
+        return;
+    }
+    addVisibilityListeners();
+}
+/**
+ * A method to initialise metrics.
+ * @param init.pageViewId - identifies the page view. Usually available on `guardian.config.ophan.pageViewId`. Defaults to `null`
+ * @param init.browserId - identifies the browser. Usually available via `getCookie({ name: 'bwid' })`. Defaults to `null`
+ * @param init.isDev - used to determine whether to use CODE or PROD endpoints.
+ * @param init.adBlockerInUse - indicates whether or not ann adblocker is being used.
+ */
+export function initCommercialMetrics(pageViewId, browserId, isDev, adBlockerInUse, sampling = 1 / 100) {
+    commercialMetricsPayload.page_view_id = pageViewId;
+    commercialMetricsPayload.browser_id = browserId;
+    setEndpoint(isDev);
+    setDevProperties(isDev);
+    setAdBlockerProperties(adBlockerInUse);
+    if (initialised) {
+        return false;
+    }
+    initialised = true;
+    const userIsInSamplingGroup = Math.random() <= sampling;
+    if (isDev || userIsInSamplingGroup) {
+        addVisibilityListeners();
+        return true;
+    }
+    return false;
 }
+export const _ = {
+    Endpoints,
+    setEndpoint,
+    filterUndefinedProperties,
+    mapEventTimerPropertiesToString,
+    roundTimeStamp,
+    transformToObjectEntries,
+    reset: () => {
+        initialised = false;
+        commercialMetricsPayload = {
+            page_view_id: undefined,
+            browser_id: undefined,
+            platform: 'NEXT_GEN',
+            metrics: [],
+            properties: [],
+        };
+        removeEventListener('visibilitychange', listener);
+        removeEventListener('pagehide', listener);
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guardian/commercial-core",
-  "version": "0.41.0",
+  "version": "1.0.0",
   "description": "Guardian advertising business logic",
   "homepage": "https://github.com/guardian/commercial-core#readme",
   "bugs": {
@@ -26,6 +26,7 @@
     "precommit:lint": "lint-staged",
     "prepush:test": "jest --verbose --runInBand --onlyChanged",
     "test": "jest",
+    "test:watch": "jest --watch",
     "test:ci": "jest --coverage --ci",
     "tsc": "tsc --noEmit",
     "validate": "npm-run-all tsc lint test build",