Add ophan tracking for Admiral events (#2141)

* install ophan-tracker-js as dev dependency

* add ophan record function and track INSERT, DETECT, VIEW, CLOSE actions for adblock recovery

* add test for ophan tracking

Author: cemms1

bundle/package.json

@@ -48,6 +48,7 @@
 		"web-vitals": "^4.2.4"
 	},
 	"devDependencies": {
+		"@guardian/ophan-tracker-js": "catalog:",
 		"@babel/cli": "^7.26.4",
 		"@babel/core": "^7.26.0",
 		"@babel/plugin-syntax-dynamic-import": "^7.8.3",

bundle/src/init/consented/admiral.test.ts

@@ -0,0 +1,74 @@
+import { isUserInVariant } from '../../experiments/ab';
+import { recordAdmiralOphanEvent } from './admiral';
+
+jest.mock('../../experiments/ab');
+
+// Mock Ophan
+window.guardian.ophan = {
+	trackComponentAttention: jest.fn(),
+	viewId: '',
+	pageViewId: '',
+	record: jest.fn(),
+};
+
+describe('Admiral functions', () => {
+	describe('recordAdmiralOphanEvent', () => {
+		it('calls ophan.record with expected params for action provided', () => {
+			jest.mocked(isUserInVariant).mockReturnValue(true);
+
+			recordAdmiralOphanEvent({ action: 'INSERT' });
+			const expectedComponentEvent = {
+				component: {
+					componentType: 'AD_BLOCK_RECOVERY',
+					id: 'admiral-adblock-recovery',
+				},
+				action: 'INSERT',
+				abTest: {
+					name: 'AdmiralAdblockRecovery',
+					variant: 'variant-detect',
+				},
+			};
+			expect(window.guardian.ophan?.record).toHaveBeenCalledWith({
+				componentEvent: expectedComponentEvent,
+			});
+		});
+
+		it('calls ophan.record with expected params for action and value provided', () => {
+			jest.mocked(isUserInVariant).mockReturnValue(true);
+
+			recordAdmiralOphanEvent({ action: 'DETECT', value: 'whitelisted' });
+			const expectedComponentEvent = {
+				component: {
+					componentType: 'AD_BLOCK_RECOVERY',
+					id: 'admiral-adblock-recovery',
+				},
+				action: 'DETECT',
+				value: 'whitelisted',
+				abTest: {
+					name: 'AdmiralAdblockRecovery',
+					variant: 'variant-detect',
+				},
+			};
+			expect(window.guardian.ophan?.record).toHaveBeenCalledWith({
+				componentEvent: expectedComponentEvent,
+			});
+		});
+
+		it('omits the abTest key value pair if not in a variant', () => {
+			jest.mocked(isUserInVariant).mockReturnValue(false);
+
+			recordAdmiralOphanEvent({ action: 'DETECT', value: 'whitelisted' });
+			const expectedComponentEvent = {
+				component: {
+					componentType: 'AD_BLOCK_RECOVERY',
+					id: 'admiral-adblock-recovery',
+				},
+				action: 'DETECT',
+				value: 'whitelisted',
+			};
+			expect(window.guardian.ophan?.record).toHaveBeenCalledWith({
+				componentEvent: expectedComponentEvent,
+			});
+		});
+	});
+});

bundle/src/init/consented/admiral.ts

@@ -1,3 +1,4 @@
+import type { ComponentEvent } from '@guardian/ophan-tracker-js';
 import { isUserInVariant } from '../../experiments/ab';
 import { admiralAdblockRecovery } from '../../experiments/tests/admiral-adblocker-recovery';
 
@@ -17,6 +18,41 @@ const getAdmiralAbTestVariant = (): string | undefined => {
 	return undefined;
 };
 
+/**
+ * Sends component events to Ophan with the componentType of `AD_BLOCK_RECOVERY`
+ * as well as sending the AB test participation
+ *
+ * @param overrides allows overriding / setting values for `action` and `value`
+ */
+const recordAdmiralOphanEvent = ({
+	action,
+	value,
+}: {
+	action: ComponentEvent['action'];
+	value?: ComponentEvent['value'];
+}): void => {
+	const abTestVariant = getAdmiralAbTestVariant();
+
+	const componentEvent: ComponentEvent = {
+		component: {
+			componentType: 'AD_BLOCK_RECOVERY',
+			id: 'admiral-adblock-recovery',
+		},
+		action,
+		...(value ? { value } : {}),
+		...(abTestVariant
+			? {
+					abTest: {
+						name: 'AdmiralAdblockRecovery',
+						variant: abTestVariant,
+					},
+				}
+			: {}),
+	};
+
+	window.guardian.ophan?.record({ componentEvent });
+};
+
 /**
  * Sets targeting on the Admiral object
  *
@@ -26,4 +62,8 @@ const getAdmiralAbTestVariant = (): string | undefined => {
 const setAdmiralTargeting = (key: string, value: string): void =>
 	window.admiral?.('targeting', 'set', key, value);
 
-export { getAdmiralAbTestVariant, setAdmiralTargeting };
+export {
+	getAdmiralAbTestVariant,
+	recordAdmiralOphanEvent,
+	setAdmiralTargeting,
+};

bundle/src/init/consented/prepare-admiral.ts

@@ -1,5 +1,6 @@
 import type { Admiral, AdmiralEvent } from '@guardian/commercial-core/types';
 import { log } from '@guardian/libs';
+import { recordAdmiralOphanEvent } from './admiral';
 
 type MeasureDetectedEvent = {
 	adblocking: boolean;
@@ -31,12 +32,14 @@ const handleMeasureDetectedEvent = (event: AdmiralEvent): void => {
 				'commercial',
 				'🛡️ Admiral - user has an adblocker and it is enabled',
 			);
+			recordAdmiralOphanEvent({ action: 'DETECT', value: 'blocked' });
 		}
 		if (event.whitelisted) {
 			log(
 				'commercial',
 				'🛡️ Admiral - user has seen Engage and subsequently disabled their adblocker',
 			);
+			recordAdmiralOphanEvent({ action: 'DETECT', value: 'whitelisted' });
 		}
 		if (event.subscribed) {
 			log(
@@ -64,6 +67,7 @@ const handleCandidateShownEvent = (event: AdmiralEvent): void => {
 			'commercial',
 			`🛡️ Admiral - Launching candidate ${event.candidateID}`,
 		);
+		recordAdmiralOphanEvent({ action: 'VIEW', value: event.candidateID });
 	} else {
 		log(
 			'commercial',
@@ -83,6 +87,7 @@ const handleCandidateDismissedEvent = (event: AdmiralEvent): void => {
 			'commercial',
 			`🛡️ Admiral - Candidate ${event.candidateID} was dismissed`,
 		);
+		recordAdmiralOphanEvent({ action: 'CLOSE', value: event.candidateID });
 	} else {
 		log(
 			'commercial',

bundle/src/lib/third-party-tags/admiral.ts

@@ -2,6 +2,7 @@ import { isInUsa } from '@guardian/commercial-core/geo/geo-utils';
 import { cmp, log } from '@guardian/libs';
 import {
 	getAdmiralAbTestVariant,
+	recordAdmiralOphanEvent,
 	setAdmiralTargeting,
 } from '../../init/consented/admiral';
 import type { GetThirdPartyTag } from '../types';
@@ -54,6 +55,7 @@ const admiralTag: ReturnType<GetThirdPartyTag> = {
 	url: `${BASE_AJAX_URL}/commercial/admiral-bootstrap.js`,
 	beforeLoad: () => {
 		log('commercial', '🛡️ Admiral - loading script on the page');
+		recordAdmiralOphanEvent({ action: 'INSERT' });
 
 		/** Send targeting to Admiral for AB test variants */
 		if (isInVariant && abTestVariant) {

core/package.json

@@ -50,13 +50,14 @@
 		"@types/googletag": "catalog:"
 	},
 	"devDependencies": {
-		"@types/node": "catalog:",
-		"typescript": "catalog:",
+		"@guardian/ophan-tracker-js": "catalog:",
 		"@types/jest": "catalog:",
+		"@types/node": "catalog:",
 		"jest": "catalog:",
 		"jest-environment-jsdom": "catalog:",
 		"jest-environment-jsdom-global": "catalog:",
 		"ts-jest": "catalog:",
+		"typescript": "catalog:",
 		"type-fest": "catalog:"
 	},
 	"publishConfig": {

core/src/types.ts

@@ -1,3 +1,4 @@
+import type { EventPayload } from '@guardian/ophan-tracker-js';
 import type { AdSize, SizeMapping } from './ad-sizes';
 import type { PageTargeting } from './targeting/build-page-targeting';
 import 'googletag';
@@ -57,7 +58,7 @@ interface NetworkInformation extends EventTarget {
 }
 
 type OphanRecordFunction = (
-	event: Record<string, unknown> & {
+	event: EventPayload & {
 		/**
 		 * the experiences key will override previously set values.
 		 * Use `recordExperiences` instead.

pnpm-lock.yaml

@@ -5,12 +5,13 @@ packages:
 catalog:
     '@guardian/ab-core': '8.0.1'
     '@guardian/libs': '25.2.0'
-    'typescript': '5.8.3'
+    '@guardian/ophan-tracker-js': '2.4.0'
     '@types/node': '24.2.0'
     '@types/jest': '30.0.0'
     '@types/googletag': '~3.3.0'
     'jest': '^30.0.5'
     'jest-environment-jsdom': '^30.0.5'
     'jest-environment-jsdom-global': '~4.0.0'
     'ts-jest': '^29.4.1'
+    'typescript': '5.8.3'
     'type-fest': '^4.41.0'