@guardian/ophan-tracker-js 4.0.2 → 5.1.0

package/readme.md

@@ -10,76 +10,148 @@ $ npm install @guardian/ophan-tracker-js
 
 ## Usage
 
-Tracker JS contains multiple entry point files tailored to specific platforms. These include:
+Tracker JS is available as both an NPM package and a CDN distribution.
 
-- `ng.js` (short for next-gen) for the theguardian.com
-- `manage-my-account.js` for manage.theguardian.com
-- `support.js` for support.theguardian.com
-- `membership.js` for membership-related sections
+### NPM Package
 
-**Default Behaviour**
+The NPM package uses a unified entry point that supports multiple platforms. Import it eagerly and call `init()` once for your platform before calling any other tracker method. The platform defaults to `ng` when omitted or unrecognised at runtime.
 
-The [default entry point](https://github.com/guardian/ophan/blob/main/tracker-js/package.json#L12) for the library is `ng.js`. With this entry point, the library automatically initializes itself on the global window object and provides a suite of functionalities to monitor user interactions, visibility, and more. 
-The library will send an initial [page view event](/tracker-js/src/types/event.ts#L15) on page load. You are then in control of sending other events to Ophan.
+**NPM Supported Platforms**
+
+- `ng` (short for next-gen) for theguardian.com
+- `manage-my-account` for manage.theguardian.com
+- `support` for support.theguardian.com
+
+**Default behaviour**
+
+The default entry point for the library is `@guardian/ophan-tracker-js`, which resolves to `NPM-dist/index.js`. Calling `init()` starts the tracker for the chosen platform and sends the initial page-view event. Use `record()` for additional events. Use `sendInitialEvent()` only when you intentionally need a new page-view event, for example after a single-page app route change.
+
+If a tracker method is called before `init()` in a browser context, the method warns and does not send the event. In server-side rendering or other non-browser contexts, tracker methods return without touching browser globals.
+
+### CDN Distribution
+
+The CDN version provides individual entry points for specific use cases, available at `https://j.ophan.co.uk/`. These entry points initialise themselves for their historical platform and are kept for existing CDN consumers:
+
+- `contribution.js` - Contribution tracking
+- `embed.js` - For embedded content
+- `fb-instant.js` - For Facebook Instant Articles
+- `holidays.js` - Guardian Holidays
+- `http-status.js` - HTTP status page tracking
+- `interactive.js` - For Guardian interactives
+- `jobs.js` - For Guardian Jobs site
+- `jobs-courses.js` - For Guardian Jobs courses site
+- `membership.js` - For Guardian membership (old site)
+- `ng.js` - For theguardian.com
+- `r2.js` - Legacy R2 platform tracking
+- `smart-news.js` - SmartNews platform tracking
+- `witness.js` - GuardianWitness tracking
+
+#### Plain `<script src>` (IIFE) build
+
+The AMD (`ophan/*.js`) and SystemJS (`*.js`) CDN builds both require a module
+loader on the page. For consumers that have **no module loader and no bundler**
+— e.g. the Salesforce-hosted Help Centre — there is a self-executing IIFE build:
+
+- `help-centre.iife.js` - Self-initialises platform) and exposes the full
+   tracker API at `window.guardian.ophan`.
+
+```html
+<!-- Sends the first page view on load; no page-side boot code needed. -->
+<script src="https://j.ophan.co.uk/help-centre.iife.js"></script>
+<script>
+  // Single-page-app route change: sends a fresh page view.
+  window.guardian.ophan.sendInitialEvent();
+  // Component/interaction events:
+  window.guardian.ophan.record({ componentEvent: { /* … */ } });
+</script>
+```
 
 You can see example usage of the library on theguardian.com [here](https://github.com/guardian/dotcom-rendering/blob/main/dotcom-rendering/src/client/ophan/ophan.ts)
 
-1. **Import and start the library:**
+1. **Import and initialise the library:**
 
-   The library should be imported and executed eagerly (non-lazily) to ensure proper initialization. The exact syntax may vary depending on your build tool or environment.
+   The library should be imported and initialised eagerly (non-lazily) to ensure proper initialisation. The exact syntax may vary depending on your build tool or environment.
 
    ```javascript
-   import ophan from '@guardian/ophan-tracker-js';
+   import { init, record } from '@guardian/ophan-tracker-js';
+
+   // Initialise for your platform. This sends the initial page-view event.
+   init('ng'); // or 'manage-my-account' or 'support'
    ```
 
-2. **Send Tracking Events with `ophan.record()`:**
+2. **Send Tracking Events with `record()`:**
 
    ```javascript
-   ophan.record({
-       // Your tracking data in JSON format
+   record({
+       edition: 'UK',
    });
    ```
 
-### Usage with Typescript
+### Usage with TypeScript
+
+The package exports TypeScript declarations, declaration maps, and source files. Editors should let you click through from `record()` to `EventPayload`, `ComponentEvent`, `Product`, and the related union types in [`src/types/event.ts`](/tracker-js/src/types/event.ts) and the neighbouring type files.
 
-Refer to the type definitions within the library for the structure of valid tracking events.  The `ophan.record()` function accepts a type of `EventPayload` found [here](/tracker-js/src/types/event.ts#L90). 
+When you pass an object literal to `record()`, TypeScript will reject unknown top-level fields and invalid nested values such as unsupported component actions, component types, products, or editions. If you need to add a new event type or property, update the tracker-js types and the downstream Ophan model deliberately.
 
 #### Example Usage
 
 ```typescript
-import ophan, { Product, ComponentEvent } from '@guardian/ophan-tracker-js';
-import type { AbTest } from '@guardian/ophan-tracker-js';
-
-const exampleProduct: TProduct = "APP_PREMIUM_TIER";
+import {
+	getViewId,
+	init,
+	record,
+	sendInitialEvent,
+} from '@guardian/ophan-tracker-js';
+import type {
+	EventPayload,
+	Product,
+	ComponentEvent,
+	AbTest,
+} from '@guardian/ophan-tracker-js';
+
+// Initialise the library for your platform. This sends the initial page-view event.
+init('ng'); // or 'manage-my-account' or 'support'
+
+const exampleProduct: Product = 'APP_PREMIUM_TIER';
 const exampleAbTest: AbTest = {
-   name: "myAbTest",
-   variant: "variant",
-   campaignCodes: ["code1", "code2"]
+	name: 'myAbTest',
+	variant: 'variant',
+	campaignCodes: ['code1', 'code2'],
 };
 
 const componentV2 = {
-   componentType: "ACQUISITIONS_BUTTON",
-   id: "component-id",
-   products: new Set([exampleProduct]),
-   campaignCode: "campaign-code",
-   labels: new Set(["label1", "label2"]),
+	componentType: 'ACQUISITIONS_BUTTON',
+	id: 'component-id',
+	products: [exampleProduct],
+	campaignCode: 'campaign-code',
+	labels: ['label1', 'label2'],
 };
 
 const componentEvent: ComponentEvent = {
-   component: componentV2,
-   action: "CLICK",
-   value: "some-value",
-   id: "event-id",
-   abTest: exampleAbTest,
-   targetingAbTest: exampleAbTest,
+	component: componentV2,
+	action: 'CLICK',
+	value: 'some-value',
+	id: 'event-id',
+	abTest: exampleAbTest,
+	targetingAbTest: exampleAbTest,
 };
 
-ophan.record({
-   componentEvent: componentEvent
-});
+const payload: EventPayload = {
+	componentEvent: componentEvent,
+};
+
+record(payload);
+
+const currentViewId = getViewId();
+
+// Use sendInitialEvent() only when intentionally creating a new page view,
+// for example after a single-page app route change.
+sendInitialEvent();
 ```
 
-If you would like to add a new event type or event property which does not exist, please [contact the Ophan team](Ophan.Dev@guardian.co.uk).
+`getViewId()` and `getPageViewId()` return the current live page view ID. The default export also exposes `viewId` and `pageViewId` as getters for compatibility with object-style consumers.
+
+If you would like to add a new event type or event property which does not exist, please [contact the Ophan team](mailto:Ophan.Dev@guardian.co.uk).
 
 ### Sending events straight to the backend
 
@@ -91,9 +163,9 @@ The backend of tracker exposes two endpoints, `img/1` which takes in page view e
 
 The library is implemented using both Javascript and TypeScript, with the source code located in the `src` directory and its subdirectories. The project is set up to include both TypeScript (.ts) and JavaScript (.js) files, allowing for a mix of both languages in the library's implementation.
 
-Typescript interfaces and types are developed in the `types` folder.
+Typescript interfaces and types are developed in the `src/types` folder.
 
-The TypeScript compiler is configured to generate compiled JavaScript files and corresponding declaration files (.d.ts) in the ./dist directory. The declaration files provide type information for the library's public API. The compiler also generates source map files for the declaration files.
+The TypeScript compiler is configured to generate compiled JavaScript files and corresponding declaration files (`.d.ts`) in the `NPM-dist` directory. The declaration files provide type information for the library's public API, and declaration maps point editors back to the source files.
 
 ## Compile
 
@@ -101,20 +173,26 @@ The TypeScript compiler is configured to generate compiled JavaScript files and
     .../ophan/tracker-js $ npm run build-for-npm
 ```
 
+## Type checks
+
+```
+    .../ophan/tracker-js $ npm run test:types
+```
+
 #### Proxy tracker-js:
 
 1. Install dependencies
 
-    ```
-    $ brew install lighttpd
-    .../ophan/tracker-js $ npm install
-    ```
+   ```
+   $ brew install lighttpd
+   .../ophan/tracker-js $ npm install
+   ```
 
 2. In another terminal window:
 
-    ```
-    .../ophan/tracker-js $ lighttpd -f lighttpd.conf -D
-    ```
+   ```
+   .../ophan/tracker-js $ lighttpd -f lighttpd.conf -D
+   ```
 
 3. Install FoxyProxy (https://getfoxyproxy.org/downloads/) in your browser and create a rule that forces j.ophan.co.uk
    to localhost 8000. (For me FoxyProxy needed a few switches on and off before it decided to start talking to lighttpd.)
@@ -131,7 +209,7 @@ The TypeScript compiler is configured to generate compiled JavaScript files and
 
 ### Two formats for release
 
-When you make a change to Tracker JS, you must release on *both* these systems:
+When you make a change to Tracker JS, you must release on _both_ these systems:
 
 #### NPM
 
@@ -139,9 +217,9 @@ We use `changesets` for automated publishing of the NPM package:
 
 1. Add a changeset, run the following command and follow the instructions
 
-    ```
-    .../ophan/tracker-js $ npx changeset
-    ```
+   ```
+   .../ophan/tracker-js $ npx changeset
+   ```
 
 2. When you raise a PR, the changeset bot won’t correctly see that you have included a changeset – it only checks for the .changesets folder in the root of the repository, whereas we have it in a subdirectory. Don’t worry.
 
@@ -149,15 +227,16 @@ We use `changesets` for automated publishing of the NPM package:
 
 #### S3 Bucket
 
-* [https://j.ophan.co.uk/](https://j.ophan.co.uk/jobs.js) - CDN/S3, [deployed through RiffRaff](https://riffraff.gutools.co.uk/deployment/history?projectName=ophan%3A%3Aophan-tracker-js&page=1) and used by some Guardian sites like https://jobs.theguardian.com/. An advantage of this approach is that sites using it immediately get Tracker JS updates, without developer intervention.
+- [https://j.ophan.co.uk/](https://j.ophan.co.uk/jobs.js) - CDN/S3, [deployed through RiffRaff](https://riffraff.gutools.co.uk/deployment/history?projectName=ophan%3A%3Aophan-tracker-js&page=1) and used by some Guardian sites like https://jobs.theguardian.com/. An advantage of this approach is that sites using it immediately get Tracker JS updates, without developer intervention.
 
 #### Rollup
 
 The generated files from Rollup (using the `build-for-cdn` script in `package.json`) are only used for publishing to the CDN to use SystemJS / AMD
 
 ## Post publish
+
 Post publish it would be good practice to inform the teams using Tracker-JS about the update.
 
 See the [google doc ](https://docs.google.com/document/d/1MndFG-DLDQAMHIi55T4kZkGq4ONcded1-MDd9QS_NZE/edit?tab=t.0) for a list of teams depending on tracker-js.
 
-If the change to tracker-js is small, we could raise a quick PR in the relevant repo and ask the team to review it.
+If the change to tracker-js is small, we could raise a quick PR in the relevant repo and ask the team to review it.

package/src/help-centre.ts

@@ -0,0 +1,23 @@
+/**
+ * Self-initialising IIFE entry for `<script src>` consumers with no module
+ * loader or bundler (e.g. the Salesforce-hosted Help Centre). On load it exposes
+ * the tracker at `window.guardian.ophan` and sends the first page view.
+ */
+import ophan, { init, type Platform } from './index.js';
+
+const HELP_CENTRE_PLATFORM: Platform = 'help-centre';
+
+if (typeof window !== 'undefined') {
+	const windowWithGuardian = window as typeof window & {
+		guardian?: {
+			ophan?: typeof ophan;
+		};
+	};
+
+	// Don't clobber an existing tracker (e.g. script included twice).
+	if (!windowWithGuardian.guardian?.ophan) {
+		windowWithGuardian.guardian = windowWithGuardian.guardian ?? {};
+		windowWithGuardian.guardian.ophan = ophan;
+		init(HELP_CENTRE_PLATFORM);
+	}
+}

package/src/index.ts

@@ -0,0 +1,365 @@
+import core from './core.js';
+import transmit from './transmit.js';
+import attention from './attention.js';
+import visibility from './visibility.js';
+import privatebrowsing from './privatebrowsing.js';
+import heatmap from './heatmap.js';
+
+import './click-path-capture.js';
+import './perf.js';
+import './iframe-tracking.js';
+import './campaign.js';
+
+import { EventPayload } from './types/event.js';
+import clickPathCapture from './click-path-capture.js';
+
+/**
+ * Product surface that is initialising the tracker.
+ *
+ * The platform controls the historical Ophan serving-platform value and any
+ * platform-specific browser integrations started by `init()`.
+ */
+export type Platform = 'ng' | 'manage-my-account' | 'support' | 'help-centre';
+
+const isBrowser = (): boolean =>
+	typeof window !== 'undefined' && typeof document !== 'undefined';
+
+let initialized = false;
+let currentPlatform: Platform | null = null;
+
+const warnIfUninitialized = (methodName: string): void => {
+	console.warn(
+		`Ophan tracker ${methodName}() called before init(); ignoring event.`,
+	);
+};
+
+const canUseTracker = (methodName: string): boolean => {
+	if (!isBrowser()) {
+		return false;
+	}
+
+	if (!initialized) {
+		warnIfUninitialized(methodName);
+		return false;
+	}
+
+	return true;
+};
+
+/**
+ * Initialise the Ophan tracker for a specific platform.
+ *
+ * Call this once, eagerly, in a browser context before using the other tracker
+ * methods. Initialisation sends the first page-view event.
+ *
+ * @param platform - The platform identifier ('ng' for next-gen Guardian sites, 'manage-my-account', or 'support'). Defaults to 'ng'.
+ *
+ * @example
+ * ```javascript
+ * import { init } from '@guardian/ophan-tracker-js';
+ * init('ng');
+ * ```
+ */
+export const init = (platform: Platform = 'ng'): void => {
+	if (!isBrowser()) {
+		return;
+	}
+
+	const resolvedPlatform: Platform =
+		platform === 'manage-my-account' || platform === 'support' || platform === 'help-centre' ? platform : 'ng';
+
+	if (initialized) {
+		console.warn(
+			`Ophan tracker already initialized with platform: ${currentPlatform}`,
+		);
+		return;
+	}
+
+	currentPlatform = resolvedPlatform;
+	initialized = true;
+
+	if (resolvedPlatform === 'ng') {
+		core.init('next-gen');
+		privatebrowsing.init();
+		heatmap.init();
+
+		if ((window as any).addEventListener) {
+			attention.init(visibility);
+		}
+	} else if (resolvedPlatform === 'manage-my-account') {
+		core.init('manage-my-account');
+		if ((window as any).addEventListener) {
+			attention.init(visibility);
+		}
+	} else if (resolvedPlatform === 'support') {
+		core.init('support');
+		if ((window as any).addEventListener) {
+			attention.init(visibility);
+		}
+	} else if (resolvedPlatform === 'help-centre') {
+		core.init('help-centre');
+		if ((window as any).addEventListener) {
+			attention.init(visibility);
+		}
+	}
+};
+
+/**
+ * Send a new page-view event to Ophan.
+ *
+ * This generates a new view ID and tracks the current page.
+ * `init()` already sends the first page-view event, so call this only when
+ * intentionally creating another page view, such as after a single-page app
+ * route change.
+ *
+ * @param url - The page URL to track (defaults to current location)
+ * @param referrer - The referrer URL (defaults to document.referrer)
+ *
+ * @example
+ * ```javascript
+ * import { sendInitialEvent } from '@guardian/ophan-tracker-js';
+ * sendInitialEvent('https://www.theguardian.com/article', 'https://google.com');
+ * ```
+ */
+export const sendInitialEvent = (
+	url: string = typeof window !== 'undefined' ? location.href : '',
+	referrer: string = typeof window !== 'undefined' &&
+	typeof document !== 'undefined'
+		? document.referrer
+		: '',
+): void => {
+	if (!canUseTracker('sendInitialEvent')) {
+		return;
+	}
+
+	try {
+		transmit.bumpViewId();
+		core.sendInitialEvent(null, url, referrer);
+	} catch (error) {
+		console.log(error);
+	}
+};
+
+/**
+ * Record an event against the current page view.
+ *
+ * Use this for component interactions, purchases, subscriptions, media events,
+ * consent events, and other non-page-view payloads. `init()` must have run
+ * first so the event is associated with a valid page view and platform.
+ *
+ * @param event - The event data payload containing metrics and metadata
+ * @param callback - Optional callback function executed after the event is sent
+ *
+ * @example
+ * ```javascript
+ * import { record } from '@guardian/ophan-tracker-js';
+ *
+ * // Track a component interaction
+ * record({
+ *   componentEvent: {
+ *     component: {
+ *       componentType: 'ACQUISITIONS_ENGAGEMENT_BANNER',
+ *       id: 'end-of-article-banner',
+ *       campaignCode: '2024-annual-campaign',
+ *       labels: ['end-of-article']
+ *     },
+ *     action: 'CLICK',
+ *     abTest: {
+ *       name: 'BannerTest',
+ *       variant: 'control'
+ *     }
+ *   }
+ * });
+ *
+ * // Track a rendered component list
+ * record({
+ *   renderedComponents: ['nav', 'footer']
+ * });
+ * ```
+ */
+export const record = (event: EventPayload, callback?: () => void): void => {
+	if (!isBrowser()) {
+		callback?.();
+		return;
+	}
+
+	if (!initialized) {
+		warnIfUninitialized('record');
+		callback?.();
+		return;
+	}
+
+	transmit.sendMore(event, callback);
+};
+
+/**
+ * Track component attention and visibility analytics.
+ *
+ * Monitors when components enter and leave the viewport.
+ *
+ * @param name - Unique identifier for the component
+ * @param el - The DOM element to track
+ * @param visibilityThreshold - Percentage of element that must be visible (0-1)
+ * @param isTrackingVideo - Whether this component contains video content
+ *
+ * @example
+ * ```javascript
+ * import { trackComponentAttention } from '@guardian/ophan-tracker-js';
+ *
+ * const banner = document.getElementById('promo-banner');
+ * trackComponentAttention('promo-banner', banner, 0.5);
+ * ```
+ */
+export const trackComponentAttention = (
+	name: string,
+	el: HTMLElement,
+	visibilityThreshold: number,
+	isTrackingVideo?: boolean,
+): void => {
+	if (!canUseTracker('trackComponentAttention')) {
+		return;
+	}
+
+	attention.initComponent(name, el, visibilityThreshold, isTrackingVideo);
+};
+
+/**
+ * Set a custom event emitter for attention tracking.
+ *
+ * This is primarily for integrations that need to bridge the tracker's
+ * attention events into an existing event system.
+ *
+ * @param event - Event emitter object with emit/on methods
+ *
+ * @example
+ * ```javascript
+ * import { setEventEmitter } from '@guardian/ophan-tracker-js';
+ *
+ * const customEmitter = new EventEmitter();
+ * setEventEmitter(customEmitter);
+ * ```
+ */
+export const setEventEmitter = (event: Object): void => {
+	attention.setEventEmitter(event);
+};
+
+/**
+ * Manually track a click event on an element with data-link-name or data-component attributes.
+ * This captures click path information and component context for analytics.
+ * Useful for elements that stop event propagation or need explicit tracking.
+ *
+ * @param element - The clicked DOM element (should have data-link-name or data-component attributes)
+ *
+ * @example
+ * ```javascript
+ * import { trackClickComponentEvent } from '@guardian/ophan-tracker-js';
+ *
+ * // Track a click on an element with tracking attributes
+ * const link = document.querySelector('a[data-link-name="subscribe-button"]');
+ * trackClickComponentEvent(link);
+ *
+ * // Or track a button inside a component
+ * const button = document.querySelector('[data-component="newsletter-signup"] button');
+ * trackClickComponentEvent(button);
+ * ```
+ */
+export const trackClickComponentEvent = (element: Element): void => {
+	if (!canUseTracker('trackClickComponentEvent')) {
+		return;
+	}
+
+	clickPathCapture.trackClickComponentEvent(element);
+};
+
+/**
+ * Generate a new page view ID for the current browser session.
+ *
+ * Useful for single-page applications when navigating between pages.
+ *
+ * @example
+ * ```javascript
+ * import { bumpViewId } from '@guardian/ophan-tracker-js';
+ *
+ * // Call when navigating to a new page in SPA
+ * bumpViewId();
+ * ```
+ */
+export const bumpViewId = (): void => {
+	if (!canUseTracker('bumpViewId')) {
+		return;
+	}
+
+	transmit.bumpViewId();
+};
+
+/**
+ * Return the current live Ophan page view ID.
+ *
+ * Prefer this function over destructuring `viewId` from the default export,
+ * because the value changes after `bumpViewId()` or `sendInitialEvent()`.
+ */
+export const getViewId = (): string => transmit.viewId;
+
+/**
+ * Alias for `getViewId()` kept for consumers that use page-view terminology.
+ */
+export const getPageViewId = (): string => transmit.viewId;
+
+/**
+ * Object-shaped tracker API exposed by the package default export.
+ *
+ * Named exports are preferred for new code, but the default export keeps the
+ * historical object-style API and exposes `viewId`/`pageViewId` as live getters.
+ */
+export interface OphanTracker {
+	init: (platform?: Platform) => void;
+	sendInitialEvent: (url?: string, referrer?: string) => void;
+	record: (event: EventPayload, callback?: () => void) => void;
+	trackComponentAttention: (
+		name: string,
+		el: HTMLElement,
+		visibilityThreshold: number,
+		isTrackingVideo?: boolean,
+	) => void;
+	setEventEmitter: (event: Object) => void;
+	trackClickComponentEvent: (element: Element) => void;
+	bumpViewId: () => void;
+	getViewId: () => string;
+	getPageViewId: () => string;
+	viewId: string;
+	pageViewId: string;
+}
+
+const ophanTracker: OphanTracker = {
+	init,
+	sendInitialEvent,
+	record,
+	trackComponentAttention,
+	setEventEmitter,
+	trackClickComponentEvent,
+	bumpViewId,
+	getViewId,
+	getPageViewId,
+	get viewId() {
+		return getViewId();
+	},
+	get pageViewId() {
+		return getPageViewId();
+	},
+};
+
+export default ophanTracker;
+
+// Type exports
+export * from './types/abtest.js';
+export * from './types/subscription.js';
+export * from './types/interaction.js';
+export * from './types/inpageclick.js';
+export * from './types/printproduct.js';
+export * from './types/product.js';
+export * from './types/platform.js';
+export * from './types/media.js';
+export * from './types/consent.js';
+export * from './types/component-type.js';
+export * from './types/component-event.js';
+export * from './types/event.js';