Enable session replay in Flutter

Overview

Enable Session Replay 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

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:

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

Check recording status:

final isRecording = await CxFlutterPlugin.isRecording();

Shut down Session Replay:

await CxFlutterPlugin.shutdownSessionReplay();

Manually capture a screenshot

Capture a screenshot at a specific moment:

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():

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

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:

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:

final isInitialized = await CxFlutterPlugin.isSessionReplayInitialized();

Retrieve the current session ID:

final sessionId = await CxFlutterPlugin.getSessionId();

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