@repliqo/sdk-react-native 0.3.8 → 0.4.1

package/dist/components/useRepliqoScrollTracking.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRepliqoScrollTracking = useRepliqoScrollTracking;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const client_1 = require("../core/client");
+/** Minimum scroll delta (px) to trigger a new tile capture. */
+const MIN_DELTA_PX = 20;
+/** Debounce: wait this long after scroll stops before capturing. */
+const DEBOUNCE_MS = 250;
+/** Throttle: minimum time between tile captures. */
+const THROTTLE_MS = 400;
+/**
+ * During continuous scroll, force a capture every this many ms.
+ * Ensures tiles are captured even during fast, uninterrupted scrolls
+ * where the user never pauses long enough for the debounce to fire.
+ */
+const SCROLL_INTERVAL_MS = 1200;
+/**
+ * During scroll, throttle window-bounds re-measurement to at most once per
+ * this many ms. Bounds rarely change while scrolling, but we still want to
+ * catch orientation changes / keyboard / overlay animations.
+ */
+const REMEASURE_THROTTLE_MS = 500;
+/**
+ * The continuous-scroll interval self-stops when no scroll event has been
+ * seen for this long. Programmatic scrolls (scrollTo / Animated) fire
+ * onScroll but never onScrollEndDrag/onMomentumScrollEnd — without this,
+ * the interval would keep running until unmount.
+ */
+const INTERVAL_IDLE_STOP_MS = SCROLL_INTERVAL_MS * 2;
+let scrollViewIdCounter = 0;
+const nextScrollViewId = () => `repliqo-scroll-${++scrollViewIdCounter}`;
+/**
+ * Shared scroll-analytics behavior behind RepliqoScrollView and
+ * RepliqoFlatList:
+ *
+ *  1. Reports scroll offset for accurate heatmap touch coords
+ *  2. Captures viewport tiles on scroll stops AND during continuous
+ *     scroll for collaborative screen building
+ *  3. Registers window-relative bounds with the SDK so touches are
+ *     auto-classified as content (inside) vs fixed UI (outside)
+ *
+ * @param forwardedRef  The consumer's ref (function or object).
+ * @param userHandlers  The consumer's own scroll/layout handlers — always
+ *                      called after the SDK's.
+ */
+function useRepliqoScrollTracking(forwardedRef, userHandlers) {
+    const debounceTimer = (0, react_1.useRef)(null);
+    const scrollIntervalTimer = (0, react_1.useRef)(null);
+    const initialLayoutTimer = (0, react_1.useRef)(null);
+    const lastCaptureTime = (0, react_1.useRef)(0);
+    const lastCaptureY = (0, react_1.useRef)(-999);
+    const lastMeasureTime = (0, react_1.useRef)(0);
+    const lastScrollEventAt = (0, react_1.useRef)(0);
+    const initialCaptured = (0, react_1.useRef)(false);
+    const realContentHeight = (0, react_1.useRef)(0);
+    const scrollViewId = (0, react_1.useRef)(nextScrollViewId());
+    const innerRef = (0, react_1.useRef)(null);
+    const isMounted = (0, react_1.useRef)(true);
+    // Last measured window-relative top Y — passed to captureScrollTile so
+    // the backend can crop each tile to just the scroll viewport area.
+    const lastViewportTop = (0, react_1.useRef)(null);
+    const scrollState = (0, react_1.useRef)(null);
+    // Keep the latest user handlers in a ref so our stable callbacks always
+    // call the current ones.
+    const handlersRef = (0, react_1.useRef)(userHandlers);
+    handlersRef.current = userHandlers;
+    // Forward the inner ref to the consumer's ref (if provided).
+    // IMPORTANT: do NOT clear innerRef on cleanup — RN sometimes calls the
+    // ref callback with null mid-update, and clearing would break async
+    // measurement callbacks that fire after the ref reattaches.
+    const setRef = (0, react_1.useCallback)((node) => {
+        if (node !== null) {
+            innerRef.current = node;
+        }
+        if (typeof forwardedRef === 'function') {
+            forwardedRef(node);
+        }
+        else if (forwardedRef) {
+            forwardedRef.current = node;
+        }
+    }, [forwardedRef]);
+    /**
+     * Resolve the node that actually supports measureInWindow. FlatList (and
+     * other VirtualizedList wrappers) don't expose it directly — their inner
+     * ScrollView does, reachable via getNativeScrollRef().
+     */
+    const resolveMeasurableNode = () => {
+        const node = innerRef.current;
+        if (!node)
+            return null;
+        if (typeof node.measureInWindow === 'function')
+            return node;
+        try {
+            const inner = typeof node.getNativeScrollRef === 'function'
+                ? node.getNativeScrollRef()
+                : typeof node.getScrollableNode === 'function'
+                    ? node.getScrollableNode()
+                    : null;
+            if (inner && typeof inner.measureInWindow === 'function')
+                return inner;
+        }
+        catch {
+            /* ignore */
+        }
+        return null;
+    };
+    /**
+     * Measure window-relative bounds and register with the SDK.
+     * Idempotent + safe to call after unmount (guards via isMounted).
+     */
+    const measureAndRegister = (0, react_1.useCallback)(() => {
+        if (!isMounted.current)
+            return;
+        const node = resolveMeasurableNode();
+        if (!node)
+            return;
+        node.measureInWindow((x, y, width, height) => {
+            if (!isMounted.current)
+                return;
+            // RN sometimes returns 0/0 dims before the view is positioned —
+            // ignore those, the next onLayout/onScroll will re-measure.
+            if (width <= 0 || height <= 0)
+                return;
+            lastViewportTop.current = y;
+            try {
+                client_1.AppAnalytics.getInstance().registerScrollView(scrollViewId.current, {
+                    x, y, width, height,
+                });
+            }
+            catch { }
+        });
+    }, []);
+    // Cleanup all timers + unregister + listeners on unmount
+    (0, react_1.useEffect)(() => {
+        const id = scrollViewId.current;
+        isMounted.current = true;
+        // Re-measure when keyboard appears/disappears (causes layout shift)
+        const showSub = react_native_1.Keyboard.addListener('keyboardDidShow', measureAndRegister);
+        const hideSub = react_native_1.Keyboard.addListener('keyboardDidHide', measureAndRegister);
+        return () => {
+            isMounted.current = false;
+            if (debounceTimer.current)
+                clearTimeout(debounceTimer.current);
+            if (scrollIntervalTimer.current)
+                clearInterval(scrollIntervalTimer.current);
+            if (initialLayoutTimer.current)
+                clearTimeout(initialLayoutTimer.current);
+            showSub.remove();
+            hideSub.remove();
+            try {
+                client_1.AppAnalytics.getInstance().unregisterScrollView(id);
+            }
+            catch { }
+        };
+    }, [measureAndRegister]);
+    /**
+     * Core tile capture logic. Reads from refs (stable across renders).
+     * Checks throttle + delta before capturing.
+     *
+     * @param force Skip throttle check (used for interval captures)
+     */
+    const doCapture = (force = false) => {
+        if (!isMounted.current)
+            return;
+        const state = scrollState.current;
+        if (!state || state.viewportHeight <= 0)
+            return;
+        const now = Date.now();
+        if (!force && now - lastCaptureTime.current < THROTTLE_MS)
+            return;
+        // Always check delta — no point re-capturing the same position
+        if (Math.abs(state.offsetY - lastCaptureY.current) < MIN_DELTA_PX &&
+            initialCaptured.current)
+            return;
+        lastCaptureTime.current = now;
+        lastCaptureY.current = state.offsetY;
+        initialCaptured.current = true;
+        try {
+            const windowHeight = react_native_1.Dimensions.get('window').height;
+            client_1.AppAnalytics.getInstance().captureScrollTile(state.offsetY, state.viewportHeight, state.contentHeight, lastViewportTop.current ?? undefined, windowHeight);
+        }
+        catch { }
+    };
+    /** Stop the continuous-scroll interval timer. */
+    const stopScrollInterval = () => {
+        if (scrollIntervalTimer.current !== null) {
+            clearInterval(scrollIntervalTimer.current);
+            scrollIntervalTimer.current = null;
+        }
+    };
+    /**
+     * Start the interval timer for continuous scroll captures. Self-stops
+     * when scroll events stop arriving (programmatic scrolls never fire the
+     * drag/momentum end events that would stop it otherwise).
+     */
+    const startScrollInterval = () => {
+        if (scrollIntervalTimer.current !== null)
+            return;
+        scrollIntervalTimer.current = setInterval(() => {
+            if (Date.now() - lastScrollEventAt.current > INTERVAL_IDLE_STOP_MS) {
+                stopScrollInterval();
+                return;
+            }
+            doCapture(true); // force=true skips throttle
+        }, SCROLL_INTERVAL_MS);
+    };
+    const onScroll = (0, react_1.useCallback)((event) => {
+        const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
+        lastScrollEventAt.current = Date.now();
+        // Update SDK with current scroll offset (both legacy + new registry)
+        try {
+            const sdk = client_1.AppAnalytics.getInstance();
+            sdk.setScrollOffset(contentOffset.y);
+            sdk.updateScrollViewOffset(scrollViewId.current, contentOffset.y);
+        }
+        catch { }
+        // Re-measure bounds occasionally during scroll — catches layout
+        // shifts from animations, keyboard, orientation changes, etc.
+        const now = Date.now();
+        if (now - lastMeasureTime.current > REMEASURE_THROTTLE_MS) {
+            lastMeasureTime.current = now;
+            measureAndRegister();
+        }
+        // Update scroll state — use realContentHeight if available
+        const bestContentHeight = realContentHeight.current > 0
+            ? realContentHeight.current
+            : contentSize.height;
+        scrollState.current = {
+            offsetY: contentOffset.y,
+            viewportHeight: layoutMeasurement.height,
+            contentHeight: bestContentHeight,
+        };
+        // Debounce: capture after scroll stops
+        if (debounceTimer.current)
+            clearTimeout(debounceTimer.current);
+        debounceTimer.current = setTimeout(() => doCapture(), DEBOUNCE_MS);
+        // Start interval for continuous scroll captures
+        startScrollInterval();
+        // Capture initial tile (Y~0) on first scroll event with real dims
+        if (!initialCaptured.current && contentOffset.y < 10) {
+            if (initialLayoutTimer.current)
+                clearTimeout(initialLayoutTimer.current);
+            initialLayoutTimer.current = setTimeout(() => doCapture(), 200);
+        }
+        handlersRef.current.onScroll?.(event);
+    }, [measureAndRegister]);
+    const onScrollEndDrag = (0, react_1.useCallback)((event) => {
+        // User lifted finger — capture immediately
+        stopScrollInterval();
+        doCapture(true);
+        handlersRef.current.onScrollEndDrag?.(event);
+    }, []);
+    const onMomentumScrollEnd = (0, react_1.useCallback)((event) => {
+        if (debounceTimer.current) {
+            clearTimeout(debounceTimer.current);
+            debounceTimer.current = null;
+        }
+        stopScrollInterval();
+        doCapture(true);
+        handlersRef.current.onMomentumScrollEnd?.(event);
+    }, []);
+    const onLayout = (0, react_1.useCallback)((event) => {
+        const { height } = event.nativeEvent.layout;
+        if (!initialCaptured.current && height > 0) {
+            scrollState.current = {
+                offsetY: 0,
+                viewportHeight: height,
+                contentHeight: realContentHeight.current || height,
+            };
+            // Clear any prior pending initial-capture timer before scheduling
+            if (initialLayoutTimer.current)
+                clearTimeout(initialLayoutTimer.current);
+            initialLayoutTimer.current = setTimeout(() => doCapture(), 1000);
+        }
+        // Register window-relative bounds immediately (no setTimeout).
+        // measureInWindow itself is async; if it returns 0/0 dims, the
+        // next onLayout / onScroll will retry — no race window.
+        measureAndRegister();
+        handlersRef.current.onLayout?.(event);
+    }, [measureAndRegister]);
+    /**
+     * Track the real content height from onContentSizeChange.
+     * This is more reliable than the first scroll event and ensures
+     * the initial tile at Y=0 has correct contentHeight metadata.
+     */
+    const onContentSizeChange = (0, react_1.useCallback)((w, h) => {
+        realContentHeight.current = h;
+        // Update scroll state if it exists
+        if (scrollState.current) {
+            scrollState.current.contentHeight = h;
+        }
+        handlersRef.current.onContentSizeChange?.(w, h);
+    }, []);
+    return {
+        setRef,
+        onScroll,
+        onScrollEndDrag,
+        onMomentumScrollEnd,
+        onLayout,
+        onContentSizeChange,
+    };
+}

