@scalebun/react-native 1.10.7 → 1.11.0

package/src/features/session/SessionManager.ts

@@ -41,16 +41,16 @@ import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
 import { redactBody } from '../../debug/redaction';
 import { consumeCalibrationTarget } from '../journey/calibrationContext';
 import { resolvePlatformOS } from '../../core/context/device';
+import { emitAutomaticEvent } from '../../analytics/automaticEvents';
+import {
+    INTERACTION_PROTOCOL_VERSION,
+    automaticInteractionProperties,
+    generateInteractionId,
+    type InteractionStateStatus,
+} from '../journey/interactionProtocol';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
-/**
- * Max analytics-lane heatmap interactions emitted per foreground (analytics
- * session) window. Bounds ingest volume now that capture defaults ON; enough to
- * resolve hotspot density, the long tail is dropped (drop-newest beyond cap).
- */
-const HEATMAP_MAX_INTERACTIONS_PER_WINDOW = 200;
-
 export interface SessionManagerConfig {
     sessionReplay?: Partial<SessionReplayConfig>;
     syncPolicy?: SyncDecisionCallback;
@@ -84,16 +84,6 @@ export class SessionManager {
      * lane even when no replay recording is active. Additive, opt-in (default off).
      */
     private _captureInteractionHeatmap = false;
-    /**
-     * Sampling cap for the analytics-lane heatmap emission. Now that capture is
-     * ON by default, an unbounded one-event-per-gesture stream could materially
-     * inflate ingest volume. We cap emitted interactions per analytics-session
-     * window (finalize-scoped per foreground): the first N gestures define the
-     * hotspot shape; the long tail is dropped. Resets when the window changes.
-     */
-    private _heatmapWindowSessionId: string | null = null;
-    private _heatmapWindowCount = 0;
-
     private session: Session | null = null;
     private active = false;
     private timeoutTimer: ReturnType<typeof setTimeout> | null = null;
@@ -740,21 +730,16 @@ export class SessionManager {
      *     injected sensitive keys (e.g. a label) are stripped before transport.
      *   - Never throws.
      */
-    private _emitInteractionToAnalytics(gestureType: string, payload: Record<string, unknown>): void {
-        if (!this._captureInteractionHeatmap) return;
-        if (this.active) return; // recording lane already carries this tap
+    private _emitInteractionToAnalytics(
+        gestureType: string,
+        payload: Record<string, unknown>,
+        occurredAt: number,
+        screenName?: string,
+    ): boolean {
+        if (!this._captureInteractionHeatmap) return false;
+        if (this.active) return false; // recording lane already carries this tap
         const adapter = this._backendTransport;
-        if (!adapter) return;
-
-        // Per-foreground sampling cap. Reset the counter when the analytics
-        // session window rolls over, then drop anything past the cap.
-        const windowId = adapter.analyticsSessionId ?? '';
-        if (windowId !== this._heatmapWindowSessionId) {
-            this._heatmapWindowSessionId = windowId;
-            this._heatmapWindowCount = 0;
-        }
-        if (this._heatmapWindowCount >= HEATMAP_MAX_INTERACTIONS_PER_WINDOW) return;
-        this._heatmapWindowCount++;
+        if (!adapter) return false;
 
         try {
             // Normalize coords in place (same logic as the recording lane).
@@ -782,16 +767,18 @@ export class SessionManager {
                 eventId: generateEventId(),
                 // sessionId is (re)stamped by the analytics lane at flush time.
                 sessionId: adapter.analyticsSessionId ?? '',
-                ts: Date.now(),
+                ts: occurredAt,
                 type: 'USER_ACTION',
                 subtype: `gesture:${gestureType}`,
-                screen: this._lastKnownScreen ?? undefined,
+                screen: screenName ?? this._lastKnownScreen ?? undefined,
                 payload: safePayload,
                 source: 'user',
             };
             adapter.trackEvent(event);
+            return true;
         } catch (err) {
             logger.error('[SessionManager] heatmap analytics emit failed:', err);
+            return false;
         }
     }
 
@@ -810,6 +797,8 @@ export class SessionManager {
             traceId?: string;
             source?: JourneyEventSource;
             journeyId?: string;
+            /** Original observation time; interaction capture may resolve asynchronously. */
+            timestamp?: number;
         },
     ): void {
         if (!this.active) return;
@@ -1046,13 +1035,18 @@ export class SessionManager {
      * Notify of a user interaction. Called by ScaleBunDebugRoot touch handlers.
      * Also triggers frame capture for desktop-initiated recordings.
      */
-    onUserAction(subtype: string, payload?: Record<string, unknown>): void {
+    onUserAction(
+        subtype: string,
+        payload?: Record<string, unknown>,
+        context?: { screen?: string; timestamp?: number },
+    ): void {
         if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
         this.emitEvent('USER_ACTION', {
             subtype,
-            screen: this._lastKnownScreen ?? undefined,
+            screen: context?.screen ?? this._lastKnownScreen ?? undefined,
             payload,
             source: 'user',
+            timestamp: context?.timestamp,
         });
         // NOTE: Do NOT call captureManager.onInteraction() here.
         // emitEvent() already triggers onInteraction() for USER_ACTION events (line ~405).
@@ -1103,11 +1097,22 @@ export class SessionManager {
         screenWidth?: number;
         screenHeight?: number;
         platform?: string;
+        interactionId?: string;
+        interactionProtocol?: number;
+        occurredAt?: number;
+        ui?: string;
+        stateStatus?: InteractionStateStatus;
+        targetId?: string;
+        screenName?: string;
+        emitAutomaticAnalytics?: boolean;
     }): void {
         // Exact-duplicate suppression — see _lastGestureSig. Signature is the gesture type plus
         // raw coordinates verbatim; String() keeps undefined coords distinct from 0 (a payload
         // with no coords never collides with a real origin tap).
-        const dedupSig = `${gestureType}|${String(details?.x)}|${String(details?.y)}|${String(details?.endX)}|${String(details?.endY)}`;
+        const suppliedInteractionId = details?.interactionId;
+        const dedupSig = suppliedInteractionId
+            ? `id:${suppliedInteractionId}`
+            : `${gestureType}|${String(details?.x)}|${String(details?.y)}|${String(details?.endX)}|${String(details?.endY)}`;
         const nowTs = Date.now();
         if (
             dedupSig === this._lastGestureSig &&
@@ -1122,7 +1127,15 @@ export class SessionManager {
         // Build the canonical gesture payload ONCE so the recording lane and the
         // (additive) analytics lane carry byte-identical keys (normalizedX/Y,
         // gestureType, etc.). Same object shape that was previously inlined.
+        const interactionId = suppliedInteractionId ?? generateInteractionId();
+        const occurredAt = details?.occurredAt ?? Date.now();
+        const stateStatus = details?.stateStatus ?? (details?.ui ? 'captured_nonempty' : 'not_captured');
         const payload: Record<string, unknown> = {
+            interaction_id: interactionId,
+            interaction_protocol: details?.interactionProtocol ?? INTERACTION_PROTOCOL_VERSION,
+            state_status: stateStatus,
+            ui: details?.ui,
+            target_id: details?.targetId,
             gestureType,
             x: details?.x,
             y: details?.y,
@@ -1167,7 +1180,27 @@ export class SessionManager {
         // when the flag is OFF, no backend transport is attached, or recording is
         // active (the recording path below already carries this tap). Uses a fresh
         // payload clone so analytics normalization never mutates the recording one.
-        this._emitInteractionToAnalytics(gestureType, { ...payload });
+        const analyticsReplayCarrier = this._emitInteractionToAnalytics(
+            gestureType,
+            { ...payload },
+            occurredAt,
+            details?.screenName,
+        );
+        const replayCarrier = !!this._backendTransport && (this.active || analyticsReplayCarrier);
+        if (details?.emitAutomaticAnalytics) {
+            try {
+                const safePayload = redactBody(payload) as Record<string, unknown>;
+                emitAutomaticEvent(
+                    'element_interacted',
+                    automaticInteractionProperties(
+                        safePayload,
+                        details?.screenName ?? this._lastKnownScreen ?? undefined,
+                        replayCarrier,
+                    ),
+                    occurredAt,
+                );
+            } catch { /* automatic projection must never affect interaction capture */ }
+        }
 
         if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
         // The subtype becomes `ReplayEvent.label`, which is what the Events explorer GROUPS BY. Naming
@@ -1178,7 +1211,11 @@ export class SessionManager {
         // ⚠️ `gestureType` also travels in the payload, and the backend's `resolveGesture` reads THAT
         // first — so enriching the label cannot change heatmap gesture classification.
         const target = typeof details?.target === 'string' ? details.target.trim() : '';
-        this.onUserAction(target ? `gesture:${gestureType} · ${target}` : `gesture:${gestureType}`, payload);
+        this.onUserAction(
+            target ? `gesture:${gestureType} · ${target}` : `gesture:${gestureType}`,
+            payload,
+            { screen: details?.screenName, timestamp: occurredAt },
+        );
     }
 
     /**