> For the complete documentation index, see [llms.txt](https://docs.luciq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luciq.ai/react-native/setup-luciq-for-react-native/setup-session-replay/video-like-replay.md).

# Video-Like Replay

{% hint style="danger" %}
**Experimental API - PII Warning**

Video-like Session Replay APIs are experimental.

This feature may capture sensitive UI unmasked in some cases. **USE AT YOUR OWN DISCRETION TO PREVENT PII LEAKAGE.** Opt in only after validating masking/privacy in your app.
{% endhint %}

{% hint style="warning" %}
**Min Required SDK Version**

Video-like Session Replay is supported starting React Native SDK version **19.1.0**.
{% endhint %}

## Overview

Video-like Session Replay transforms your session recordings from simple screen-by-screen captures into smooth, video-like playback. This feature gives you complete visibility into user behavior by:

* **Capturing more frequent screenshots** — See every interaction, not just screen transitions
* **Providing configurable quality profiles** — Balance visual fidelity with storage efficiency
* **Supporting multiple capture modes** — Choose the right approach for your debugging needs

***

## Quick Start

Add these APIs before initializing the SDK for the best experience:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
import Luciq, {
  SessionReplay,
  CapturingMode,
  ScreenshotQuality,
} from '@luciq/react-native';

// Configure video-like replay
SessionReplay.setEnabled(true);
SessionReplay.setCapturingMode(CapturingMode.frequency);
SessionReplay.setScreenshotCaptureInterval(1000); // 1 screenshot per second
SessionReplay.setScreenshotQuality(ScreenshotQuality.normal);

// Initialize SDK
Luciq.init({
  token: 'APP_TOKEN',
  invocationEvents: [/* ... */],
});
```

{% endtab %}
{% endtabs %}

***

## Capturing Modes

Control **when** screenshots are captured using `SessionReplay.setCapturingMode(mode)` with the `CapturingMode` enum.

### Navigation Mode (Default)

Captures screenshots only when users navigate between screens. This is the default behavior and provides the lowest overhead.

**Best for:** Apps where screen transitions are the primary user flow

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setCapturingMode(CapturingMode.navigation);
```

{% endtab %}
{% endtabs %}

***

### Interactions Mode

Captures screenshots on screen navigation **and** user interactions. Includes debouncing to prevent excessive captures.

**Best for:** Debugging user interaction issues, understanding how users interact with complex screens

#### Supported Interactions

* Tap
* Long Press
* Swipe
* Scroll

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setCapturingMode(CapturingMode.interactions);
```

{% endtab %}
{% endtabs %}

***

### Frequency Mode

Captures screenshots at a fixed time interval for true video-like playback. Also captures on screen navigation.

**Best for:** Full video-like replay experience, debugging visual issues, understanding complete user journeys

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setCapturingMode(CapturingMode.frequency);
SessionReplay.setScreenshotCaptureInterval(1000); // Capture every 1000ms (1 FPS)
```

{% endtab %}
{% endtabs %}

***

## Screenshot Capture Interval

When using **Frequency mode**, configure how often screenshots are captured using `SessionReplay.setScreenshotCaptureInterval(intervalMs)`.

| **Parameter** | **Description**                       |
| ------------- | ------------------------------------- |
| `intervalMs`  | Time between captures in milliseconds |
| **Default**   | 1000ms (1 screenshot per second)      |
| **Minimum**   | 500ms                                 |

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setScreenshotCaptureInterval(500);  // Capture every 500ms (2 FPS)
SessionReplay.setScreenshotCaptureInterval(2000); // Capture every 2 seconds
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Values below 500ms are automatically clamped to 500ms (the minimum allowed). This setting has no effect in `navigation` or `interactions` modes.
{% endhint %}

### Timer Reset Behavior

The capture timer resets when:

* A manual screenshot is captured via the SDK API
* Screen navigation occurs

This ensures you always capture important moments regardless of the timer state.

***

## Screenshot Quality

Control the **visual quality** of captured screenshots using `SessionReplay.setScreenshotQuality(quality)` with the `ScreenshotQuality` enum. Higher quality provides better visuals but uses more storage.

### Quality Profiles

| **Profile**          | **Compression**                | **Use Case**                                  |
| -------------------- | ------------------------------ | --------------------------------------------- |
| **high**             | 50% quality (WebP)             | Detailed debugging, visual regression testing |
| **normal** (Default) | 25% quality (WebP)             | Balanced quality and storage                  |
| **greyscale**        | 25% quality + grayscale (WebP) | Maximum storage efficiency, text-heavy apps   |

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setScreenshotQuality(ScreenshotQuality.high);      // Best visual quality
SessionReplay.setScreenshotQuality(ScreenshotQuality.normal);    // Balanced (default)
SessionReplay.setScreenshotQuality(ScreenshotQuality.greyscale); // Smallest file size
```

{% endtab %}
{% endtabs %}

### Estimated Screenshots per Session

Based on the default 2MB session screenshot limit:

| **Quality Profile** | **Approx. Screenshots per Session** |
| ------------------- | ----------------------------------- |
| high                | \~62 screenshots                    |
| normal              | \~104 screenshots                   |
| greyscale           | \~130 screenshots                   |

{% hint style="info" %}
For video-like replay at 1 FPS with `normal` quality, you can capture approximately 1-2 minutes of continuous session activity.
{% endhint %}

***

## Configuration Timing

### Recommended: Before SDK Initialization

For best results, configure Video-like Session Replay **before** calling `Luciq.init()`:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
import Luciq, {
  SessionReplay,
  CapturingMode,
  ScreenshotQuality,
} from '@luciq/react-native';

// Configure video-like replay first
SessionReplay.setEnabled(true);
SessionReplay.setCapturingMode(CapturingMode.frequency);
SessionReplay.setScreenshotCaptureInterval(1000);
SessionReplay.setScreenshotQuality(ScreenshotQuality.normal);

// Then initialize SDK
Luciq.init({
  token: 'APP_TOKEN',
  invocationEvents: [/* ... */],
});
```

{% endtab %}
{% endtabs %}

### Runtime Configuration

You can also change settings during the session. Changes take effect as follows:

| **Setting**        | **When Applied**                 |
| ------------------ | -------------------------------- |
| Capturing Mode     | Next session                     |
| Screenshot Quality | Next screenshot                  |
| Capture Interval   | After current interval completes |

{% tabs %}
{% tab title="JavaScript" %}

```javascript
// Change quality mid-session
SessionReplay.setScreenshotQuality(ScreenshotQuality.high);

// Switch capturing mode (applies next session)
SessionReplay.setCapturingMode(CapturingMode.frequency);
```

{% endtab %}
{% endtabs %}

***

## Privacy & Masking

Video-like Session Replay **respects all existing privacy** configurations:

* **Auto-masking** continues to work across all capturing modes
* **Private views** are masked in all captured screenshots
* **Network log redaction** is applied identically across every capturing mode and quality profile

Switching to `frequency` mode does **not** bypass masking.

For more information on privacy controls, see [Setup Session Replay](/react-native/setup-luciq-for-react-native/setup-session-replay.md).

***

## Platform Notes

* **iOS**: Backed by the same native screenshot pipeline documented in the [iOS Video-Like Replay guide](https://docs.luciq.ai/ios/setup-luciq-for-ios/setup-session-replay/video-like-replay). SwiftUI scroll detection in `interactions` mode may require manual gesture wiring on the native side — see [SwiftUI Integration for iOS](https://docs.luciq.ai/ios/setup-luciq-for-ios/integrate-luciq-on-ios/integrate-swiftui).
* **Android**: Capturing modes and quality profiles map to the equivalent native Session Replay configuration documented in the [Android Video-Like Replay guide](https://docs.luciq.ai/android/set-up-luciq-for-android/set-up-session-replay/video-like-replay). No extra setup is required from React Native.

***

## Best Practices

### Recommended Configurations

| **Use Case**      | **Configuration**                          |
| ----------------- | ------------------------------------------ |
| General debugging | Navigation mode + `normal` quality         |
| UI/UX analysis    | Interactions mode + `normal` quality       |
| Full video replay | Frequency mode (1000ms) + `normal` quality |
| Visual debugging  | Frequency mode (500ms) + `high` quality    |
| Storage-conscious | Navigation mode + `greyscale` quality      |

### Code Examples

**Video-like Replay (Balanced)**

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setCapturingMode(CapturingMode.frequency);
SessionReplay.setScreenshotCaptureInterval(1000);
SessionReplay.setScreenshotQuality(ScreenshotQuality.normal);
```

{% endtab %}
{% endtabs %}

**Interaction-Focused Debugging**

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setCapturingMode(CapturingMode.interactions);
SessionReplay.setScreenshotQuality(ScreenshotQuality.normal);
```

{% endtab %}
{% endtabs %}

**Maximum Visual Fidelity**

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setCapturingMode(CapturingMode.frequency);
SessionReplay.setScreenshotCaptureInterval(500);
SessionReplay.setScreenshotQuality(ScreenshotQuality.high);
```

{% endtab %}
{% endtabs %}

**Storage-Optimized**

{% tabs %}
{% tab title="JavaScript" %}

```javascript
SessionReplay.setCapturingMode(CapturingMode.navigation);
SessionReplay.setScreenshotQuality(ScreenshotQuality.greyscale);
```

{% endtab %}
{% endtabs %}

***

## API Reference

### SessionReplay.setCapturingMode()

Sets when screenshots are captured.

```
SessionReplay.setCapturingMode(mode: CapturingMode): void
```

| **Value**                    | **Description**                             |
| ---------------------------- | ------------------------------------------- |
| `CapturingMode.navigation`   | Capture on screen changes only (default)    |
| `CapturingMode.interactions` | Capture on navigation and user interactions |
| `CapturingMode.frequency`    | Capture at fixed time intervals             |

***

### SessionReplay.setScreenshotQuality()

Sets the visual quality of captured screenshots.

```
SessionReplay.setScreenshotQuality(quality: ScreenshotQuality): void
```

| **Value**                     | **Description**                  |
| ----------------------------- | -------------------------------- |
| `ScreenshotQuality.high`      | 50% WebP compression             |
| `ScreenshotQuality.normal`    | 25% WebP compression (default)   |
| `ScreenshotQuality.greyscale` | Grayscale + 25% WebP compression |

***

### SessionReplay.setScreenshotCaptureInterval()

Sets the capture interval for Frequency mode.

```
SessionReplay.setScreenshotCaptureInterval(intervalMs: number): void
```

| **Parameter** | **Description**                                    |
| ------------- | -------------------------------------------------- |
| `intervalMs`  | Interval in milliseconds (min: 500, default: 1000) |

***

## Migration Guide

If you're upgrading from a previous SDK version:

1. **No breaking changes** — Default behavior remains `navigation` mode with `normal` quality.
2. **Opt-in feature** — Video-like replay must be explicitly configured.
3. **Repro Steps unaffected** — Bug and Crash report screenshots continue to use `navigation` mode and `normal` quality.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.luciq.ai/react-native/setup-luciq-for-react-native/setup-session-replay/video-like-replay.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.