Add client for reading new ab test framework state

Jakeii · i-hardy · Jakeii · commit aa37e0950f9c · 2025-08-05T12:41:02.000+01:00
Co-authored-by: Imogen Hardy &lt;imogen.hardy@guardian.co.uk&gt;
diff --git a/dotcom-rendering/src/client/abTesting.ts b/dotcom-rendering/src/client/abTesting.ts
@@ -0,0 +1,53 @@
+import { getCookie, isUndefined } from '@guardian/libs';
+
+const AB_COOKIE_NAME = 'gu_client_ab_tests';
+
+type ABParticipations = {
+	[testId: string]: string;
+};
+
+/**
+ * get client-side AB test state from the cookie
+ */
+const getClientParticipations = (): ABParticipations => {
+	const userTestBuckets = getCookie({
+		name: AB_COOKIE_NAME,
+		shouldMemoize: true,
+	});
+
+	if (userTestBuckets) {
+		return userTestBuckets
+			.split(',')
+			.reduce<ABParticipations>((participations, abTestStatus) => {
+				const [testId, groupId] = abTestStatus.split(':');
+				if (testId && groupId) {
+					participations[testId] = groupId;
+				}
+				return participations;
+			}, {});
+	}
+
+	return {};
+};
+const initABTesting = (): void => {
+	const { serverSideABTests } = window.guardian.config;
+
+	const clientSideABTests = getClientParticipations();
+
+	const participations = {
+		...clientSideABTests,
+		...serverSideABTests,
+	};
+
+	window.guardian.modules.abTests = {
+		getParticipations: () => participations,
+		isUserInTest: (testId: string) => {
+			return !isUndefined(participations[testId]);
+		},
+		isUserInTestGroup: (testId: string, groupId: string) => {
+			return participations[testId] === groupId;
+		},
+	};
+};
+
+export { initABTesting };
diff --git a/dotcom-rendering/src/client/main.web.ts b/dotcom-rendering/src/client/main.web.ts
@@ -51,6 +51,15 @@ void (async () => {
 		},
 	);
 
