@scalebun/react-native 1.10.7 → 1.11.1

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 },
+        );
     }
 
     /**

package/src/public/ScaleBunFacade.ts

@@ -327,6 +327,17 @@ class ScaleBunFacade {
                     );
                 }
             }
+            // `healthyAfterMs` is the field BootGuardConfig actually declares.
+            // This passed `healthyTimeoutMs`, which nothing reads, so a host that
+            // tuned the boot-guard window silently got the 10s default instead.
+            // Both spellings are accepted so the older one keeps working.
+            const healthyAfterMs =
+                typeof ota.healthyAfterMs === 'number'
+                    ? ota.healthyAfterMs
+                    : typeof ota.healthyTimeoutMs === 'number'
+                      ? ota.healthyTimeoutMs
+                      : undefined;
+
             otaOrchestrator.init({
                 ...(signingRequested
                     ? {
@@ -338,16 +349,129 @@ class ScaleBunFacade {
                           },
                       }
                     : {}),
-                ...(typeof ota.healthyTimeoutMs === 'number'
-                    ? { healthyTimeoutMs: ota.healthyTimeoutMs }
-                    : {}),
+                ...(healthyAfterMs !== undefined ? { healthyAfterMs } : {}),
             });
             logger.info('[ScaleBun] OTA enabled from init config.');
+
+            // Run the checks the config asked for. Until this existed, `ota.enabled`
+            // initialised the orchestrator and then never checked anything: the
+            // documented `checkOnForeground` and `channelOverride` options were read
+            // by no code at all, and an app following the documented config received
+            // updates only if it ALSO drove `useOtaUpdate` or the CodePush shim by
+            // hand. Nothing logged, because "no update available" and "never asked"
+            // look identical from the outside.
+            this._startOtaChecks(ota);
         } catch (err: any) {
             logger.warn(`[ScaleBun] OTA init failed: ${err?.message ?? err}`);
         }
     }
 
+    /** Guards against overlapping config-driven OTA checks. */
+    private _otaCheckInFlight = false;
+    /** Wall clock of the last config-driven check, for the foreground floor. */
+    private _otaLastCheckAt = 0;
+    private _otaForegroundListener: ((state: string) => void) | null = null;
+
+    /**
+     * Minimum gap between config-driven checks.
+     *
+     * A foreground transition is cheap to trigger — app switchers, permission
+     * dialogs and share sheets all produce one — so an unthrottled check would
+     * put a request on the hot path every time the user glanced away. Ten
+     * minutes is well below any realistic release cadence and well above that
+     * noise. A host that wants a check on demand calls `useOtaUpdate().sync()`,
+     * which is never throttled.
+     */
+    private static readonly OTA_MIN_CHECK_INTERVAL_MS = 10 * 60 * 1000;
+
+    /**
+     * Drive OTA checks from init config: once at startup, then on each
+     * foreground when `checkOnForeground` is on (the schema default).
+     *
+     * `appVersion` is resolved from the native bridge rather than asked of the
+     * integrator, because it gates the server's `targetAppVersion` semver check
+     * — sending a wrong or invented value is worse than sending none, and there
+     * is no honest default. If it cannot be resolved, the check is skipped with
+     * a warning instead of guessing.
+     */
+    private _startOtaChecks(ota: any): void {
+        // Never in a debug build. `ScaleBunOtaModule.getJSBundleFile()` returns null
+        // there on purpose so Metro keeps ownership of the bundle — so a bundle
+        // downloaded in dev is installed into a slot that will never be loaded, and
+        // the identity check on the next launch then correctly observes that the
+        // running code is not what was installed and reports APPLY_FAILED. Checking
+        // at all in dev buys nothing and manufactures that false alarm. A developer
+        // testing the OTA path drives `useOtaUpdate().sync()` explicitly.
+        if (__DEV__) {
+            logger.info('[ScaleBun] OTA checks are skipped in debug builds (Metro owns the bundle).');
+            return;
+        }
+
+        const runCheck = async (trigger: 'startup' | 'foreground'): Promise<void> => {
+            if (this._otaCheckInFlight) return;
+            if (
+                trigger === 'foreground' &&
+                Date.now() - this._otaLastCheckAt < ScaleBunFacade.OTA_MIN_CHECK_INTERVAL_MS
+            ) {
+                return;
+            }
+            const clientKey = this._clientKey;
+            const apiUrl = this._apiBaseUrl;
+            if (!clientKey || !apiUrl) return;
+
+            this._otaCheckInFlight = true;
+            try {
+                const info = await bridgeAdapter.getDeviceInfo();
+                const appVersion = (info as { appVersion?: string } | null)?.appVersion;
+                if (!appVersion) {
+                    logger.warn(
+                        '[ScaleBun] OTA check skipped — the app version could not be read from the ' +
+                            'native bridge. Rebuild the native app, or drive checks yourself with ' +
+                            'useOtaUpdate({ appVersion }).',
+                    );
+                    return;
+                }
+                this._otaLastCheckAt = Date.now();
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { otaOrchestrator } = require('../features/ota/OtaOrchestrator');
+                await otaOrchestrator.sync({
+                    apiUrl,
+                    clientKey,
+                    appVersion,
+                    // The documented option, finally connected. Omitted means the
+                    // server's `default` channel, exactly as before.
+                    channelName: typeof ota.channelOverride === 'string' ? ota.channelOverride : undefined,
+                    // Never forced from config: the release's own installMode
+                    // decides when the app restarts, and yanking the screen out
+                    // from under a user is not a decision this switch should make.
+                });
+            } catch (err: any) {
+                logger.warn(`[ScaleBun] OTA check failed: ${err?.message ?? err}`);
+            } finally {
+                this._otaCheckInFlight = false;
+            }
+        };
+
+        void runCheck('startup');
+
+        if (ota.checkOnForeground === false) return;
+        if (this._otaForegroundListener) return; // idempotent across repeated init()
+        try {
+            // Through `appLifecycle`, not a second AppState subscription: the SDK
+            // already owns one and fanning out from it keeps every consumer on the
+            // same transition sequence.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { appLifecycle } = require('../core/lifecycle/appLifecycle');
+            this._otaForegroundListener = (state: string) => {
+                if (state === 'active') void runCheck('foreground');
+            };
+            appLifecycle.addListener(this._otaForegroundListener);
+        } catch {
+            // Lifecycle unavailable (tests, exotic hosts) — the startup check stands.
+            this._otaForegroundListener = null;
+        }
+    }
+
     private _autoEnableDebug(debugConfig: DebugConnectionConfig): void {
         try {
             const dbgConfig = buildDebugConfigFromInitConfig(debugConfig);