@repliqo/sdk-react-native 0.1.3 → 0.2.1

package/android/src/main/java/com/repliqo/screencapture/FullContentCapture.java

@@ -0,0 +1,258 @@
+package com.repliqo.screencapture;
+
+import android.app.Activity;
+import android.graphics.Bitmap;
+import android.graphics.Canvas;
+import android.util.Base64;
+import android.util.Log;
+import android.view.View;
+import android.view.ViewGroup;
+import android.widget.ScrollView;
+
+import java.io.ByteArrayOutputStream;
+import java.lang.reflect.Field;
+import java.util.ArrayList;
+
+/**
+ * Captures the FULL content of the primary vertical ScrollView found in
+ * the app's view hierarchy — including content scrolled off-screen.
+ *
+ * Used for heatmap backgrounds where we need the complete screen layout,
+ * not just the visible viewport.
+ *
+ * Supports:
+ *  - Android ScrollView
+ *  - AndroidX NestedScrollView
+ *  - React Native ReactScrollView (old arch)
+ *  - React Native ReactScrollViewManager (Fabric / new arch)
+ *
+ * Known limitation: FlatList / SectionList use RecyclerView which only
+ * renders visible items. Full-content capture is not possible for those.
+ * The method falls back to a viewport capture in that case.
+ *
+ * No permissions needed. Runs on UI thread.
+ */
+public class FullContentCapture {
+    private static final String TAG = "RepliqoCapture";
+    private static final int TARGET_WIDTH = 500;
+    private static final int JPEG_QUALITY = 60;
+    private static final int MAX_HEIGHT = 5000;
+
+    /** Result that includes whether this is a full-content or viewport capture. */
+    public static class FullCaptureResult {
+        public final String image;
+        public final int width;
+        public final int height;
+        public final boolean isFullContent;
+
+        FullCaptureResult(String image, int width, int height, boolean isFullContent) {
+            this.image = image;
+            this.width = width;
+            this.height = height;
+            this.isFullContent = isFullContent;
+        }
+    }
+
+    /**
+     * Capture the full content of the primary vertical ScrollView.
+     * Falls back to viewport capture if no suitable ScrollView is found.
+     *
+     * @param activity Current activity
+     * @return FullCaptureResult with isFullContent flag
+     */
+    public static FullCaptureResult capture(Activity activity) {
+        if (activity == null || activity.isFinishing()) return null;
+
+        try {
+            // Find the primary vertical ScrollView
+            View scrollView = findVerticalScrollView(activity);
+            if (scrollView == null) {
+                Log.d(TAG, "No vertical ScrollView found, falling back to viewport");
+                return viewportFallback(activity);
+            }
+
+            // Get the content child
+            View contentView = getContentChild(scrollView);
+            if (contentView == null) {
+                return viewportFallback(activity);
+            }
+
+            int contentWidth = contentView.getWidth();
+            int contentHeight = contentView.getHeight();
+
+            if (contentWidth <= 0 || contentHeight <= 0) {
+                return viewportFallback(activity);
+            }
+
+            // If content height is same as viewport, it's not scrollable
+            int viewportHeight = scrollView.getHeight();
+            if (contentHeight <= viewportHeight) {
+                Log.d(TAG, "Content fits in viewport, no scroll needed");
+                return viewportFallback(activity);
+            }
+
+            // Cap height to avoid OOM
+            int captureHeight = Math.min(contentHeight, MAX_HEIGHT);
+
+            // Scale to output dimensions
+            float scale = (float) TARGET_WIDTH / contentWidth;
+            int outWidth = TARGET_WIDTH & ~1;
+            int outHeight = Math.round(captureHeight * scale) & ~1;
+
+            if (outWidth <= 0 || outHeight <= 0) {
+                return viewportFallback(activity);
+            }
+
+            // Create bitmap — wrapped in OOM catch
+            Bitmap bitmap;
+            try {
+                bitmap = Bitmap.createBitmap(outWidth, outHeight,
+                        Bitmap.Config.ARGB_8888);
+            } catch (OutOfMemoryError oom) {
+                Log.w(TAG, "OOM creating bitmap " + outWidth + "x" + outHeight +
+                        ", falling back to viewport");
+                return viewportFallback(activity);
+            }
+
+            Canvas canvas = new Canvas(bitmap);
+            canvas.scale(scale, scale);
+
+            // Draw the full content
+            contentView.draw(canvas);
+
+            // Compress to JPEG
+            ByteArrayOutputStream baos = new ByteArrayOutputStream();
+            bitmap.compress(Bitmap.CompressFormat.JPEG, JPEG_QUALITY, baos);
+            String base64 = Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP);
+            bitmap.recycle();
+
+            Log.d(TAG, "Full content captured: " + outWidth + "x" + outHeight +
+                    " (content: " + contentWidth + "x" + contentHeight +
+                    ", viewport: " + contentWidth + "x" + viewportHeight + ")");
+
+            return new FullCaptureResult(base64, outWidth, outHeight, true);
+
+        } catch (Exception e) {
+            Log.w(TAG, "FullContentCapture failed: " + e.getMessage());
+            return viewportFallback(activity);
+        }
+    }
+
+    /**
+     * Fallback: capture just the visible viewport via MultiWindowCapture.
+     */
+    private static FullCaptureResult viewportFallback(Activity activity) {
+        MultiWindowCapture.CaptureResult vp = MultiWindowCapture.capture(activity);
+        if (vp == null) return null;
+        return new FullCaptureResult(vp.image, vp.width, vp.height, false);
+    }
+
+    /**
+     * Find the first VERTICAL ScrollView in the view hierarchy.
+     * Searches all root views (including modals).
+     *
+     * Matches by walking the class hierarchy for known scroll classes:
+     *  - android.widget.ScrollView
+     *  - androidx.core.widget.NestedScrollView
+     *  - com.facebook.react.views.scroll.ReactScrollView (old arch)
+     *  - Any class with "ScrollView" in the name (catches Fabric variants)
+     *
+     * Explicitly SKIPS HorizontalScrollView and classes containing
+     * "Horizontal" to avoid capturing carousels.
+     */
+    private static View findVerticalScrollView(Activity activity) {
+        View decorView = activity.getWindow().getDecorView();
+        View found = findVerticalScrollInTree(decorView);
+        if (found != null) return found;
+
+        // Check other windows (modals)
+        try {
+            Class<?> wmgClass = Class.forName("android.view.WindowManagerGlobal");
+            Object wmg = wmgClass.getMethod("getInstance").invoke(null);
+            Field viewsField = wmgClass.getDeclaredField("mViews");
+            viewsField.setAccessible(true);
+            @SuppressWarnings("unchecked")
+            ArrayList<View> views = (ArrayList<View>) viewsField.get(wmg);
+            if (views != null) {
+                for (View root : views) {
+                    if (root == decorView) continue;
+                    found = findVerticalScrollInTree(root);
+                    if (found != null) return found;
+                }
+            }
+        } catch (Exception e) {
+            // Reflection failed
+        }
+
+        return null;
+    }
+
+    /**
+     * DFS for a vertical scroll view in the tree.
+     */
+    private static View findVerticalScrollInTree(View view) {
+        if (view == null) return null;
+
+        if (isVerticalScrollView(view)) {
+            if (view instanceof ViewGroup && ((ViewGroup) view).getChildCount() > 0) {
+                return view;
+            }
+        }
+
+        if (view instanceof ViewGroup) {
+            ViewGroup group = (ViewGroup) view;
+            for (int i = 0; i < group.getChildCount(); i++) {
+                View found = findVerticalScrollInTree(group.getChildAt(i));
+                if (found != null) return found;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Check if a view is a vertical scroll view.
+     * Walks the class hierarchy to catch subclasses.
+     */
+    private static boolean isVerticalScrollView(View view) {
+        // Direct instanceof for standard Android ScrollView
+        if (view instanceof ScrollView) return true;
+
+        // Walk class hierarchy for name-based matching
+        Class<?> clazz = view.getClass();
+        while (clazz != null && clazz != View.class) {
+            String name = clazz.getName();
+
+            // Skip horizontal variants
+            if (name.contains("Horizontal")) return false;
+
+            // Match known vertical scroll classes:
+            // - androidx.core.widget.NestedScrollView
+            // - com.facebook.react.views.scroll.ReactScrollView (old arch)
+            // - com.facebook.react.views.scroll.ReactScrollViewManager$... (Fabric)
+            // - Any other class ending in "ScrollView" that isn't horizontal
+            if (name.contains("NestedScrollView") ||
+                name.contains("ReactScrollView") ||
+                (name.endsWith("ScrollView") && !name.contains("Horizontal"))) {
+                return true;
+            }
+
+            clazz = clazz.getSuperclass();
+        }
+
+        return false;
+    }
+
+    /**
+     * Get the content child of a ScrollView.
+     */
+    private static View getContentChild(View scrollView) {
+        if (scrollView instanceof ViewGroup) {
+            ViewGroup group = (ViewGroup) scrollView;
+            if (group.getChildCount() > 0) {
+                return group.getChildAt(0);
+            }
+        }
+        return null;
+    }
+}

package/android/src/main/java/com/repliqo/screencapture/ScreenCaptureModule.java

@@ -91,4 +91,45 @@ public class ScreenCaptureModule extends ReactContextBaseJavaModule {
             }
         });
     }
