feat: behavioral targeting for web experiment client (#265)

Author: tyiuhc

packages/experiment-tag/src/behavioral-targeting/behavioral-targeting-manager.ts

@@ -107,7 +107,7 @@ export class BehavioralTargetingManager {
     const eventTypes = new Set<string>();
     for (const andGroup of rules) {
       for (const conditionSet of andGroup) {
-        if (conditionSet.condition.type === 'event') {
+        if (conditionSet.condition.type === 'behavior') {
           eventTypes.add(conditionSet.condition.event_type);
         }
       }

packages/experiment-tag/src/behavioral-targeting/types.ts

@@ -24,7 +24,7 @@ export interface BehavioralConditionSet {
  * A behavioral condition
  */
 export interface BehavioralCondition {
-  type: 'event';
+  type: 'behavior';
   event_type: string; // Event name
   op: (typeof EvaluationOperator)[
     | 'GREATER_THAN_EQUALS'

packages/experiment-tag/src/behavioral-targeting/util.ts

@@ -0,0 +1,30 @@
+/**
+ * Check if two Maps of behavioral flags are equal.
+ * Compares flag keys and their associated behavior ID sets.
+ * @param current Current map of flag keys to behavior ID sets
+ * @param previous Previous map of flag keys to behavior ID sets
+ * @returns true if the maps are equal, false if they're different
+ */
+export function areBehaviorsEqual(
+  current: Map<string, Set<string>> | undefined,
+  previous: Map<string, Set<string>>,
+): boolean {
+  // If one is undefined and the other isn't, they're different
+  if (!current && previous.size > 0) return false;
+  if (current && current.size !== previous.size) return false;
+  if (!current) return true;
+
+  // Check if all keys and their values match
+  for (const [flagKey, behaviorIds] of current) {
+    const previousBehaviorIds = previous.get(flagKey);
+    if (!previousBehaviorIds) return false;
+
+    // Compare sets of behavior IDs
+    if (behaviorIds.size !== previousBehaviorIds.size) return false;
+    for (const id of behaviorIds) {
+      if (!previousBehaviorIds.has(id)) return false;
+    }
+  }
+
+  return true;
+}

packages/experiment-tag/src/experiment.ts

@@ -18,6 +18,7 @@ import * as FeatureExperiment from '@amplitude/experiment-js-client';
 import mutate, { MutationController } from 'dom-mutator';
 import * as domMutatorExports from 'dom-mutator';
 
+import { BehavioralTargetingManager } from './behavioral-targeting';
 import { showPreviewModeModal } from './preview/preview';
 import { MessageBus } from './subscriptions/message-bus';
 import {
@@ -38,6 +39,7 @@ import {
   PreviewVariantsOptions,
   PreviewState,
   RevertVariantsOptions,
+  BehavioralTargetingRules,
 } from './types';
 import type { AudienceEvaluationDebugInfo, DebugState } from './types/debug';
 import { applyAntiFlickerCss } from './util/anti-flicker';
@@ -113,6 +115,10 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
   private readonly messageBus: MessageBus;
   private pageObjects: PageObjects;
   private activePages: PageObjects = {};
+  private readonly behavioralTargetingRules: BehavioralTargetingRules = {};
+  public readonly behavioralTargetingManager:
+    | BehavioralTargetingManager
+    | undefined;
   private subscriptionManager: SubscriptionManager | undefined;
   private isVisualEditorMode = false;
   private isDebugActive = false;
@@ -135,6 +141,17 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
     this.apiKey = apiKey;
     this.initialFlags = JSON.parse(initConfigs.initialFlags);
     this.pageObjects = JSON.parse(initConfigs.pageObjects);
+    this.behavioralTargetingRules = initConfigs.behavioralTargetingRules
+      ? JSON.parse(initConfigs.behavioralTargetingRules)
+      : {};
+
+    // Initialize behavioral targeting infrastructure only if there are rules
+    if (Object.keys(this.behavioralTargetingRules).length > 0) {
+      this.behavioralTargetingManager = new BehavioralTargetingManager(
+        this.apiKey,
+        this.behavioralTargetingRules,
+      );
+    }
     // merge config with defaults and experimentConfig (if provided)
     this.config = {
       ...Defaults,
@@ -214,6 +231,7 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
       this,
       this.messageBus,
       this.pageObjects,
+      this.behavioralTargetingManager,
       {
         ...this.config,
         isVisualEditorMode: this.isVisualEditorMode,
@@ -332,6 +350,7 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
     this.globalScope.experimentIntegration.type = 'integration';
     this.experimentClient.addPlugin(this.globalScope.experimentIntegration);
     this.experimentClient.setUser(enrichedUser);
+    this.updateUserWithBehaviors();
 
     if (!this.isRemoteBlocking) {
       // Remove anti-flicker css if remote flags are not blocking
@@ -591,6 +610,35 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
     }
   }
 
+  /**
+   * Update the user with matched behavioral targeting IDs.
+   * Sets the user property `behavioral_targeting` to an array of all matched behavior IDs.
+   */
+  public updateUserWithBehaviors(): void {
+    // Extract all behavior IDs from the map
+    if (!this.behavioralTargetingManager) {
+      return;
+    }
+    const behaviorIds: string[] = [];
+    for (const behaviorSet of this.behavioralTargetingManager
+      .getMatchedBehaviors()
+      .values()) {
+      behaviorIds.push(...behaviorSet);
+    }
+
+    // Get the current user from the experiment client
+    const currentUser = this.experimentClient.getUser();
+
+    // Update user with behavioral_targeting property directly on the user object
+    const updatedUser = {
+      ...currentUser,
+      behavioral_targeting: behaviorIds,
+    };
+
+    // Set the updated user
+    this.experimentClient.setUser(updatedUser);
+  }
+
   /**
    * When in visual editor mode, update the current page objects and reinitialize subscriptions and active pages.
    *
@@ -723,14 +771,21 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
   }
 
   /**
-   * Track an analytics event that can trigger page objects.
+   * Track an analytics event that can trigger page objects and behavioral targeting.
    * @param event_type The event type/name
    * @param event_properties Optional event properties
    */
   public trackEvent(
     event_type: string,
     event_properties?: Record<string, unknown>,
   ) {
+    // Store event in behavioral targeting storage
+    this.behavioralTargetingManager?.trackEvent(
+      event_type,
+      event_properties || {},
+    );
+
+    // Publish to message bus for page object triggers
     this.messageBus.publish('analytics_event', {
       event: event_type,
       properties: event_properties || {},

packages/experiment-tag/src/index.ts

@@ -39,7 +39,18 @@ export const initialize = (
       .then((previewState) => {
         const initialFlags = JSON.stringify(previewState.flags);
         const pageObjects = JSON.stringify(previewState.pageViewObjects);
-        startClient(apiKey, { initialFlags, pageObjects }, config);
+        const behavioralTargetingRules = JSON.stringify(
+          previewState.behavioralTargetingRules,
+        );
+        startClient(
+          apiKey,
+          {
+            initialFlags,
+            pageObjects,
+            behavioralTargetingRules,
+          },
+          config,
+        );
       })
       .catch((error) => {
         console.warn('Failed to fetch latest configs for preview:', error);

packages/experiment-tag/src/preview/preview-api.ts

@@ -1,14 +1,15 @@
 import { EvaluationFlag } from '@amplitude/experiment-core';
 
 import { version } from '../../package.json';
-import { PageObjects } from '../types';
+import { BehavioralTargetingRules, PageObjects } from '../types';
 
 import { HttpClient } from './http';
 
 export interface PreviewApi {
   getPreviewFlagsAndPageViewObjects(): Promise<{
     flags: EvaluationFlag[];
     pageViewObjects: PageObjects;
+    behavioralTargetingRules?: BehavioralTargetingRules;
   }>;
 }
 
@@ -30,6 +31,7 @@ export class SdkPreviewApi implements PreviewApi {
   public async getPreviewFlagsAndPageViewObjects(): Promise<{
     flags: EvaluationFlag[];
     pageViewObjects: PageObjects;
+    behavioralTargetingRules?: BehavioralTargetingRules;
   }> {
     const headers: Record<string, string> = {
       Authorization: `Api-Key ${this.deploymentKey}`,
@@ -45,10 +47,12 @@ export class SdkPreviewApi implements PreviewApi {
     if (response.status != 200) {
       throw Error(`Preview error response: status=${response.status}`);
     }
-    const flags: EvaluationFlag[] = JSON.parse(response.body)
-      .flags as EvaluationFlag[];
-    const pageViewObjects: PageObjects = JSON.parse(response.body)
-      .pageObjects as PageObjects;
-    return { flags, pageViewObjects };
+    const responseBody = JSON.parse(response.body);
+    const flags: EvaluationFlag[] = responseBody.flags as EvaluationFlag[];
+    const pageViewObjects: PageObjects =
+      responseBody.pageObjects as PageObjects;
+    const behavioralTargetingRules: BehavioralTargetingRules | undefined =
+      responseBody.behavioralTargetingRules;
+    return { flags, pageViewObjects, behavioralTargetingRules };
   }
 }

packages/experiment-tag/src/subscriptions/subscriptions.ts

@@ -1,5 +1,7 @@
 import { EvaluationEngine } from '@amplitude/experiment-core';
 
+import { BehavioralTargetingManager } from '../behavioral-targeting';
+import { areBehaviorsEqual } from '../behavioral-targeting/util';
 import { DefaultWebExperimentClient, INJECT_ACTION } from '../experiment';
 import {
   ElementAppearedTriggerValue,
@@ -55,11 +57,16 @@ export class SubscriptionManager {
   private webExperimentClient: DefaultWebExperimentClient;
   private messageBus: MessageBus;
   private pageObjects: PageObjects;
+  private readonly behavioralTargetingManager:
+    | BehavioralTargetingManager
+    | undefined;
   private options: initOptions;
   private readonly globalScope: typeof globalThis;
   private pageChangeSubscribers: Set<(event: PageChangeEvent) => void> =
     new Set();
   private lastNotifiedActivePages: PageObjects = {};
+  private lastNotifiedActiveBehavioralFlags: Map<string, Set<string>> =
+    new Map();
   private intersectionObservers: Map<string, IntersectionObserver> = new Map();
   private elementVisibilityState: Map<string, boolean> = new Map();
   private elementAppearedState: Set<string> = new Set();
@@ -99,12 +106,14 @@ export class SubscriptionManager {
     webExperimentClient: DefaultWebExperimentClient,
     messageBus: MessageBus,
     pageObjects: PageObjects,
+    behavioralTargetingManager: BehavioralTargetingManager | undefined,
     options: initOptions,
     globalScope: typeof globalThis,
   ) {
     this.webExperimentClient = webExperimentClient;
     this.messageBus = messageBus;
     this.pageObjects = pageObjects;
+    this.behavioralTargetingManager = behavioralTargetingManager;
     this.options = options;
     this.globalScope = globalScope;
   }
@@ -325,6 +334,12 @@ export class SubscriptionManager {
       url_change: new Set(),
     };
 
+    // Ensure analytics_event subscription is set up if behavioral targeting exists
+    // This ensures behavioral targeting evaluation runs even without analytics_event page objects
+    if (this.behavioralTargetingManager) {
+      triggerTypeExperimentMap.analytics_event = new Set();
+    }
+
     for (const [experiment, pages] of Object.entries(this.pageObjects)) {
       for (const page of Object.values(pages)) {
         if (!triggerTypeExperimentMap[page.trigger_type]) {
@@ -361,6 +376,7 @@ export class SubscriptionManager {
     for (const triggerType of Object.keys(triggerTypeExperimentMap)) {
       this.messageBus.groupSubscribe(triggerType as MessageType, (payload) => {
         const isUrlChange = triggerType === 'url_change';
+        const isAnalyticsEvent = triggerType === 'analytics_event';
 
         // Handle URL change: reset state and revert injections
         if (isUrlChange) {
@@ -379,19 +395,52 @@ export class SubscriptionManager {
           this.lastNotifiedActivePages,
         );
 
+        // Get current behavioral state and check if it changed
+        const activeBehavioralFlags =
+          this.webExperimentClient.behavioralTargetingManager?.getMatchedBehaviors();
+
+        const behaviorsChanged =
+          isAnalyticsEvent &&
+          !areBehaviorsEqual(
+            activeBehavioralFlags,
+            this.lastNotifiedActiveBehavioralFlags,
+          );
+        if (behaviorsChanged) {
+          this.webExperimentClient.updateUserWithBehaviors();
+        }
         // Skip processing in visual editor mode or internal updates
         const isInternalUpdate =
           'updateActivePages' in payload && payload.updateActivePages;
         const shouldApplyVariants =
           !isInternalUpdate &&
           !this.options.isVisualEditorMode &&
-          (pagesChanged || isUrlChange);
+          (pagesChanged || behaviorsChanged || isUrlChange);
 
         if (shouldApplyVariants) {
           // Determine which experiments to apply variants for
-          const relevantFlags = isUrlChange
-            ? undefined // All experiments
-            : Array.from(triggerTypeExperimentMap[triggerType] || []);
+          let relevantFlags: string[] | undefined;
+
+          if (isUrlChange) {
+            relevantFlags = undefined; // All experiments
+          } else {
+            // Combine flags from both page triggers and behavioral changes
+            const pageTriggerFlags = Array.from(
+              triggerTypeExperimentMap[triggerType] || [],
+            );
+            const behaviorFlags = behaviorsChanged
+              ? Array.from(
+                  new Set([
+                    ...Array.from(activeBehavioralFlags?.keys() || []),
+                    ...Array.from(
+                      this.lastNotifiedActiveBehavioralFlags?.keys() || [],
+                    ),
+                  ]),
+                )
+              : [];
+            relevantFlags = Array.from(
+              new Set([...pageTriggerFlags, ...behaviorFlags]),
+            );
+          }
 
           // Apply non-preview variants
           this.webExperimentClient.applyVariants({
@@ -427,6 +476,16 @@ export class SubscriptionManager {
         if (pagesChanged || isUrlChange) {
           this.scheduleDebugNotification();
         }
+
+        // Update last notified behaviors if they changed
+        if (behaviorsChanged && activeBehavioralFlags) {
+          this.lastNotifiedActiveBehavioralFlags = new Map(
+            Array.from(activeBehavioralFlags.entries()).map(([key, value]) => [
+              key,
+              new Set(value),
+            ]),
+          );
+        }
       });
     }
   };
@@ -451,6 +510,7 @@ export class SubscriptionManager {
     this.maxScrollPercentage = 0;
     this.pageLoadTime = Date.now();
     this.analyticsEventState.clear();
+    this.lastNotifiedActiveBehavioralFlags = new Map();
 
     // Clear pending click timeouts
     for (const timeout of this.clickTimeouts.values()) {

packages/experiment-tag/src/types.ts

@@ -159,4 +159,5 @@ export type WebExperimentUser = {
 export type InitConfigs = {
   initialFlags: string;
   pageObjects: string;
+  behavioralTargetingRules?: string;
 };