@guardian/ophan-tracker-js 2.1.1 → 2.1.2-next.0

package/package.json

@@ -1,30 +1,40 @@
 {
 	"name": "@guardian/ophan-tracker-js",
-	"version": "2.1.1",
+	"version": "2.1.2-next.0",
 	"type": "module",
 	"engines": {
 		"node": ">=16"
 	},
 	"files": [
-		"assets/*.js",
-		"assets/vendor/*.js"
+		"NPM-dist/**/*.js",
+		"NPM-dist/**/*.d.ts"
 	],
-	"main": "assets/ng.js",
+	"main": "NPM-dist/ng.js",
+	"types": "NPM-dist/types/ng.d.ts",
 	"devDependencies": {
-		"@babel/preset-env": "7.22.10",
+		"@babel/preset-env": "^7.22.10",
+		"@babel/preset-typescript": "^7.24.7",
 		"@changesets/cli": "^2.26.2",
 		"@guardian/prettier": "^7.0.0",
 		"@rollup/plugin-babel": "6.0.3",
 		"@rollup/plugin-terser": "0.4.3",
+		"@rollup/plugin-typescript": "^11.1.6",
+		"@types/jest": "^29.5.12",
+		"babel-jest": "^29.7.0",
 		"jest": "^29.7.0",
 		"jest-environment-jsdom": "^29.7.0",
 		"rollup": "3.28.0",
-		"rollup-jest": "^3.1.0"
+		"rollup-jest": "^3.1.0",
+		"ts-jest": "^29.1.4",
+		"typescript": "^5.4.4"
 	},
 	"scripts": {
-		"build": "NODE_ENV=production npx rollup -c",
-		"build:test": "NODE_ENV=test npx rollup -c",
+		"build-for-cdn": "NODE_ENV=production npx rollup -c",
+		"build-for-npm": "tsc",
 		"test": "jest",
 		"format": "npx prettier --write ."
+	},
+	"dependencies": {
+		"@guardian/tsconfig": "^1.0.0"
 	}
 }

package/readme.md

@@ -1,14 +1,105 @@
-# Ophan Tracker JS
+# Using Ophan Tracker JS
 
 Browser JavaScript client for Ophan.
 
 ## Install
 
+```bash
+$ npm install @guardian/ophan-tracker-js
 ```
-$ npm install ophan-tracker-js
+
+## Usage
+
+Tracker JS contains multiple entry point files tailored to specific platforms. These include:
+
+- `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
+
+**Default Behaviour**
+
+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](./types/event.ts#L15) on page load. You are then in control of sending other events to Ophan.
+
+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:**
+
+   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.
+
+   ```javascript
+   import ophan from '@guardian/ophan-tracker-js';
+   ```
+
+2. **Send Tracking Events with `ophan.record()`:**
+
+   ```javascript
+   ophan.record({
+       // Your tracking data in JSON format
+   });
+   ```
+
+### Usage with Typescript
+
+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]("./types/event.ts#L95"). 
+
+#### 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";
+const exampleAbTest: AbTest = {
+   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"]),
+};
+
+const componentEvent: ComponentEvent = {
+   component: componentV2,
+   action: "CLICK",
+   value: "some-value",
+   id: "event-id",
+   abTest: exampleAbTest,
+   targetingAbTest: exampleAbTest,
+};
+
+ophan.record({
+   componentEvent: componentEvent
+});
 ```
 
-## Contribute
+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).
+
+### Sending events straight to the backend
+
+_Please [consult with the Ophan team](Ophan.Dev@guardian.co.uk) if you wish to do this._
+
+The backend of tracker exposes two endpoints, `img/1` which takes in page view events, and `img/2` which takes in all other events. For events sent to the `img/2` endpoint, a page view event MUST also be created via the `img/1`. Further down the Ophan and Datatech pipeline, events with the same page view ID are tied together for ease of querying and data analysis. Therefore, a page view event must be present.
+
+# Developing Ophan Tracker JS
+
+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.
+
+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.
+
+## Compile
+
+```
+    .../ophan/tracker-js $ npm run build-for-npm
+```
 
 #### Proxy tracker-js:
 
@@ -25,8 +116,8 @@ $ npm install ophan-tracker-js
     .../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.)
