feat(experiment-tag): Wire relay iframe on start

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

@@ -2,6 +2,7 @@ import { BehavioralTargetingRules } from '../types';
 
 import { BehavioralTargetingEvaluator } from './evaluator';
 import { EventStorageManager } from './event-storage';
+import { RelayClient } from './relay-client';
 import { SessionManager } from './session-manager';
 import { BehavioralTargeting } from './types';
 
@@ -51,6 +52,48 @@ export class BehavioralTargetingManager {
     this.evaluateEvent(eventType);
   }
 
+  /**
+   * Attach the relay client for cross-subdomain event dual-write.
+   */
+  public setRelayClient(relayClient: RelayClient | null): void {
+    this.eventStorage.setRelayClient(relayClient);
+  }
+
+  /**
+   * Pass 2: migrate local events to relay if needed, merge relay store, re-evaluate.
+   * Returns true when relay store was merged.
+   */
+  public async syncFromRelay(): Promise<boolean> {
+    const synced = await this.eventStorage.syncFromRelay();
+    if (synced) {
+      this.evaluateAll();
+    }
+    return synced;
+  }
+
+  /**
+   * Inject relay iframe (non-blocking init) and run Pass 2 sync.
+   *
+   * @returns true when matched behaviors changed after relay sync
+   */
+  public async beginRelaySync(relayClient: RelayClient): Promise<boolean> {
+    const behaviorsBefore = this.serializeMatchedBehaviors();
+    this.setRelayClient(relayClient);
+    await relayClient.init();
+    if (!relayClient.relayAvailable) {
+      await relayClient.waitForAvailable();
+    }
+    if (!relayClient.relayAvailable) {
+      this.setRelayClient(null);
+      return false;
+    }
+    const synced = await this.syncFromRelay();
+    if (!synced) {
+      return false;
+    }
+    return behaviorsBefore !== this.serializeMatchedBehaviors();
+  }
+
   /**
    * Check if a flag has behavioral targeting rules.
    * @param flagKey The flag key to check
@@ -175,6 +218,14 @@ export class BehavioralTargetingManager {
    * @param flagKey The flag key to evaluate
    * @param behaviorId The specific behavior ID to evaluate
    */
