[WS-3079]: Send a Piano activation event when a user is activated into an Optimizely experiment (#14293)

* feat: Piano & Optimizely activation event sync; tests

* fix: activation event wiring, tests

* fix: add tracking state toggle in tests

* fix: hande unsuccessful onReady resolution in activateExperiment; remove redundant activation properties

* feat: implement activation event tracking in the decision event listener

* feat: refactor activation event structure to use personalisation object; related tests

* fix: move activatedExperiments from server side; rename sendOptimizelyActivationEvent --> sendExperimentActivationEvent

* feat: update event structure and related types

* fix: typo

* chore: remove unused useOptimizelyActivationEvent hook, superseded by DECISION listener [copilot]

* fix: remove redundant personalisation

* refactor: activationTrackingData naming

* refactor: update engine_id structure

* test: reuse AllTheProviders

---------

Co-authored-by: Alex Magana <alex.magana@andela.com>
Co-authored-by: Elvinas Valenas <elvinas.valenas.ext@bbc.co.uk>

Author: 3 people

src/app/components/ATIAnalytics/atiUrl/index.ts

@@ -1,9 +1,15 @@
 import {
+  ACTIVATION_EVENT,
+  ACTIVATION_EVENT_INTERACTION_TYPE,
+  ACTIVATION_EVENT_SERVE_ACTION,
+  ACTIVATION_EVENT_SPEC_ID,
+  ACTIVATION_EVENT_SPEC_VERSION,
   CLICK_EVENT,
   VIEW_EVENT,
   VIEWABILITY_CLICK_EVENT,
 } from '#app/lib/analyticsUtils/analytics.const';
 import { getEnvConfig } from '#app/lib/utilities/getEnvConfig';
+import { Platforms } from '#app/models/types/global';
 import {
   getAppType,
   getHref,
@@ -189,3 +195,69 @@ export const buildReverbEventModel = ({
     },
   };
 };
+
+type ActivationEventProps = {
+  pageIdentifier?: string;
+  platform?: Platforms;
+  appName?: string;
+  producerName?: string;
+  statsDestination?: string;
+  experimentName: string;
+  experimentVariant: string;
+  isSignedIn?: boolean;
+  hashedId?: string | null;
+};
+
+/**
+ * Builds the standalone Piano/Reverb "activation" beacon fired when a user is
+ * activated into an Optimizely experiment, decoupled from any view/click event.
+ * Follows the "Activation (v1.0.1) on Web" event-catalogue spec (viewability model),
+ * spec ID ACTIVATION_EVENT_SPEC_ID - see https://broxy.tools.bbc.co.uk/bbc-event-catalogue/xbbc/viewability-events/specs/experiment/activation-web/1.0.1/
+ */
+export const buildActivationEventModel = ({
+  pageIdentifier,
+  platform,
+  appName,
+  producerName,
+  statsDestination,
+  experimentName,
+  experimentVariant,
+  isSignedIn = false,
+  hashedId = null,
+}: ActivationEventProps): ReverbBeaconConfig => ({
+  params: {
+    page: {
+      destination: statsDestination,
+      name: pageIdentifier,
+      producer: producerName,
+      additionalProperties: {
+        type: 'AT',
+        app_name: platform === 'app' ? `${appName}-app` : appName,
+        app_type: getAppType(platform),
+      },
+    },
+    user: {
+      isSignedIn,
+      hashedId,
+    },
+  },
+  eventDetails: {
+    eventName: ACTIVATION_EVENT,
+    eventPublisher: 'viewability',
+    event: {
+      category: 'viewability',
+      action: ACTIVATION_EVENT_SERVE_ACTION,
+      // Identifies this 'serve' event as an activation event, pending a dedicated event_action value in the spec
+      interaction_type: ACTIVATION_EVENT_INTERACTION_TYPE,
+      spec_id: ACTIVATION_EVENT_SPEC_ID,
+      spec_version: ACTIVATION_EVENT_SPEC_VERSION,
+    },
+    group: {
+      type: 'experiment',
+      name: 'optimizely',
+    },
+    experience: {
+      engine_id: [`optimizely.${experimentName}.${experimentVariant}`],
+    },
+  },
+});

src/app/components/ATIAnalytics/types.ts

@@ -104,6 +104,7 @@ export type ReverbPageVars = {
   name?: string | null;
   additionalProperties?: {
     app_name?: string | null;
+    app_type?: string | null;
     content_language?: string | null;
     type?: string | null;
   };
@@ -119,22 +120,30 @@ export type ReverbUserVars = {
 };
 
 export type ReverbEventDetails = {
+  actionName?: string;
   anchorElement?: HTMLElement;
+  background?: boolean;
+  container?: string;
   experience?: {
-    engine_type: Array<string>;
+    engine_type?: Array<string>;
     engine_id: Array<string>;
   };
   event?: {
     category: string;
-    action: 'select' | 'view';
+    action: 'select' | 'view' | 'serve';
     grouping?: string;
+    interaction_type?: string;
+    spec_id?: string;
+    spec_version?: string;
   };
-  eventName: 'pageView' | 'sectionView' | 'sectionClick';
+  eventName: 'pageView' | 'sectionView' | 'sectionClick' | 'activation';
   eventPublisher?: string;
   group?: string | object;
   isClick?: boolean;
   item?: string | object;
   originalEvent?: Event;
+  // Appended to 'actionName' by Reverb to form the 'creation' slot as 'actionName~type'
+  type?: string;
 };
 
 export type ReverbBeaconConfig = {

src/app/components/react-testing-library-with-providers.tsx

@@ -13,7 +13,13 @@ import {
   PageMetadata,
 } from '../contexts/ReverbParamsContext';
 import ThemeProvider from './ThemeProvider';
-import { PageTypes, Services, Toggles, Variants } from '../models/types/global';
+import {
+  PageTypes,
+  ServerSideExperiment,
+  Services,
+  Toggles,
+  Variants,
+} from '../models/types/global';
 
 jest.mock('./ThemeProvider');
 
@@ -43,6 +49,7 @@ interface Props extends PropsWithChildren {
   pageLang?: string;
   isUK?: boolean | null;
   idctaConfig?: IdctaConfig | null;
+  serverSideExperiments?: ServerSideExperiment[] | null;
 }
 
 const AllTheProviders: FC<Props> = ({
@@ -66,6 +73,7 @@ const AllTheProviders: FC<Props> = ({
   isNextJs = false,
   isUK = null,
   idctaConfig = null,
+  serverSideExperiments = null,
 }: Props) => {
   return (
     <ToggleContextProvider toggles={toggles}>
@@ -90,6 +98,7 @@ const AllTheProviders: FC<Props> = ({
           showCookieBannerBasedOnCountry={showCookieBannerBasedOnCountry}
           statusCode={statusCode}
           isUK={isUK}
+          serverSideExperiments={serverSideExperiments}
         >
           <AccountProvider initialConfig={idctaConfig}>
             <ReverbParamsContextProvider metadata={pageMetadata}>
@@ -135,6 +144,7 @@ const customRender = (
     pageLang,
     isUK,
     idctaConfig,
+    serverSideExperiments,
   } = options || {};
 
   return render(ui, {
@@ -160,6 +170,7 @@ const customRender = (
         pageLang={pageLang}
         isUK={isUK}
         idctaConfig={idctaConfig}
+        serverSideExperiments={serverSideExperiments}
       >
         {children}
       </AllTheProviders>

src/app/contexts/EventTrackingContext/index.test.tsx

@@ -54,6 +54,7 @@ describe('Expected use', () => {
     const trackingData = JSON.parse(testEl.textContent as string);
 
     expect(trackingData).toEqual({
+      appName: 'news-pidgin',
       campaignID: 'article-sty',
       hashedId: null,
       isSignedIn: false,
@@ -78,6 +79,7 @@ describe('Expected use', () => {
     const trackingData = JSON.parse(testEl.textContent as string);
 
     expect(trackingData).toEqual({
+      appName: 'news-kyrgyz',
       campaignID: 'index-home',
       hashedId: null,
       isSignedIn: false,

src/app/contexts/EventTrackingContext/index.tsx

@@ -1,6 +1,7 @@
 import { createContext, PropsWithChildren, use, useMemo } from 'react';
 
 import { AccountContext } from '#contexts/AccountContext';
+import { setActivationTrackingData } from '#app/lib/analyticsUtils/activationTrackingData';
 import { RequestContext } from '../RequestContext';
 import useToggle from '../../hooks/useToggle';
 import {
@@ -86,7 +87,11 @@ export const EventTrackingContextProvider = ({
   const { pageType, platform, statsDestination } = requestContext;
 
   const serviceContext = use(ServiceContext);
-  const { atiAnalyticsProducerId, atiAnalyticsProducerName } = serviceContext;
+  const {
+    atiAnalyticsAppName,
+    atiAnalyticsProducerId,
+    atiAnalyticsProducerName,
+  } = serviceContext;
 
   const { isSignedIn, hashedUserId } = use(AccountContext);
   const { enabled: eventTrackingIsEnabled } = useToggle('eventTracking');
@@ -100,6 +105,7 @@ export const EventTrackingContextProvider = ({
         campaignID,
         pageIdentifier,
         platform,
+        appName: atiAnalyticsAppName,
         producerId: atiAnalyticsProducerId,
         producerName: atiAnalyticsProducerName,
         statsDestination,
@@ -109,6 +115,7 @@ export const EventTrackingContextProvider = ({
     }
     return null;
   }, [
+    atiAnalyticsAppName,
     atiAnalyticsProducerId,
     atiAnalyticsProducerName,
     atiData,
@@ -121,6 +128,8 @@ export const EventTrackingContextProvider = ({
   ]);
 
   if (!eventTrackingIsEnabled || !atiData) {
+    setActivationTrackingData({ trackingIsEnabled: false });
+
     return (
       <EventTrackingContext.Provider value={NO_TRACKING_PROPS}>
         {children}
@@ -139,6 +148,20 @@ export const EventTrackingContextProvider = ({
       trackingProps.statsDestination,
     ].every(Boolean);
 
+  // Populated synchronously (not in an effect) so it's set before any descendant's
+  // effects run and potentially trigger an Optimizely decision on this same render pass.
+  const activationTrackingData = {
+    trackingIsEnabled: Boolean(hasRequiredProps),
+    pageIdentifier: trackingProps?.pageIdentifier,
+    platform: trackingProps?.platform,
+    appName: trackingProps?.appName,
+    producerName: trackingProps?.producerName,
+    statsDestination: trackingProps?.statsDestination,
+    isSignedIn: trackingProps?.isSignedIn,
+    hashedId: trackingProps?.hashedId,
+  };
+  setActivationTrackingData(activationTrackingData);
+
   return (
     <EventTrackingContext.Provider
       value={

src/app/hooks/useOptimizelyVariation/activateExperiment/index.test.ts

@@ -1,12 +1,13 @@
 import onClient from '#lib/utilities/onClient';
 import { ReactSDKClient } from '@optimizely/react-sdk';
-import activateExperiment from '.';
+import activateExperiment, { resetActivatedExperiments } from '.';
 
 jest.mock('#lib/utilities/onClient');
 
 describe('activateExperiment', () => {
   afterEach(() => {
     jest.clearAllMocks();
+    resetActivatedExperiments();
   });
 
   const mockOptimizely = {
@@ -52,4 +53,57 @@ describe('activateExperiment', () => {
     expect(mockOptimizely.setForcedVariation).not.toHaveBeenCalled();
     expect(mockOptimizely.activate).not.toHaveBeenCalled();
   });
+
+  it('should not activate again if the experiment was already activated', async () => {
+    (onClient as jest.Mock).mockReturnValue(true);
+    mockOptimizely.onReady.mockResolvedValue({ success: true });
+
+    await activateExperiment({
+      optimizely: mockOptimizely as unknown as ReactSDKClient,
+      experimentName: mockExperimentName,
+      experimentVariation: mockExperimentVariation,
+    });
+
+    await activateExperiment({
+      optimizely: mockOptimizely as unknown as ReactSDKClient,
+      experimentName: mockExperimentName,
+      experimentVariation: mockExperimentVariation,
+    });
+
+    expect(mockOptimizely.activate).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not activate again for a concurrent hook instance activating the same experiment', async () => {
+    (onClient as jest.Mock).mockReturnValue(true);
+    mockOptimizely.onReady.mockResolvedValue({ success: true });
+
+    await Promise.all([
+      activateExperiment({
+        optimizely: mockOptimizely as unknown as ReactSDKClient,
+        experimentName: mockExperimentName,
+        experimentVariation: mockExperimentVariation,
+      }),
+      activateExperiment({
+        optimizely: mockOptimizely as unknown as ReactSDKClient,
+        experimentName: mockExperimentName,
+        experimentVariation: mockExperimentVariation,
+      }),
+    ]);
+
+    expect(mockOptimizely.activate).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not set a forced variation or activate when onReady resolves with success: false', async () => {
+    (onClient as jest.Mock).mockReturnValueOnce(true);
+    mockOptimizely.onReady.mockResolvedValue({ success: false });
+
+    await activateExperiment({
+      optimizely: mockOptimizely as unknown as ReactSDKClient,
+      experimentName: mockExperimentName,
+      experimentVariation: mockExperimentVariation,
+    });
+
+    expect(mockOptimizely.setForcedVariation).not.toHaveBeenCalled();
+    expect(mockOptimizely.activate).not.toHaveBeenCalled();
+  });
 });

src/app/hooks/useOptimizelyVariation/activateExperiment/index.ts

@@ -1,6 +1,12 @@
 import onClient from '#lib/utilities/onClient';
 import { ReactSDKClient } from '@optimizely/react-sdk';
 
+// Module-level (not per hook-instance) so concurrent renders of the same
+// experiment can't each independently pass the guard and call activate().
+const activatedExperiments = new Set<string>();
+
+const resetActivatedExperiments = () => activatedExperiments.clear();
+
 type Props = {
   optimizely: ReactSDKClient;
   experimentName: string;
@@ -13,12 +19,14 @@ const activateExperiment = async ({
   experimentVariation,
 }: Props) => {
   if (onClient() && optimizely) {
-    const success = await optimizely?.onReady();
-    if (success) {
+    const { success } = await optimizely.onReady();
+    if (success && !activatedExperiments.has(experimentName)) {
+      activatedExperiments.add(experimentName);
       optimizely.setForcedVariation(experimentName, experimentVariation);
       optimizely.activate(experimentName);
     }
   }
 };
 
 export default activateExperiment;
+export { resetActivatedExperiments };