# **Enable session replay in flutter**

## Overview

Enable [Session Replay](https://coralogix.com/docs/user-guides/rum/product-features/session-replay/index.md) in your Flutter app to capture a visual sequence of user interactions during a session.

Session Replay records periodic screenshots and interaction triggers so you can understand what users saw before, during, and after an issue. Use it to investigate crashes, ANRs, performance slowdowns, and unexpected UI behavior with full visual context.

The Flutter implementation wraps the native mobile SDKs and follows the same behavior and capabilities as the iOS implementation.

## Prerequisites

Install and initialize the Coralogix Flutter RUM SDK before enabling Session Replay.

Session Replay extends the base SDK and must be initialized after calling `initSdk`. Initializing Session Replay without first initializing the SDK results in an error.

## Session Replay defaults

By default, Session Replay:

- Captures screenshots periodically
- Records 100% of sessions
- Does not mask all text or images unless explicitly configured

Customize these behaviors using `CXSessionReplayOptions`.

## Configure and initialize

Use `CXSessionReplayOptions` to configure capture behavior, privacy masking, sampling, and recording mode.

### Example

```dart
Future<void> initializeSessionReplay() async {
  final options = CXSessionReplayOptions(
    captureScale: 1.0,
    captureCompressQuality: 1.0,
    sessionRecordingSampleRate: 100,
    autoStartSessionRecording: true,
    maskAllTexts: false,
    textsToMask: ['Back', '^Session.*'],
    maskAllImages: false,
  );

  await CxFlutterPlugin.initializeSessionReplay(options);
}
```

Call this method after initializing the SDK with `CxFlutterPlugin.initSdk(...)`.

## Options reference

Some options are marked **Required** in the **Default** column. These options do not have a default value and must be explicitly provided when creating `CXSessionReplayOptions`.

| Option                       | Type               | Description                                                                      | Default  |
| ---------------------------- | ------------------ | -------------------------------------------------------------------------------- | -------- |
| `autoStartSessionRecording`  | `bool`             | Start recording automatically after initialization                               | Required |
| `captureScale`               | `double`           | Screenshot resolution scale factor. Lower values reduce memory and storage usage | Required |
| `captureCompressQuality`     | `double` (0.0–1.0) | Image compression quality. Lower values reduce fidelity and file size            | Required |
| `sessionRecordingSampleRate` | `int` (0–100)      | Percentage of sessions to record                                                 | Required |
| `maskAllTexts`               | `bool`             | Mask all visible text elements                                                   | `false`  |
| `textsToMask`                | `List<String>`     | Text patterns to redact (supports regex)                                         | `null`   |
| `maskAllImages`              | `bool`             | Mask all images                                                                  | `false`  |

## Image capture triggers

Screenshots are captured in the following scenarios:

- Periodically, based on the configured capture interval (native default)
- When the user taps the screen
- When the user navigates between views
- When an error or crash occurs
- When you manually trigger a capture

This hybrid model ensures that important visual context is preserved even between periodic captures.

## Start and stop recording

If `autoStartSessionRecording` is set to `false`, control recording manually:

```dart
await CxFlutterPlugin.startSessionRecording();
await CxFlutterPlugin.stopSessionRecording();
```

Check recording status:

```dart
final isRecording = await CxFlutterPlugin.isRecording();
```

Shut down Session Replay:

```dart
await CxFlutterPlugin.shutdownSessionReplay();
```

## Manually capture a screenshot

Capture a screenshot at a specific moment:

```dart
await CxFlutterPlugin.captureScreenshot();
```

Use this method to record key events such as successful checkout, form submission, or state transitions.

## Mask specific widgets

Wrap sensitive UI components with `MaskedWidget` to prevent them from appearing in Session Replay recordings.

### Initialize masking support

To enable widget-level masking in Flutter, initialize the masking bridge in your `main()` method before calling `runApp()`:

```dart
import 'package:cx_flutter_plugin/cx_session_replay_masking.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SessionReplayMasking.initialize();
  runApp(MyApp());
}
```

This step connects the Flutter UI layer to the native Session Replay engine.

Without it, `MaskedWidget` regions will not be applied.

### Example

```dart
MaskedWidget(
  child:TextField(
    controller:passwordController,
    obscureText:true,
  ),
)
```

`MaskedWidget` registers the widget region with the native layer and masks it in captured screenshots.

Use this approach to protect:

- Password fields
- Payment details
- Personal information
- Sensitive account data

You can dynamically control masking using the `isMasked` property.

## Register mask regions programmatically

Register or unregister mask regions directly:

```dart
await SessionReplayMasking.registerRegion('custom-id');
await SessionReplayMasking.unregisterRegion('custom-id');
```

Masking is best-effort and does not block app execution if registration fails.

## Privacy considerations

Control masking behavior using:

- `maskAllTexts` to redact all visible text.
- `textsToMask` to redact specific text patterns using regex.
- `maskAllImages` to blur all images.
- `MaskedWidget` to protect specific UI areas.

Always validate your masking configuration in a staging environment before enabling Session Replay in production.

## Verify initialization

Confirm that Session Replay is initialized:

```dart
final isInitialized = await CxFlutterPlugin.isSessionReplayInitialized();
```

Retrieve the current session ID:

```dart
final sessionId = await CxFlutterPlugin.getSessionId();
```

Use the session ID to correlate logs, traces, and replay data across the Coralogix platform.