+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.)
 
 4. In another terminal window, start a server that is [running the Guardian frontend](https://github.com/guardian/frontend/blob/main/docs/01-start-here/01-installation-steps.md)
 
@@ -53,7 +144,7 @@ We use `changesets` for automated publishing of the NPM package:
     ```
 
 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.
-   
+
 3. When the PR is merged, the [`changesets` github action](https://github.com/changesets/action) will create a new PR, [example here](https://github.com/guardian/ophan/pull/5626). On merging this generated PR, the action will publish to NPM. (This checks the subdirectory correctly.)
 
 ##### S3 Bucket
@@ -62,8 +153,4 @@ We use `changesets` for automated publishing of the NPM package:
 
 ##### Rollup
 
-The generated files from Rollup are only used for publishing to the CDN to use SystemJS / AMD
-
-##### Example Usage
-
-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)
+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

package/assets/adblock-detection.js

@@ -1,19 +0,0 @@
-import abd from './vendor/adBlockDetectionLib.js';
-
-export default {
-	run() {
-		return new Promise((resolve, reject) => {
-			if (abd.init) {
-				try {
-					abd.init({
-						complete: resolve,
-					});
-				} catch (error) {
-					reject(error);
-				}
-			} else {
-				reject(new Error('Failed to initialise adblock detection'));
-			}
-		});
-	},
-};

package/assets/attention.js

@@ -1,160 +0,0 @@
-// Generated by CoffeeScript 2.7.0
-import transmit from './transmit.js';
-
-import components from './components.js';
-
-// The upworthy definition of attention minutes, from
-// http://upworthy.github.io/2014/06/implementing-attention-minutes-part-1/ :
-
-// "We consider the page to have the user’s attention if
-//  1. some activity is happening on the page. For our purposes this means:
-//     1. the page currently has focus
-//     2. and the user has interacted with the page within a certain timeout
-//  2. or a video is playing on the page
-//  Attention Minutes, then, are the total number of minutes that a user has spent on
-//  a page where the above conditions have held true."
-
-// our definition of "within a certain timeout" above:
-const ATTENTIONDECAY = 5000;
-
-// our definition of "the user has interacted with the page"
-const EVENTS = [
-	'focus',
-	'click',
-	'scroll',
-	'mousemove',
-	'touchstart',
-	'touchend',
-	'touchcancel',
-	'touchleave',
-	'touchmove',
-	'keyup',
-	'keydown',
-];
-
-const REPORTINGINTERVAL = 10000;
-
-// total attention time so far on this page
-let totalAttentionMs = 0;
-
-// the time elapsed since the time origin (https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#the_time_origin)
-// when the most recent period of attention (that is, attention
-// which we haven't yet added to totalAttentionMs) began.
-// null if we don't have attention.
-let unrecordedAttentionStarted = null;
-
-// the attention time we last reported to ophan
-let reportedTotalAttentionMs = null; // setting null here forces a first report of attention time, even if it's only 0ms
-
-// the decay timer if we've set one
-let decayTimerId = null;
-
-// is video currently playing?
-let videoPlaying = false;
-
-const cancelDecayTimer = () => {
-	if (decayTimerId != null) {
-		window.clearTimeout(decayTimerId);
-	}
-	decayTimerId = null;
-};
-
-const makeActive = () => {
-	if (unrecordedAttentionStarted == null) {
-		unrecordedAttentionStarted = performance.now();
-	}
-	components.startMonitoring();
-	cancelDecayTimer();
-	decayTimerId = window.setTimeout(() => {
-		if (!videoPlaying) {
-			makeInactive();
-		}
-	}, ATTENTIONDECAY);
-};
-
-const incrementTotalAttentionTimeByUnrecordedAmount = () => {
-	if (unrecordedAttentionStarted != null) {
-		const now = performance.now();
-		const unrecordedMs = Math.min(
-			now - unrecordedAttentionStarted,
-			REPORTINGINTERVAL,
-		);
-		totalAttentionMs += unrecordedMs;
-		unrecordedAttentionStarted = now;
-	}
-};
-
-const makeInactive = () => {
-	cancelDecayTimer();
-	components.stopMonitoring();
-	incrementTotalAttentionTimeByUnrecordedAmount();
-	unrecordedAttentionStarted = null;
-};
-
-const reporter = () => {
-	incrementTotalAttentionTimeByUnrecordedAmount();
-	if (totalAttentionMs !== reportedTotalAttentionMs) {
-		const report = {
-			attentionMs: Math.round(totalAttentionMs),
-		};
-		const componentAttentionTimes = components.getAttentionTimes();
-		if (Object.keys(componentAttentionTimes).length) {
-			report.componentAttentionMs = componentAttentionTimes;
-		}
-		transmit.sendMore(report);
-		reportedTotalAttentionMs = totalAttentionMs;
-	}
-};
-
-const initComponent = (name, el, visibilityThreshold = 0.5) => {
-	components.registerComponent(
-		name,
-		el,
-		visibilityThreshold,
-		REPORTINGINTERVAL,
-	);
-};
-
-const initAttention = (visibility) => {
-	EVENTS.forEach((event) => {
-		window.addEventListener(event, makeActive);
-	});
-
-	document.addEventListener(
-		visibility.changeEvent,
-		() => {
-			if (visibility.state() === 'visible') {
-				makeActive();
-			} else {
-				makeInactive();
-			}
-		},
-		false,
-	);
-
-	document.addEventListener('videoPlaying', () => {
-		videoPlaying = true;
-		makeActive();
-	});
-	document.addEventListener('videoEnded', () => {
-		videoPlaying = false;
-		makeInactive();
-	});
-	document.addEventListener('videoPause', () => {
-		videoPlaying = false;
-		makeInactive();
-	});
-
-	window.setTimeout(reporter, 100);
-	window.setInterval(reporter, REPORTINGINTERVAL);
-};
-
-const setEventEmitter = (emitter) => {
-	components.setEventEmitter(emitter);
-};
-
-export default {
-	init: initAttention,
-	initComponent: initComponent,
-	setEventEmitter: setEventEmitter,
-};

package/assets/campaign.js

@@ -1,25 +0,0 @@
-// Generated by CoffeeScript 2.7.0
-import transmit from './transmit.js';
-import perf from './perf.js';
-
-const start = perf?.timing?.domComplete ?? performance.now();
-
-// DFP ads
-if (typeof googletag !== 'undefined' && googletag !== null) {
-	googletag.cmd.push(() => {
-		googletag.pubads().addEventListener('slotRenderEnded', (event) => {
-			const slotId = event.slot.getSlotId().getDomId();
-			transmit.sendMore({
-				ads: [
-					{
-						slot: slotId,
-						campaignId: event.isEmpty ? '__empty__' : event.lineItemId,
-						creativeId: event.creativeId,
-						timeToRenderEnded: Math.round(performance.now() - start),
-						adServer: 'DFP',
-					},
-				],
-			});
-		});
-	});
-}

package/assets/click-path-capture.js

@@ -1,80 +0,0 @@
-import ophan from './core.js';
-
-import transmit from './transmit.js';
-
-/**
- * Finds the closest ancestor anchor (`<a>`) element of the given element.
- *
- * @param {Element} el - The element to start searching from.
- * @returns {Element|null} The closest ancestor anchor element or null if none found.
- */
-export const validAncestorAnchorElement = (el) => {
-	if (!el || el.nodeName?.toLowerCase() === 'body') return null;
-	return el.nodeName.toLowerCase() === 'a'
-		? el
-		: validAncestorAnchorElement(el.parentNode);
-};
-
-/**
- * Retrieves the value of the `data-component` attribute from the closest ancestor.
- *
- * @param {Element} el - The element to start searching from.
- * @returns {string|null} The `data-component` attribute value or null if not found.
- */
-export const getContainingComponent = (el) => {
-	if (!el || el.nodeName?.toLowerCase() === 'body') return null;
-	return (
-		el.getAttribute('data-component') || getContainingComponent(el.parentNode)
-	);
-};
-
-/**
- * Collects all `data-link-name` attribute values from the ancestor elements.
- *
- * @param {Element} el - The element to start searching from.
- * @param {string[]} dataLinkNames - Initial array of data link names (optional).
- * @returns {string[]} Array of `data-link-name` values.
- */
-const getDataLinkNames = (el, dataLinkNames = []) => {
-	if (!el || el === document.body || el === document) return dataLinkNames;
-
-	const dataLinkName = el.getAttribute('data-link-name');
-	if (dataLinkName) dataLinkNames.push(dataLinkName);
-
-	return getDataLinkNames(el.parentNode, dataLinkNames);
-};
-
-if (typeof document.addEventListener === 'function') {
-	document.addEventListener(
-		'click',
-		function (e) {
-			let anchorTarget, info;
-			anchorTarget = validAncestorAnchorElement(e.target);
-			info = {
-				from: [location.protocol, '//', location.host, location.pathname].join(
-					'',
-				),
-				to: anchorTarget ? anchorTarget.href : void 0,
-				referringComponent: getContainingComponent(e.target),
-				referringDataLinkNames: getDataLinkNames(e.target),
-				refPlatform: ophan.servingPlatform(),
-				refViewId: ophan.viewId,
-			};
-			if (info.referringDataLinkNames != null) {
-				transmit.sendMore({
-					clickComponent: info.referringComponent,
-					clickLinkNames: info.referringDataLinkNames,
-				});
-			}
-			if (anchorTarget != null) {
-				// then we may be about to navigate away from this page, so store to send on next request
-				return ophan.storeDataToSendOnNextEvent(info);
-			}
-		},
-		false,
-	);
-}
-
-export default {
-	getDataLinkNames: getDataLinkNames,
-};

package/assets/components.js

@@ -1,199 +0,0 @@
-/**
- * @type {Component[]}
- */
-export const components = [];
-
-/**
- * theguardian.com uses a custom scroll event for performance reasons.
- * We pass in the event emitter so that we can listen to this custom scroll event.
- * If not on theguardian.com, we default to the native scroll event
- * @type {Object|null}
- */
-let eventEmitter = null;
-
-// Tracks attention time of elements on the page with data-component attributes.
-// This should always be less than or equal to the page attention time.
-// If the page does not have attention, no component has attention.
-// If the page does have attention, a given component *may* also have
-// attention, if it is within the viewport and not hidden.
-class Component {
-	/**
-	 * Component constructor.
-	 * @param {string} name - The name of the component.
-	 * @param {HTMLElement} element - The DOM element of the component.
-	 * @param {number} visibilityThreshold1 -
-	 *    visibilityThreshold represents the fraction of each component that must
-	 *    be in the viewport before it is considered visible.
-	 *    e.g. 0.5 means that half the height or width must be in the viewport
-	 *    1 means that the entire element must be in the viewport
-	 * @param {number} reportingInterval1 - ??
-	 */
-	constructor(name, element, visibilityThreshold1, reportingInterval1) {
-		this.name = name;
-		this.element = element;
-		this.visibilityThreshold = visibilityThreshold1;
-		this.reportingInterval = reportingInterval1;
-		this.visible = false;
-		// total attention time so far for this element
-		this.totalAttentionMs = 0;
-		// the time elapsed since the time origin (https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#the_time_origin)
-		// when the most recent period of attention (that is, attention
-		// which we haven't yet added to totalAttentionMs) began.
-		// null if we don't have attention.
-		this.unrecordedAttentionStarted = null;
-		// the attention time when getAttentionTime() was last called
-		this.reportedTotalAttentionMs = 0;
-		this.usingEmitter = false;
-		this.visCheck = this.checkVisibility.bind(this);
-		if (eventEmitter != null) {
-			this.usingEmitter = true;
-			eventEmitter.on('window:throttledScroll', this.visCheck);
-		} else {
-			window.addEventListener('scroll', this.visCheck);
-		}
-		window.addEventListener('resize', this.visCheck);
-	}
-
-	isVisible(threshold = 1) {
-		if (!this.element.offsetParent) {
-			// exclude hidden elements
-			// will also exclude position: fixed elements but we don't care about these
-			// (because their attention time would always be the same as the whole page)
-			// https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent
-			return false;
-		}
-
-		const box = this.element.getBoundingClientRect();
-		const width = box.width;
-		const height = box.height;
-		const windowHeight =
-			window.innerHeight || document.documentElement.clientHeight;
-		const windowWidth =
-			window.innerWidth || document.documentElement.clientWidth;
-
-		return (
-			box.left >= -(width * (1 - threshold)) &&
-			box.top >= -(height * (1 - threshold)) &&
-			box.right <= windowWidth + width * (1 - threshold) &&
-			box.bottom <= windowHeight + height * (1 - threshold)
-		);
-	}
-
-	visibilityHasChanged() {
-		const wasVisible = this.visible;
-		this.visible = this.isVisible(this.visibilityThreshold);
-		return wasVisible !== this.visible;
-	}
-
-	rebindToEventEmitter() {
-		if (!this.usingEmitter && eventEmitter != null) {
-			window.removeEventListener('scroll', this.visCheck);
-			this.usingEmitter = true;
-			return eventEmitter.on('window:throttledScroll', this.visCheck);
-		}
-	}
-
-	checkVisibility() {
-		this.rebindToEventEmitter();
-		if (this.visibilityHasChanged()) {
-			return this.visible ? this.makeActive() : this.makeInactive();
-		}
-	}
-
-	makeActive() {
-		// mark when the latest period of attention began,
-		// if we're not already in an attention period
-		return this.unrecordedAttentionStarted != null
-			? this.unrecordedAttentionStarted
-			: (this.unrecordedAttentionStarted = performance.now());
-	}
-
-	makeInactive() {
-		this.incrementTotalAttentionTimeByUnrecordedAmount();
-		return (this.unrecordedAttentionStarted = null);
-	}
-
-	hadAttentionSinceLastGet() {
-		this.incrementTotalAttentionTimeByUnrecordedAmount();
-		return this.totalAttentionMs !== this.reportedTotalAttentionMs;
-	}
-
-	getAttentionTime() {
-		this.incrementTotalAttentionTimeByUnrecordedAmount();
-		this.reportedTotalAttentionMs = this.totalAttentionMs;
-		return this.totalAttentionMs;
-	}
-
-	incrementTotalAttentionTimeByUnrecordedAmount() {
-		if (this.unrecordedAttentionStarted != null) {
-			const now = performance.now();
-			// the Math.min here is to deal with occasions where we don't get an event indicating that the user
-			// has become inactive - this can happen e.g. due to users suspending their phone. Never send
-			// crazy big values!
-			const unrecordedMs = Math.min(
-				now - this.unrecordedAttentionStarted,
-				this.reportingInterval,
-			);
-			this.totalAttentionMs += unrecordedMs;
-			return (this.unrecordedAttentionStarted = now);
-		}
-	}
-}
-
-/**
- * Begins monitoring the components on the page for attention time.
- * @returns {Array} Array of results from makeActive() for each visible component.
- */
-const startMonitoring = () => {
-	return components
-		.filter((component) => component.isVisible())
-		.map((component) => component.makeActive());
-};
-
-/**
- * Stops monitoring the components on the page for attention time.
- * @returns {Array} Array of results from makeInactive() for each component.
- */
-const stopMonitoring = () => {
-	return components.map((component) => component.makeInactive());
-};
-
-/**
- * Retrieves the attention times for all components.
- * @returns {Object}
- */
-const getAttentionTimes = () => {
-	const obj = {};
-	for (const component of components) {
-		if (component.hadAttentionSinceLastGet()) {
-			// if there are duplicate component names, only the last one survives
-			obj[component.name] = Math.round(component.getAttentionTime());
-		}
-	}
-	return obj;
-};
-
-export default {
-	/**
-	 * @param {Object} emitter - The event emitter to set.
-	 * @returns {Object}
-	 */
-	setEventEmitter: function (emitter) {
-		return (eventEmitter = emitter);
-	},
-	startMonitoring,
-	stopMonitoring,
-	getAttentionTimes,
-
-	/** @type {(...args: ConstructorParameters<typeof Component>) => void} */
-	registerComponent: function (
-		name,
-		el,
-		visibilityThreshold,
-		reportingInterval,
-	) {
-		return components.push(
-			new Component(name, el, visibilityThreshold, reportingInterval),
-		);
-	},
-};

package/assets/contribution.js

@@ -1,25 +0,0 @@
-// Generated by CoffeeScript 2.7.0
-import core from './core.js';
-
-import transmit from './transmit.js';
-
-import attention from './attention.js';
-
-import visibility from './visibility.js';
-
-import './click-path-capture.js';
-
-import './perf.js';
-
-import './campaign.js';
-
-core.init('contribution');
-
-if (window.addEventListener != null) {
-	attention.init(visibility);
-}
-
-export default {
-	record: transmit.sendMore,
-	viewId: transmit.viewId,
-};