+
+    /**
+     * Capture the FULL content of the primary ScrollView on screen,
+     * including content that is scrolled off-screen.
+     *
+     * Used for heatmap backgrounds. Falls back to a viewport capture
+     * if no ScrollView is found.
+     *
+     * Returns: { image: base64, width: int, height: int, format: "jpeg" }
+     */
+    @ReactMethod
+    public void captureFullContent(Promise promise) {
+        Activity activity = getCurrentActivity();
+        if (activity == null) {
+            promise.resolve(null);
+            return;
+        }
+
+        mainHandler.post(() -> {
+            try {
+                FullContentCapture.FullCaptureResult result =
+                        FullContentCapture.capture(activity);
+
+                if (result == null) {
+                    promise.resolve(null);
+                    return;
+                }
+
+                WritableMap map = Arguments.createMap();
+                map.putString("image", result.image);
+                map.putInt("width", result.width);
+                map.putInt("height", result.height);
+                map.putString("format", "jpeg");
+                map.putBoolean("isFullContent", result.isFullContent);
+                promise.resolve(map);
+            } catch (Exception e) {
+                Log.w(TAG, "captureFullContent failed: " + e.getMessage());
+                promise.resolve(null);
+            }
+        });
+    }
 }

package/dist/core/client.d.ts