+	void startup(
+		'abTesting',
+		() =>
+			import(/* webpackMode: 'eager' */ './abTesting').then(
+				({ initABTesting }) => initABTesting(),
+			),
+		{ priority: 'critical' },
+	);
+
 	void startup(
 		'dynamicImport',
 		() =>
diff --git a/dotcom-rendering/src/components/ArticlePage.tsx b/dotcom-rendering/src/components/ArticlePage.tsx
@@ -134,6 +134,9 @@ export const ArticlePage = (props: WebProps | AppProps) => {
 							pageIsSensitive={frontendData.config.isSensitive}
 							isDev={!!frontendData.config.isDev}
 							serverSideTests={frontendData.config.abTests}
+							serverSideABTests={
+								frontendData.config.serverSideABTests
+							}
 						/>
 					</Island>
 				</>
diff --git a/dotcom-rendering/src/components/FrontPage.tsx b/dotcom-rendering/src/components/FrontPage.tsx
@@ -80,6 +80,7 @@ export const FrontPage = ({ front, NAV }: Props) => {
 					pageIsSensitive={front.config.isSensitive}
 					isDev={!!front.config.isDev}
 					serverSideTests={front.config.abTests}
+					serverSideABTests={front.config.serverSideABTests}
 				/>
 			</Island>
 
diff --git a/dotcom-rendering/src/components/SetABTests.importable.tsx b/dotcom-rendering/src/components/SetABTests.importable.tsx
@@ -1,12 +1,13 @@
 import type { CoreAPIConfig } from '@guardian/ab-core';
 import { AB } from '@guardian/ab-core';
 import { getCookie, isUndefined, log } from '@guardian/libs';
-import { useEffect, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { getOphan } from '../client/ophan/ophan';
 import { tests } from '../experiments/ab-tests';
 import { runnableTestsToParticipations } from '../experiments/lib/ab-participations';
+import { BetaABTests } from '../experiments/lib/beta-ab-tests';
 import { getForcedParticipationsFromUrl } from '../lib/getAbUrlHash';
-import { setABTests } from '../lib/useAB';
+import { setABTests, setBetaABTests } from '../lib/useAB';
 import type { ABTestSwitches } from '../model/enhance-switches';
 import type { ServerSideTests } from '../types/config';
 import { useConfig } from './ConfigContext';
@@ -17,6 +18,7 @@ type Props = {
 	isDev: boolean;
 	pageIsSensitive: CoreAPIConfig['pageIsSensitive'];
 	serverSideTests: ServerSideTests;
+	serverSideABTests: Record<string, string>;
 };
 
 const mvtMinValue = 1;
@@ -49,6 +51,12 @@ const getLocalMvtId = () =>
 		}),
 	);
 
+const errorReporter = (e: unknown) =>
+	window.guardian.modules.sentry.reportError(
+		e instanceof Error ? e : Error(String(e)),
+		'ab-tests',
+	);
+
 /**
  * Initialises the values of `useAB` and sends relevant Ophan events.
  *
@@ -66,6 +74,7 @@ export const SetABTests = ({
 	abTestSwitches,
 	forcedTestVariants,
 	serverSideTests,
+	serverSideABTests,
 }: Props) => {
 	const { renderingTarget } = useConfig();
 	const [ophan, setOphan] = useState<Awaited<ReturnType<typeof getOphan>>>();
@@ -81,6 +90,16 @@ export const SetABTests = ({
 			});
 	}, [renderingTarget]);
 
+	const betaAb = useMemo(
+		() =>
+			new BetaABTests({
+				serverSideABTests,
+			}),
+		[serverSideABTests],
+	);
+
+	setBetaABTests(betaAb);
+
 	useEffect(() => {
 		if (!ophan) return;
 
@@ -106,11 +125,7 @@ export const SetABTests = ({
 			forcedTestVariants: allForcedTestVariants,
 			ophanRecord: ophan.record,
 			serverSideTests,
-			errorReporter: (e) =>
-				window.guardian.modules.sentry.reportError(
-					e instanceof Error ? e : Error(String(e)),
-					'ab-tests',
-				),
+			errorReporter,
 		});
 		const allRunnableTests = ab.allRunnableTests(tests);
 		const participations = runnableTestsToParticipations(allRunnableTests);
@@ -123,6 +138,9 @@ export const SetABTests = ({
 		ab.trackABTests(allRunnableTests);
 		ab.registerImpressionEvents(allRunnableTests);
 		ab.registerCompleteEvents(allRunnableTests);
+
+		betaAb.trackABTests(ophan.record, errorReporter);
+
 		log('dotcom', 'AB tests initialised');
 	}, [
 		abTestSwitches,
@@ -131,6 +149,7 @@ export const SetABTests = ({
 		pageIsSensitive,
 		ophan,
 		serverSideTests,
+		betaAb,
 	]);
 
 	// we don’t render anything
diff --git a/dotcom-rendering/src/components/SportDataPageComponent.tsx b/dotcom-rendering/src/components/SportDataPageComponent.tsx
@@ -72,6 +72,7 @@ export const SportDataPageComponent = ({ sportData }: Props) => {
 					pageIsSensitive={sportData.config.isSensitive}
 					isDev={!!sportData.config.isDev}
 					serverSideTests={sportData.config.abTests}
+					serverSideABTests={sportData.config.serverSideABTests}
 				/>
 			</Island>
 			<Island priority="critical">
diff --git a/dotcom-rendering/src/components/TagPage.tsx b/dotcom-rendering/src/components/TagPage.tsx
@@ -76,6 +76,7 @@ export const TagPage = ({ tagPage, NAV }: Props) => {
 					pageIsSensitive={tagPage.config.isSensitive}
 					isDev={!!tagPage.config.isDev}
 					serverSideTests={tagPage.config.abTests}
+					serverSideABTests={tagPage.config.serverSideABTests}
 				/>
 			</Island>
 			<Island priority="critical">
diff --git a/dotcom-rendering/src/experiments/lib/beta-ab-tests.ts b/dotcom-rendering/src/experiments/lib/beta-ab-tests.ts
@@ -0,0 +1,85 @@
+import { isServer } from '../../lib/isServer';
+
+export interface BetaABTestAPI {
+	isUserInTest: (testId: string, variantId: string) => boolean;
+	trackABTests: (
+		ophanRecord: OphanRecordFunction,
+		errorReporter: ErrorReporter,
+	) => void;
+}
+
+type ABParticipations = {
+	[testId: string]: string;
+};
+
+interface OphanABEvent {
+	variantName: string;
+	complete: string | boolean;
+	campaignCodes?: readonly string[];
+}
+
+type OphanABPayload = Record<string, OphanABEvent>;
+
+type OphanRecordFunction = (send: Record<string, OphanABPayload>) => void;
+
+type ErrorReporter = (e: unknown) => void;
+
+type BetaABTestsConfig = {
+	serverSideABTests: Record<string, string>;
+};
+
+/**
+ * generate an A/B event for Ophan
+ */
+const makeABEvent = (variantName: string, complete: boolean): OphanABEvent => {
+	const event: OphanABEvent = {
+		variantName,
+		complete,
+	};
+
+	return event;
+};
+
+export class BetaABTests implements BetaABTestAPI {
+	private participations: ABParticipations;
+
+	constructor({ serverSideABTests }: BetaABTestsConfig) {
+		if (isServer) {
+			this.participations = serverSideABTests;
+		} else {
+			this.participations =
+				window.guardian.modules.abTests?.getParticipations() ?? {};
+		}
+	}
+
+	isUserInTest(testId: string, variantId: string): boolean {
+		return this.participations[testId] === variantId;
+	}
+
+	trackABTests(
+		ophanRecord: OphanRecordFunction,
+		errorReporter: ErrorReporter,
+	): void {
+		ophanRecord({
+			abTestRegister: this.buildOphanPayload(errorReporter),
+		});
+	}
+
+	private buildOphanPayload(errorReporter: ErrorReporter) {
+		try {
+			const testAndVariantIds = Object.entries(this.participations);
+
+			return testAndVariantIds.reduce<OphanABPayload>(
+				(eventLog, [testId, variantId]) => {
+					eventLog[testId] = makeABEvent(variantId, false);
+					return eventLog;
+				},
+				{},
+			);
+		} catch (error: unknown) {
+			// Encountering an error should invalidate the logging process.
+			errorReporter(error);
+			return {};
+		}
+	}
+}
diff --git a/dotcom-rendering/src/frontend/feFront.ts b/dotcom-rendering/src/frontend/feFront.ts
@@ -340,6 +340,7 @@ export type FEFrontConfig = {
 	sharedAdTargeting: SharedAdTargeting;
 	buildNumber: string;
 	abTests: ServerSideTests;
+	serverSideABTests: Record<string, string>;
 	pbIndexSites: { [key: string]: unknown }[];
 	ampIframeUrl: string;
 	beaconUrl: string;
diff --git a/dotcom-rendering/src/lib/useAB.ts b/dotcom-rendering/src/lib/useAB.ts
@@ -1,6 +1,7 @@
 import type { ABTestAPI, Participations } from '@guardian/ab-core';
 import { mutate } from 'swr';
 import useSWRImmutable from 'swr/immutable';
+import type { BetaABTestAPI } from '../experiments/lib/beta-ab-tests';
 
 type ABTests = {
 	api: ABTestAPI;
@@ -26,3 +27,15 @@ export const useAB = (): ABTests | undefined => {
 export const setABTests = ({ api, participations }: ABTests): void => {
 	void mutate(key, { api, participations }, false);
 };
+
+export const useBetaAB = (): BetaABTestAPI | undefined => {
+	const { data } = useSWRImmutable(
+		'beta-ab-tests',
+		() => new Promise<BetaABTestAPI>(() => {}),
+	);
+	return data;
+};
+
+export const setBetaABTests = (api: BetaABTestAPI): void => {
+	void mutate('beta-ab-tests', api, false);
+};
diff --git a/dotcom-rendering/src/model/guardian.ts b/dotcom-rendering/src/model/guardian.ts
@@ -47,6 +47,7 @@ export interface Guardian {
 		};
 		switches: Switches;
 		tests: ServerSideTests;
+		serverSideABTests: Record<string, string>;
 		ophan: {
 			pageViewId: string;
 			browserId: string;
@@ -56,6 +57,16 @@ export interface Guardian {
 		sentry: {
 			reportError: ReportError;
 		};
+		/**
+		 * The 'abTests' is for use by external scripts that need to
+		 * access A/B test information. Do not use this directly
+		 * in DCR, instead use the `useAB` hook as it is csr/ssr aware.
+		 */
+		abTests?: {
+			getParticipations: () => Record<string, string>;
+			isUserInTest: (testId: string) => boolean;
+			isUserInTestGroup: (testId: string, variantId: string) => boolean;
+		};
 	};
 	adBlockers: unknown;
 }
@@ -81,6 +92,7 @@ export const createGuardian = ({
 	googletagUrl,
 	switches,
 	abTests,
+	serverSideABTests,
 	editionId,
 	contentType,
 	brazeApiKey,
@@ -99,6 +111,7 @@ export const createGuardian = ({
 	googletagUrl: string;
 	switches: Switches;
 	abTests: ServerSideTests;
+	serverSideABTests: Record<string, string>;
 	editionId: EditionId;
 	shouldHideReaderRevenue?: boolean;
 	isPaidContent?: boolean;
@@ -147,6 +160,7 @@ export const createGuardian = ({
 			},
 			switches,
 			tests: abTests,
+			serverSideABTests,
 			ophan: {
 				pageViewId: '',
 				browserId: '',
@@ -161,6 +175,11 @@ export const createGuardian = ({
 			sentry: {
 				reportError: () => null,
 			},
+			abTests: {
+				getParticipations: () => ({}),
+				isUserInTest: () => false,
+				isUserInTestGroup: () => false,
+			},
 		},
 	};
 };
diff --git a/dotcom-rendering/src/types/config.ts b/dotcom-rendering/src/types/config.ts
@@ -51,6 +51,7 @@ export interface ConfigType extends CommercialConfigType {
 	dcrSentryDsn: string;
 	switches: Switches;
 	abTests: ServerSideTests;
+	serverSideABTests: Record<string, string>;
 	dfpAccountId: string;
 	commercialBundleUrl: string;
 	revisionNumber: string;