package/dist/core/client.d.ts

@@ -14,6 +14,18 @@ export declare class AppAnalytics {
     private scrollOffsetY;
     private logger;
     private appStateSubscription;
+    /**
+     * User identity set via identify(). Kept for the process lifetime and
+     * automatically re-attached to every new session, so the host app only
+     * needs to call identify() once (e.g. after login).
+     */
+    private identity;
+    /**
+     * Offline persistence backend (AsyncStorage-compatible). Null when the
+     * host app neither passed one nor has AsyncStorage installed — the SDK
+     * then behaves exactly as before (in-memory buffering only).
+     */
+    private storage;
     /**
      * Registry of active ScrollViews on the current screen.
      * Each RepliqoScrollView registers its window-relative bounds and current
@@ -49,6 +61,21 @@ export declare class AppAnalytics {
     trackTouch(x: number, y: number, screenName?: string, extra?: Record<string, any>): void;
     trackNavigation(fromScreen: string, toScreen: string): void;
     trackCustomEvent(eventName: string, data?: Record<string, any>): void;
+    /**
+     * Identify the current user (call once after login). The identity is
+     * attached to the active session immediately and re-attached to every
+     * future session automatically until resetIdentity() is called.
+     *
+     * @param userId The host app's own user identifier.
+     * @param traits Optional free-form traits (plan, role, locale...).
+     *               Avoid PII you don't want stored (emails in plain text).
+     */
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Clear the stored identity (call on logout). Sessions started after
+     * this are anonymous again; already-identified sessions keep their user.
+     */
+    resetIdentity(): void;
     reportError(error: Error, metadata?: Record<string, any>): void;
     /**
      * Update the current scroll offset. Called by RepliqoScrollView
@@ -109,5 +136,30 @@ export declare class AppAnalytics {
     startSnapshotCapture(): void;
     stopSnapshotCapture(): void;
     isInitialized(): boolean;
+    /**
+     * Persist the un-flushed event buffer (called when backgrounding).
+     * Events carry their __sessionId stamp, so on restore they are still
+     * attributed to the session they belonged to.
+     */
+    private persistPendingEvents;
+    /**
+     * Serialization chain for pending-crash read-modify-write operations.
+     * Two near-simultaneous crashes (e.g. an error cascade) would otherwise
+     * interleave getItem/setItem and lose one of the entries.
+     */
+    private crashStoreLock;
+    private withCrashStoreLock;
+    /** Monotonic suffix so identical crashes get distinct keys. */
+    private crashSeq;
+    /** Append a crash to the persisted pending list; returns its key. */
+    private persistCrash;
+    /** Remove a crash from the persisted pending list (after send success). */
+    private removePendingCrash;
+    /**
+     * Restore data persisted by a previous run: re-enqueue events (still
+     * stamped with their original session) and re-send pending crashes.
+     * Called once from the constructor.
+     */
+    private restorePersistedData;
     private setupAppStateListener;
 }