@@ -7,6 +7,7 @@ export declare class AppAnalytics {
     private screenVisitQueue;
     private snapshotQueue;
     private snapshotCapture;
+    private screenCaptureManager;
     private errorTracker;
     private sessionId;
     private currentScreen;

package/dist/core/client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppAnalytics = void 0;
 const react_native_1 = require("react-native");
 const capture_1 = require("../snapshot/capture");
+const ScreenCaptureManager_1 = require("../snapshot/ScreenCaptureManager");
 const config_1 = require("./config");
 const logger_1 = require("./logger");
 const api_client_1 = require("../transport/api.client");
@@ -13,6 +14,7 @@ const error_tracker_1 = require("../trackers/error.tracker");
 class AppAnalytics {
     constructor(config) {
         this.snapshotCapture = null;
+        this.screenCaptureManager = null;
         this.errorTracker = null;
         this.sessionId = null;
         this.currentScreen = null;
@@ -50,6 +52,12 @@ class AppAnalytics {
             }, undefined, // default captureScreenshot provider
             (...args) => this.logger.log(...args), (...args) => this.logger.warn(...args));
         }
+        // Screen capture manager for heatmap backgrounds.
+        // Captures full ScrollView content on screen enter (24h cache).
+        // Independent of session replay snapshots.
+        if (this.config.enableHeatmapCapture) {
+            this.screenCaptureManager = new ScreenCaptureManager_1.ScreenCaptureManager((screenName, image, width, height, isFullContent) => this.apiClient.uploadScreenCapture(screenName, image, width, height, isFullContent), this.config.debug);
+        }
         if (this.config.enableCrashTracking) {
             this.errorTracker = new error_tracker_1.ErrorTracker((crash) => {
                 // Crash reports are sent immediately (fire-and-forget), not batched
@@ -94,6 +102,8 @@ class AppAnalytics {
                 instance.snapshotCapture.stop();
                 instance.snapshotCapture = null;
             }
+            instance.screenCaptureManager?.reset();
+            instance.screenCaptureManager = null;
             instance.eventQueue.stopAutoFlush();
             instance.screenVisitQueue.stopAutoFlush();
             instance.snapshotQueue.stopAutoFlush();
@@ -227,9 +237,11 @@ class AppAnalytics {
     onScreenEnter(screenName) {
         this.currentScreen = screenName;
         this.currentScreenEnteredAt = new Date().toISOString();
-        this.scrollOffsetY = 0; // Reset scroll on screen change
+        this.scrollOffsetY = 0;
         this.errorTracker?.setCurrentScreen(screenName);
         this.snapshotCapture?.setCurrentScreen(screenName);
+        // Trigger full-content capture for heatmap backgrounds (async, non-blocking)
+        this.screenCaptureManager?.onScreenEnter(screenName);
         this.logger.log('Screen entered:', screenName);
     }
     onScreenExit(screenName) {

package/dist/core/config.js

@@ -19,6 +19,7 @@ exports.DEFAULT_CONFIG = {
     snapshotFlushInterval: 15000,
     // ~32 * 30KB ≈ 1 MB cap on in-memory buffer if the backend is down.
     snapshotMaxBufferSize: 32,
+    enableHeatmapCapture: true,
     enableCrashTracking: true,
     debug: false,
 };

package/dist/index.d.ts

@@ -5,7 +5,8 @@ export { trackScreenEnter, trackScreenExit, } from './trackers/screen.tracker';
 export { ErrorTracker } from './trackers/error.tracker';
 export { SnapshotCapture } from './snapshot/capture';
 export { captureScreenshot } from './snapshot/captureScreenshot';
-export { isNativeScreenCaptureAvailable, captureNativeFrame, } from './snapshot/NativeScreenCapture';
+export { isNativeScreenCaptureAvailable, captureNativeFrame, captureFullContent, } from './snapshot/NativeScreenCapture';
+export type { FullContentResult } from './snapshot/NativeScreenCapture';
 export type { EventType, AnalyticsEvent, TouchEventData, NavigationEventData, ScreenVisit, DeviceInfo, SDKConfig, } from './types/events';
 export type { ScreenshotData, SnapshotPayload, } from './types/snapshot';
 export type { CrashReport } from './types/crash';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CONFIG = exports.RepliqoScrollView = exports.captureNativeFrame = exports.isNativeScreenCaptureAvailable = exports.captureScreenshot = exports.SnapshotCapture = exports.ErrorTracker = exports.trackScreenExit = exports.trackScreenEnter = exports.trackScreenChange = exports.useNavigationTracker = exports.TouchTracker = exports.AppAnalytics = void 0;
+exports.DEFAULT_CONFIG = exports.RepliqoScrollView = exports.captureFullContent = exports.captureNativeFrame = exports.isNativeScreenCaptureAvailable = exports.captureScreenshot = exports.SnapshotCapture = exports.ErrorTracker = exports.trackScreenExit = exports.trackScreenEnter = exports.trackScreenChange = exports.useNavigationTracker = exports.TouchTracker = exports.AppAnalytics = void 0;
 // Main class
 var client_1 = require("./core/client");
 Object.defineProperty(exports, "AppAnalytics", { enumerable: true, get: function () { return client_1.AppAnalytics; } });
@@ -23,6 +23,7 @@ Object.defineProperty(exports, "captureScreenshot", { enumerable: true, get: fun
 var NativeScreenCapture_1 = require("./snapshot/NativeScreenCapture");
 Object.defineProperty(exports, "isNativeScreenCaptureAvailable", { enumerable: true, get: function () { return NativeScreenCapture_1.isNativeScreenCaptureAvailable; } });
 Object.defineProperty(exports, "captureNativeFrame", { enumerable: true, get: function () { return NativeScreenCapture_1.captureNativeFrame; } });
+Object.defineProperty(exports, "captureFullContent", { enumerable: true, get: function () { return NativeScreenCapture_1.captureFullContent; } });
 // Components
 var RepliqoScrollView_1 = require("./components/RepliqoScrollView");
 Object.defineProperty(exports, "RepliqoScrollView", { enumerable: true, get: function () { return RepliqoScrollView_1.RepliqoScrollView; } });

package/dist/snapshot/NativeScreenCapture.d.ts

@@ -15,3 +15,29 @@ export declare function isNativeScreenCaptureAvailable(): boolean;
  * @returns NativeFrameResult or null if capture failed / not available
  */
 export declare function captureNativeFrame(): Promise<NativeFrameResult | null>;
+/**
+ * Capture the FULL content of the primary ScrollView on screen,
+ * including content scrolled off-screen. Used for heatmap backgrounds.
+ *
+ * Falls back to a viewport capture if no ScrollView is found.
+ * Max height: 5000px. JPEG quality: 60%. Width: ~500px.
+ *
+ * @returns NativeFrameResult or null if capture failed / not available
+ */
+export interface FullContentResult extends NativeFrameResult {
+    /** True if the capture includes full scrollable content. False if viewport-only fallback. */
+    isFullContent: boolean;
+}
+/**
+ * Capture the FULL content of the primary ScrollView on screen,
+ * including content scrolled off-screen. Used for heatmap backgrounds.
+ *
+ * Falls back to a viewport capture if no ScrollView is found.
+ * Max height: 5000px. JPEG quality: 60%. Width: ~500px.
+ *
+ * Known limitation: FlatList/SectionList use RecyclerView which only
+ * renders visible items — full-content capture falls back to viewport.
+ *
+ * @returns FullContentResult with isFullContent flag, or null
+ */
+export declare function captureFullContent(): Promise<FullContentResult | null>;

package/dist/snapshot/NativeScreenCapture.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isNativeScreenCaptureAvailable = isNativeScreenCaptureAvailable;
 exports.captureNativeFrame = captureNativeFrame;
+exports.captureFullContent = captureFullContent;
 const react_native_1 = require("react-native");
 const NativeModule = react_native_1.Platform.OS === 'android'
     ? react_native_1.NativeModules.ScreenCaptureModule ?? null
@@ -36,3 +37,34 @@ async function captureNativeFrame() {
         return null;
     }
 }
+/**
+ * Capture the FULL content of the primary ScrollView on screen,
+ * including content scrolled off-screen. Used for heatmap backgrounds.
+ *
+ * Falls back to a viewport capture if no ScrollView is found.
+ * Max height: 5000px. JPEG quality: 60%. Width: ~500px.
+ *
+ * Known limitation: FlatList/SectionList use RecyclerView which only
+ * renders visible items — full-content capture falls back to viewport.
+ *
+ * @returns FullContentResult with isFullContent flag, or null
+ */
+async function captureFullContent() {
+    if (!NativeModule)
+        return null;
+    try {
+        const result = await NativeModule.captureFullContent();
+        if (!result || !result.image)
+            return null;
+        return {
+            image: result.image,
+            width: result.width,
+            height: result.height,
+            format: 'jpeg',
+            isFullContent: !!result.isFullContent,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/snapshot/ScreenCaptureManager.d.ts

@@ -0,0 +1,30 @@
+export type UploadFn = (screenName: string, image: string, width: number, height: number, isFullContent: boolean) => Promise<void>;
+/**
+ * Manages full-content screen captures for heatmap backgrounds.
+ *
+ * - Captures the full ScrollView content on screen enter
+ * - Local cache with 24h TTL to avoid redundant captures
+ * - Cancels pending captures when navigating away (prevents cross-screen bugs)
+ * - Async and non-blocking: never delays navigation or crashes the app
+ */
+export declare class ScreenCaptureManager {
+    private cache;
+    private pending;
+    private pendingTimer;
+    private currentScreen;
+    private uploadFn;
+    private debug;
+    constructor(uploadFn: UploadFn, debug?: boolean);
+    /**
+     * Called when the user enters a screen. Schedules a full-content
+     * capture after a delay if no recent capture exists.
+     *
+     * Cancels any pending capture from a previous screen to prevent
+     * cross-screen data corruption (capturing screen B but labeling as A).
+     */
+    onScreenEnter(screenName: string): void;
+    private shouldCapture;
+    private captureAndUpload;
+    private cancelPending;
+    reset(): void;
+}

package/dist/snapshot/ScreenCaptureManager.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScreenCaptureManager = void 0;
+const NativeScreenCapture_1 = require("./NativeScreenCapture");
+/** 24 hours in milliseconds. */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/** Wait for screen to render before capturing. */
+const RENDER_DELAY_MS = 800;
+/** Max base64 size to upload (3MB base64 ≈ ~2.2MB binary). */
+const MAX_IMAGE_SIZE = 3 * 1024 * 1024;
+/**
+ * Manages full-content screen captures for heatmap backgrounds.
+ *
+ * - Captures the full ScrollView content on screen enter
+ * - Local cache with 24h TTL to avoid redundant captures
+ * - Cancels pending captures when navigating away (prevents cross-screen bugs)
+ * - Async and non-blocking: never delays navigation or crashes the app
+ */
+class ScreenCaptureManager {
+    constructor(uploadFn, debug = false) {
+        this.cache = new Map();
+        this.pending = new Set();
+        this.pendingTimer = null;
+        this.currentScreen = null;
+        this.uploadFn = uploadFn;
+        this.debug = debug;
+    }
+    /**
+     * Called when the user enters a screen. Schedules a full-content
+     * capture after a delay if no recent capture exists.
+     *
+     * Cancels any pending capture from a previous screen to prevent
+     * cross-screen data corruption (capturing screen B but labeling as A).
+     */
+    onScreenEnter(screenName) {
+        // Cancel any pending capture from the previous screen
+        this.cancelPending();
+        this.currentScreen = screenName;
+        if (!this.shouldCapture(screenName))
+            return;
+        this.pending.add(screenName);
+        this.pendingTimer = setTimeout(() => {
+            this.pendingTimer = null;
+            // Verify the user is STILL on this screen before capturing
+            if (this.currentScreen !== screenName) {
+                this.pending.delete(screenName);
+                if (this.debug) {
+                    console.log(`[Repliqo] Screen capture skipped: navigated away from "${screenName}"`);
+                }
+                return;
+            }
+            this.captureAndUpload(screenName).catch(() => { });
+        }, RENDER_DELAY_MS);
+    }
+    shouldCapture(screenName) {
+        if (this.pending.has(screenName))
+            return false;
+        const lastCapture = this.cache.get(screenName);
+        if (lastCapture && Date.now() - lastCapture < CACHE_TTL_MS) {
+            return false;
+        }
+        return true;
+    }
+    async captureAndUpload(screenName) {
+        try {
+            const result = await (0, NativeScreenCapture_1.captureFullContent)();
+            if (!result) {
+                if (this.debug) {
+                    console.log(`[Repliqo] Screen capture returned null for "${screenName}"`);
+                }
+                return;
+            }
+            // Guard: check we're still on the same screen after the async capture
+            if (this.currentScreen !== screenName) {
+                if (this.debug) {
+                    console.log(`[Repliqo] Screen capture discarded: user left "${screenName}" during capture`);
+                }
+                return;
+            }
+            // Guard: reject oversized images to prevent OOM during upload
+            if (result.image.length > MAX_IMAGE_SIZE) {
+                if (this.debug) {
+                    console.warn(`[Repliqo] Screen capture too large (${Math.round(result.image.length / 1024)}KB), skipping "${screenName}"`);
+                }
+                return;
+            }
+            if (this.debug) {
+                console.log(`[Repliqo] Screen captured: "${screenName}" ${result.width}x${result.height} ` +
+                    `(full=${result.isFullContent}, ${Math.round(result.image.length / 1024)}KB)`);
+            }
+            await this.uploadFn(screenName, result.image, result.width, result.height, result.isFullContent);
+            this.cache.set(screenName, Date.now());
+            if (this.debug) {
+                console.log(`[Repliqo] Screen capture uploaded: "${screenName}"`);
+            }
+        }
+        catch (err) {
+            if (this.debug) {
+                console.warn(`[Repliqo] Screen capture failed for "${screenName}":`, err);
+            }
+        }
+        finally {
+            this.pending.delete(screenName);
+        }
+    }
+    cancelPending() {
+        if (this.pendingTimer !== null) {
+            clearTimeout(this.pendingTimer);
+            this.pendingTimer = null;
+        }
+    }
+    reset() {
+        this.cancelPending();
+        this.cache.clear();
+        this.pending.clear();
+        this.currentScreen = null;
+    }
+}
+exports.ScreenCaptureManager = ScreenCaptureManager;

package/dist/transport/api.client.d.ts

@@ -26,4 +26,9 @@ export declare class ApiClient {
     sendCrashesBatch(crashes: CrashReport[]): Promise<{
         count: number;
     }>;
+    /**
+     * Upload a full-content screen capture for heatmap backgrounds.
+     * Fire-and-forget: errors are logged but never thrown.
+     */
+    uploadScreenCapture(screenName: string, image: string, width: number, height: number, isFullContent: boolean): Promise<void>;
 }

package/dist/transport/api.client.js

@@ -152,5 +152,31 @@ class ApiClient {
             throw error;
         }
     }
+    /**
+     * Upload a full-content screen capture for heatmap backgrounds.
+     * Fire-and-forget: errors are logged but never thrown.
+     */
+    async uploadScreenCapture(screenName, image, width, height, isFullContent) {
+        try {
+            const response = await fetch(`${this.baseUrl}/api/screen-captures`, {
+                method: 'POST',
+                headers: this.getHeaders(),
+                body: JSON.stringify({
+                    screenName,
+                    image,
+                    width,
+                    height,
+                    isFullContent,
+                }),
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                this.logger.warn('Screen capture upload failed:', response.status, text?.substring(0, 200));
+            }
+        }
+        catch (error) {
+            this.logger.warn('Error uploading screen capture:', error);
+        }
+    }
 }
 exports.ApiClient = ApiClient;

package/dist/types/events.d.ts

@@ -47,6 +47,8 @@ export interface SDKConfig {
     snapshotFlushInterval?: number;
     /** Max snapshots kept in memory if the backend is unreachable. Defaults to 32. */
     snapshotMaxBufferSize?: number;
+    /** Enable full-content screen captures for heatmap backgrounds. Defaults to true when enableSnapshots is true. */
+    enableHeatmapCapture?: boolean;
     enableCrashTracking?: boolean;
     debug?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repliqo/sdk-react-native",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Session replay & analytics SDK for React Native. Captures screenshots (including modals/alerts), navigation, screen visits, and custom events.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core/client.ts

@@ -7,6 +7,7 @@ import {
 } from '../types/events';
 import { SnapshotPayload } from '../types/snapshot';
 import { SnapshotCapture } from '../snapshot/capture';
+import { ScreenCaptureManager } from '../snapshot/ScreenCaptureManager';
 import { ResolvedConfig, resolveConfig, REPLIQO_API_URL } from './config';
 import { Logger } from './logger';
 import { ApiClient } from '../transport/api.client';
@@ -24,6 +25,7 @@ export class AppAnalytics {
   private screenVisitQueue: BatchQueue<ScreenVisit>;
   private snapshotQueue: BatchQueue<SnapshotPayload>;
   private snapshotCapture: SnapshotCapture | null = null;
+  private screenCaptureManager: ScreenCaptureManager | null = null;
   private errorTracker: ErrorTracker | null = null;
   private sessionId: string | null = null;
   private currentScreen: string | null = null;
@@ -94,6 +96,19 @@ export class AppAnalytics {
       );
     }
 
+    // Screen capture manager for heatmap backgrounds.
+    // Captures full ScrollView content on screen enter (24h cache).
+    // Independent of session replay snapshots.
+    if (this.config.enableHeatmapCapture) {
+      this.screenCaptureManager = new ScreenCaptureManager(
+        (screenName, image, width, height, isFullContent) =>
+          this.apiClient.uploadScreenCapture(
+            screenName, image, width, height, isFullContent,
+          ),
+        this.config.debug,
+      );
+    }
+
     if (this.config.enableCrashTracking) {
       this.errorTracker = new ErrorTracker((crash) => {
         // Crash reports are sent immediately (fire-and-forget), not batched
@@ -151,6 +166,8 @@ export class AppAnalytics {
         instance.snapshotCapture = null;
       }
 
+      instance.screenCaptureManager?.reset();
+      instance.screenCaptureManager = null;
 
       instance.eventQueue.stopAutoFlush();
       instance.screenVisitQueue.stopAutoFlush();
@@ -325,9 +342,11 @@ export class AppAnalytics {
   onScreenEnter(screenName: string): void {
     this.currentScreen = screenName;
     this.currentScreenEnteredAt = new Date().toISOString();
-    this.scrollOffsetY = 0; // Reset scroll on screen change
+    this.scrollOffsetY = 0;
     this.errorTracker?.setCurrentScreen(screenName);
     this.snapshotCapture?.setCurrentScreen(screenName);
+    // Trigger full-content capture for heatmap backgrounds (async, non-blocking)
+    this.screenCaptureManager?.onScreenEnter(screenName);
     this.logger.log('Screen entered:', screenName);
   }
 

package/src/core/config.ts

@@ -18,6 +18,7 @@ export const DEFAULT_CONFIG: Required<Omit<SDKConfig, 'apiKey' | 'appId'>> = {
   snapshotFlushInterval: 15000,
   // ~32 * 30KB ≈ 1 MB cap on in-memory buffer if the backend is down.
   snapshotMaxBufferSize: 32,
+  enableHeatmapCapture: true,
   enableCrashTracking: true,
   debug: false,
 };

package/src/index.ts

@@ -19,7 +19,9 @@ export { captureScreenshot } from './snapshot/captureScreenshot';
 export {
   isNativeScreenCaptureAvailable,
   captureNativeFrame,
+  captureFullContent,
 } from './snapshot/NativeScreenCapture';
+export type { FullContentResult } from './snapshot/NativeScreenCapture';
 
 // Types
 export type {

package/src/snapshot/NativeScreenCapture.ts

@@ -7,13 +7,20 @@ export interface NativeFrameResult {
   format: 'jpeg';
 }
 
+interface NativeCaptureResult {
+  image: string;
+  width: number;
+  height: number;
+  format: string;
+}
+
+interface NativeFullContentResult extends NativeCaptureResult {
+  isFullContent: boolean;
+}
+
 interface NativeScreenCaptureModule {
-  captureFrame(): Promise<{
-    image: string;
-    width: number;
-    height: number;
-    format: string;
-  } | null>;
+  captureFrame(): Promise<NativeCaptureResult | null>;
+  captureFullContent(): Promise<NativeFullContentResult | null>;
   isAvailable(): Promise<boolean>;
 }
 
@@ -52,3 +59,48 @@ export async function captureNativeFrame(): Promise<NativeFrameResult | null> {
     return null;
   }
 }
+
+/**
+ * Capture the FULL content of the primary ScrollView on screen,
+ * including content scrolled off-screen. Used for heatmap backgrounds.
+ *
+ * Falls back to a viewport capture if no ScrollView is found.
+ * Max height: 5000px. JPEG quality: 60%. Width: ~500px.
+ *
+ * @returns NativeFrameResult or null if capture failed / not available
+ */
+export interface FullContentResult extends NativeFrameResult {
+  /** True if the capture includes full scrollable content. False if viewport-only fallback. */
+  isFullContent: boolean;
+}
+
+/**
+ * Capture the FULL content of the primary ScrollView on screen,
+ * including content scrolled off-screen. Used for heatmap backgrounds.
+ *
+ * Falls back to a viewport capture if no ScrollView is found.
+ * Max height: 5000px. JPEG quality: 60%. Width: ~500px.
+ *
+ * Known limitation: FlatList/SectionList use RecyclerView which only
+ * renders visible items — full-content capture falls back to viewport.
+ *
+ * @returns FullContentResult with isFullContent flag, or null
+ */
+export async function captureFullContent(): Promise<FullContentResult | null> {
+  if (!NativeModule) return null;
+
+  try {
+    const result = await NativeModule.captureFullContent();
+    if (!result || !result.image) return null;
+
+    return {
+      image: result.image,
+      width: result.width,
+      height: result.height,
+      format: 'jpeg',
+      isFullContent: !!result.isFullContent,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/snapshot/ScreenCaptureManager.ts

@@ -0,0 +1,156 @@
+import { captureFullContent } from './NativeScreenCapture';
+
+/** 24 hours in milliseconds. */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Wait for screen to render before capturing. */
+const RENDER_DELAY_MS = 800;
+
+/** Max base64 size to upload (3MB base64 ≈ ~2.2MB binary). */
+const MAX_IMAGE_SIZE = 3 * 1024 * 1024;
+
+export type UploadFn = (
+  screenName: string,
+  image: string,
+  width: number,
+  height: number,
+  isFullContent: boolean,
+) => Promise<void>;
+
+/**
+ * Manages full-content screen captures for heatmap backgrounds.
+ *
+ * - Captures the full ScrollView content on screen enter
+ * - Local cache with 24h TTL to avoid redundant captures
+ * - Cancels pending captures when navigating away (prevents cross-screen bugs)
+ * - Async and non-blocking: never delays navigation or crashes the app
+ */
+export class ScreenCaptureManager {
+  private cache = new Map<string, number>();
+  private pending = new Set<string>();
+  private pendingTimer: ReturnType<typeof setTimeout> | null = null;
+  private currentScreen: string | null = null;
+  private uploadFn: UploadFn;
+  private debug: boolean;
+
+  constructor(uploadFn: UploadFn, debug = false) {
+    this.uploadFn = uploadFn;
+    this.debug = debug;
+  }
+
+  /**
+   * Called when the user enters a screen. Schedules a full-content
+   * capture after a delay if no recent capture exists.
+   *
+   * Cancels any pending capture from a previous screen to prevent
+   * cross-screen data corruption (capturing screen B but labeling as A).
+   */
+  onScreenEnter(screenName: string): void {
+    // Cancel any pending capture from the previous screen
+    this.cancelPending();
+    this.currentScreen = screenName;
+
+    if (!this.shouldCapture(screenName)) return;
+
+    this.pending.add(screenName);
+
+    this.pendingTimer = setTimeout(() => {
+      this.pendingTimer = null;
+      // Verify the user is STILL on this screen before capturing
+      if (this.currentScreen !== screenName) {
+        this.pending.delete(screenName);
+        if (this.debug) {
+          console.log(
+            `[Repliqo] Screen capture skipped: navigated away from "${screenName}"`,
+          );
+        }
+        return;
+      }
+      this.captureAndUpload(screenName).catch(() => {});
+    }, RENDER_DELAY_MS);
+  }
+
+  private shouldCapture(screenName: string): boolean {
+    if (this.pending.has(screenName)) return false;
+
+    const lastCapture = this.cache.get(screenName);
+    if (lastCapture && Date.now() - lastCapture < CACHE_TTL_MS) {
+      return false;
+    }
+
+    return true;
+  }
+
+  private async captureAndUpload(screenName: string): Promise<void> {
+    try {
+      const result = await captureFullContent();
+      if (!result) {
+        if (this.debug) {
+          console.log(`[Repliqo] Screen capture returned null for "${screenName}"`);
+        }
+        return;
+      }
+
+      // Guard: check we're still on the same screen after the async capture
+      if (this.currentScreen !== screenName) {
+        if (this.debug) {
+          console.log(
+            `[Repliqo] Screen capture discarded: user left "${screenName}" during capture`,
+          );
+        }
+        return;
+      }
+
+      // Guard: reject oversized images to prevent OOM during upload
+      if (result.image.length > MAX_IMAGE_SIZE) {
+        if (this.debug) {
+          console.warn(
+            `[Repliqo] Screen capture too large (${Math.round(result.image.length / 1024)}KB), skipping "${screenName}"`,
+          );
+        }
+        return;
+      }
+
+      if (this.debug) {
+        console.log(
+          `[Repliqo] Screen captured: "${screenName}" ${result.width}x${result.height} ` +
+            `(full=${result.isFullContent}, ${Math.round(result.image.length / 1024)}KB)`,
+        );
+      }
+
+      await this.uploadFn(
+        screenName,
+        result.image,
+        result.width,
+        result.height,
+        result.isFullContent,
+      );
+
+      this.cache.set(screenName, Date.now());
+
+      if (this.debug) {
+        console.log(`[Repliqo] Screen capture uploaded: "${screenName}"`);
+      }
+    } catch (err) {
+      if (this.debug) {
+        console.warn(`[Repliqo] Screen capture failed for "${screenName}":`, err);
+      }
+    } finally {
+      this.pending.delete(screenName);
+    }
+  }
+
+  private cancelPending(): void {
+    if (this.pendingTimer !== null) {
+      clearTimeout(this.pendingTimer);
+      this.pendingTimer = null;
+    }
+  }
+
+  reset(): void {
+    this.cancelPending();
+    this.cache.clear();
+    this.pending.clear();
+    this.currentScreen = null;
+  }
+}

package/src/transport/api.client.ts

@@ -222,4 +222,44 @@ export class ApiClient {
       throw error;
     }
   }
+
+  /**
+   * Upload a full-content screen capture for heatmap backgrounds.
+   * Fire-and-forget: errors are logged but never thrown.
+   */
+  async uploadScreenCapture(
+    screenName: string,
+    image: string,
+    width: number,
+    height: number,
+    isFullContent: boolean,
+  ): Promise<void> {
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/api/screen-captures`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify({
+            screenName,
+            image,
+            width,
+            height,
+            isFullContent,
+          }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.warn(
+          'Screen capture upload failed:',
+          response.status,
+          text?.substring(0, 200),
+        );
+      }
+    } catch (error) {
+      this.logger.warn('Error uploading screen capture:', error);
+    }
+  }
 }

package/src/types/events.ts

@@ -53,6 +53,8 @@ export interface SDKConfig {
   snapshotFlushInterval?: number;
   /** Max snapshots kept in memory if the backend is unreachable. Defaults to 32. */
   snapshotMaxBufferSize?: number;
+  /** Enable full-content screen captures for heatmap backgrounds. Defaults to true when enableSnapshots is true. */
+  enableHeatmapCapture?: boolean;
   enableCrashTracking?: boolean;
   debug?: boolean;
 }