+  private serializeMatchedBehaviors(): string {
+    const snapshot: Record<string, string[]> = {};
+    for (const [flagKey, behaviorIds] of this.matchedBehaviors.entries()) {
+      snapshot[flagKey] = [...behaviorIds].sort();
+    }
+    return JSON.stringify(snapshot);
+  }
+
   private evaluateBehaviorId(flagKey: string, behaviorId: string): void {
     const rulesByIds = this.rules[flagKey];
     if (!rulesByIds || !rulesByIds[behaviorId]) {

packages/experiment-tag/src/behavioral-targeting/relay-client.ts

@@ -49,6 +49,7 @@ export class RelayClient {
   private initResolve: (() => void) | null = null;
   private cancelBodyReadyPoll: (() => void) | null = null;
   private destroyed = false;
+  private readonly availableWaiters: Array<() => void> = [];
 
   constructor(
     private readonly apiKey: string,
@@ -75,6 +76,46 @@ export class RelayClient {
     return this.available;
   }
 
+  private notifyAvailable(): void {
+    const waiters = [...this.availableWaiters];
+    this.availableWaiters.length = 0;
+    for (const waiter of waiters) {
+      waiter();
+    }
+  }
+
+  /**
+   * Resolves when the relay becomes available, or after timeout.
+   * Use after init() when the init timer may have fired before RELAY_READY.
+   */
+  waitForAvailable(timeoutMs = RELAY_RPC_TIMEOUT_MS): Promise<boolean> {
+    if (this.destroyed) {
+      return Promise.resolve(false);
+    }
+    if (this.available) {
+      return Promise.resolve(true);
+    }
+
+    return new Promise((resolve) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        window.clearTimeout(timeoutId);
+        const idx = this.availableWaiters.indexOf(onAvailable);
+        if (idx !== -1) {
+          this.availableWaiters.splice(idx, 1);
+        }
+        resolve(this.available && !this.destroyed);
+      };
+      const onAvailable = () => finish();
+      this.availableWaiters.push(onAvailable);
+      const timeoutId = window.setTimeout(() => finish(), timeoutMs);
+    });
+  }
+
   async init(): Promise<void> {
     if (this.initPromise) {
       return this.initPromise;
@@ -131,6 +172,7 @@ export class RelayClient {
             this.iframeWindow = iframe.contentWindow;
             this.available = true;
             this.flush();
+            this.notifyAvailable();
             finishInit();
             return;
           }
@@ -189,28 +231,41 @@ export class RelayClient {
     if (this.destroyed) {
       return;
     }
+
+    // Queue until async write confirms — flush() can resend in-flight events on unload.
+    this.pendingWrites.push(event);
+    this.sendPendingWrite(event);
+  }
+
+  private removeConfirmedWrite(event: RelayEventRecord): void {
+    const idx = this.pendingWrites.indexOf(event);
+    if (idx !== -1) {
+      this.pendingWrites.splice(idx, 1);
+    }
+  }
+
+  private sendPendingWrite(event: RelayEventRecord): void {
     if (!this.available || !this.iframeWindow) {
-      this.pendingWrites.push(event);
       return;
     }
-    void this.sendRequest(
-      this.createRelayRequest('WRITE_EVENT', { event }),
-    ).catch(() => {
-      // fire-and-forget
-    });
+
+    void this.sendRequest(this.createRelayRequest('WRITE_EVENT', { event }))
+      .then((response) => {
+        if (response.ok) {
+          this.removeConfirmedWrite(event);
+        }
+      })
+      .catch(() => {
+        // Keep in pendingWrites for a later flush()
+      });
   }
 
   flush(): void {
     if (!this.available || !this.iframeWindow) {
       return;
     }
-    const writes = [...this.pendingWrites];
-    this.pendingWrites = [];
-    for (const event of writes) {
-      this.iframeWindow.postMessage(
-        this.createRelayRequest('WRITE_EVENT', { event }),
-        this.relayOrigin,
-      );
+    for (const event of [...this.pendingWrites]) {
+      this.sendPendingWrite(event);
     }
   }
 
@@ -256,6 +311,7 @@ export class RelayClient {
       pending.reject(new Error('relay destroyed'));
     }
     this.pendingRequests.clear();
+    this.availableWaiters.length = 0;
     this.iframe?.remove();
     this.iframe = null;
     this.iframeWindow = null;

packages/experiment-tag/src/experiment.ts

@@ -24,6 +24,7 @@ import * as domMutatorExports from 'dom-mutator';
 import type { MutationController } from 'dom-mutator/dist/types';
 
 import { BehavioralTargetingManager } from './behavioral-targeting';
+import { getRelayUrl, RelayClient } from './behavioral-targeting/relay-client';
 import { showPreviewModeModal } from './preview/preview';
 import { MessageBus } from './subscriptions/message-bus';
 import {
@@ -138,6 +139,7 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
   public readonly behavioralTargetingManager:
     | BehavioralTargetingManager
     | undefined;
+  private relayClient: RelayClient | null = null;
   private subscriptionManager: SubscriptionManager | undefined;
   private isVisualEditorMode = false;
   private isDebugActive = false;
@@ -466,6 +468,7 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
         Object.keys(this.previewFlags).includes(key),
       )
     ) {
+      this.scheduleRelaySync(enrichedUser);
       this.isRunning = true;
       flushEventBuffer(this);
       return;
@@ -474,6 +477,7 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
     await this.fetchRemoteFlags();
     // apply remote variants - if fetch is unsuccessful, fallback order: 1. localStorage flags, 2. initial flags
     await this.applyVariants({ flagKeys: this.remoteFlagKeys });
+    this.scheduleRelaySync(enrichedUser);
     this.isRunning = true;
     flushEventBuffer(this);
   }
@@ -710,6 +714,78 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
     }
   }
 
+  /**
+   * Non-blocking relay iframe init + Pass 2 sync.
+   */
+  private scheduleRelaySync(user: WebExperimentUser): void {
+    if (!this.behavioralTargetingManager || this.isVisualEditorMode) {
+      return;
+    }
+
+    const webExpIdV2 = user.web_exp_id_v2 ?? user.web_exp_id;
+    if (!webExpIdV2) {
+      return;
+    }
+
+    this.relayClient?.destroy();
+    const relayClient = new RelayClient(
+      this.apiKey,
+      webExpIdV2,
+      getRelayUrl(this.apiKey),
+    );
+    this.relayClient = relayClient;
+
+    void this.behavioralTargetingManager
+      .beginRelaySync(relayClient)
+      .then((behaviorsChanged) => {
+        if (this.relayClient !== relayClient) {
+          return;
+        }
+        if (!relayClient.relayAvailable) {
+          relayClient.destroy();
+          this.relayClient = null;
+          return;
+        }
+        return this.handleRelayPass2(behaviorsChanged).catch((pass2Error) => {
+          console.warn('Experiment relay Pass 2 failed:', pass2Error);
+        });
+      })
+      .catch(() => {
+        if (this.relayClient !== relayClient) {
+          return;
+        }
+        relayClient.destroy();
+        this.relayClient = null;
+      });
+  }
+
+  /**
+   * Pass 2: re-apply variants when relay sync changes matched behaviors.
+   */
+  private async handleRelayPass2(behaviorsChanged: boolean): Promise<void> {
+    if (!behaviorsChanged || !this.behavioralTargetingManager) {
+      return;
+    }
+
+    this.updateUserWithBehaviors();
+
+    const flagKeys = Object.keys(this.behavioralTargetingRules);
+    const localKeys = flagKeys.filter((key) =>
+      this.localFlagKeys.includes(key),
+    );
+    const remoteKeys = flagKeys.filter((key) =>
+      this.remoteFlagKeys.includes(key),
+    );
+
+    if (localKeys.length > 0) {
+      await this.applyVariants({ flagKeys: localKeys });
+    }
+    if (remoteKeys.length > 0) {
+      await this.fetchRemoteFlags();
+      await this.applyVariants({ flagKeys: remoteKeys });
+    }
+  }
+
   /**
    * Update the user with matched behavioral targeting IDs.
    * Sets the user property `behavioral_targeting` to an array of all matched behavior IDs.

packages/experiment-tag/src/types.ts

@@ -173,6 +173,8 @@ export interface WebExperimentClient {
 
 export type WebExperimentUser = {
   web_exp_id?: string;
+  /** Cross-subdomain visitor ID; falls back to web_exp_id for relay wiring. */
+  web_exp_id_v2?: string;
 } & ExperimentUser;
 
 export type InitConfigs = {