Session Replay Flutter Standalone SDK

This article covers the installation of Session Replay for Flutter.

Before you begin

The Session Replay Flutter SDK requires that:

1. Your application runs on iOS 13.0+ or Android 5.0+ (minSdk 21).
2. Your project uses Dart SDK 3.7.2 or later and Flutter SDK 3.29.2 or later.
3. You can provide a device ID and session ID to the SDK. These values must match the identifiers you send as event properties to Amplitude.

The SDK doesn't provide session management. Your application or a third-party integration must update the SDK when the session ID or device ID changes.

Compatibility

Quickstart

Add Session Replay to your pubspec.yaml:

dependencies:
  amplitude_session_replay: ^0.1.0-beta.5

Then run flutter pub get.

SessionReplay is a process-wide singleton. Access it through SessionReplay.instance, and don't construct it directly.

Configure your application code:

1. Call SessionReplay.instance.init() with a SessionReplayConfig, passing your API key, device ID, and session ID. init() is synchronous. It stores the config and installs the message channel handler.
2. Call start() to initialize the native SDK and begin recording.
3. When the session ID or device ID changes, call setSessionId() or setDeviceId() to keep Session Replay synchronized.

import 'package:amplitude_session_replay/amplitude_session_replay.dart';
import 'package:flutter/widgets.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // init() is synchronous: it stores the config and installs the channel handler.
  SessionReplay.instance.init(
    SessionReplayConfig(
      apiKey: 'YOUR_AMPLITUDE_API_KEY',
      deviceId: 'your-device-id',
      sessionId: DateTime.now().millisecondsSinceEpoch,
      sampleRate: 0.1,
    ),
  );

  // start() initializes the native SDK and begins recording.
  await SessionReplay.instance.start();

  runApp(const MyApp());
}

Configuration

Pass the following options through SessionReplayConfig when you call SessionReplay.instance.init():

Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

Mask onscreen data

Session Replay provides three Flutter widgets for privacy control. These widgets apply to the entire subtree of the wrapped widget. Priority order: AmpBlock > AmpMask > AmpUnmask.

Privacy levels

The privacyConfig option controls automatic masking behavior:

AmpMask

Replaces every character of captured text with an asterisk (*), preserving the original text length and layout. Use this to protect sensitive information that the automatic privacy level doesn't catch:

AmpMask(
  child: Text('Sensitive information'),
)

AmpBlock

Blocks an entire subtree from recording and replaces it with a placeholder. Use this for highly sensitive content:

AmpBlock(
  child: TextField(
    decoration: InputDecoration(labelText: 'Password'),
  ),
)

AmpUnmask

Prevents automatic masking from privacy level rules. Use this to reveal content that the privacy level would otherwise mask. AmpUnmask can't override a manual AmpMask or AmpBlock:

AmpUnmask(
  child: Text('Public content'),
)

User opt-out

To opt users out of session replay collection, pass optOut: true during initialization, or call setOptOut(optOut: true) at runtime. Opted-out users don't record or upload replay data.

await SessionReplay.instance.setOptOut(optOut: true);

EU data residency

Amplitude customers who use the EU data center can access Session Replay. Set serverZone to ServerZone.eu during initialization.

SessionReplay.instance.init(
  SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: 'your-device-id',
    sessionId: DateTime.now().millisecondsSinceEpoch,
    serverZone: ServerZone.eu,
  ),
);

Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use the sampleRate configuration option to set the percentage of total sessions that Session Replay captures. For example:

To set the sampleRate consider the monthly quota on your Session Replay plan. For example, if your monthly quota is 2,500,000 sessions, and you average 3,000,000 monthly sessions, your quota is 83% of your average sessions. In this case, to ensure sampling lasts through the month, set sampleRate to .83 or lower.

Keep the following in mind as you consider your sample rate:

• When you reach your monthly session quota, Amplitude stops capturing sessions for replay.
• Session quotas reset on the first of every month.
• Use sample rate to distribute your session quota over the course of a month, rather than using your full quota at the beginning of the month.
• To find the best sample rate, Amplitude recommends that you start low, for example .01. If this value doesn't capture enough replays, raise the rate over the course of a few days. For ways to monitor the number of session replays captured, see View the number of captured sessions.
• Replays with processing errors don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

SessionReplay.instance.init(
  SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: 'your-device-id',
    sessionId: DateTime.now().millisecondsSinceEpoch,
    sampleRate: 0.01, // Capture 1% of sessions
  ),
);

Update the session ID

When your session ID changes (for example, on user login or session timeout), update Session Replay:

final newSessionId = DateTime.now().millisecondsSinceEpoch;
await SessionReplay.instance.setSessionId(newSessionId);

Start and stop recording

Control recording for specific pages or features:

// Stop recording before entering a restricted area
await SessionReplay.instance.stop();

// Resume recording after leaving the restricted area
await SessionReplay.instance.start();

Disable replay collection

After you enable Session Replay, it runs on your app until either:

• The user leaves your app.
• You call SessionReplay.instance.stop().
• You call SessionReplay.instance.dispose().

Call SessionReplay.instance.stop() before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

Call SessionReplay.instance.start() to re-enable replay collection when the user returns to an unrestricted area of your app.

Hybrid and add-to-app

If your Flutter module runs inside a native iOS or Android host that already integrates the Amplitude Session Replay native SDK, call SessionReplay.instance.attach() instead of init(). This installs the message channel handler and lets the host app's native SDK own the API key, device ID, session ID, sampling, masking, and upload lifecycle. Don't pass a SessionReplayConfig. The native SDK owns configuration in this mode.

import 'package:amplitude_session_replay/amplitude_session_replay.dart';
import 'package:flutter/widgets.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // The native SDK owns config and lifecycle. attach() only installs the
  // channel handler so native start commands reach the Flutter engine.
  SessionReplay.instance.attach();

  runApp(const MyApp());
}

In hybrid mode, the native SDK owns the recording lifecycle. start(), stop(), flush(), setOptOut(), setSessionId(), and setDeviceId() log a warning and no-op. Configure those on the native SDK instead. dispose() tears down only the Dart channel handler and engine, and leaves the native SDK alone.

If your app runs multiple Flutter engines (for example, FlutterEngineGroup with several Dart entry points), call attach() in each entry point. Each engine runs its own isolate with its own SessionReplay.instance.

Methods

Call these methods on the SessionReplay.instance singleton:

Lifecycle

init() is one-shot per lifecycle: it's only callable from the uninitialized (or disposed) state. To re-initialize with a new config, call dispose() first, then init() again.

You can call dispose() from any state. It returns the singleton to its uninitialized state, so a later init() or attach() cleanly revives it. Use dispose() for permanent teardown only. To temporarily pause and resume recording, use stop() and start() instead.

Upgrade from earlier beta versions

Version 0.1.0-beta.5 simplifies installation and reworks the SessionReplay API. SessionReplay is now a process-wide singleton, and the SessionReplayWidget wrapper is no longer required.

Breaking changes

For Flutter-only apps:

For hybrid and add-to-app:

Flutter-only apps

Replace the constructor and SessionReplayWidget wrapper with SessionReplay.instance.init() and start():

// Before
final sessionReplay = SessionReplay(
  SessionReplayConfig(apiKey: '...', sampleRate: 1.0),
);
runApp(SessionReplayWidget(sessionReplay: sessionReplay, app: const MyApp()));
await sessionReplay.start();

// After
SessionReplay.instance.init(          // synchronous, no await
  SessionReplayConfig(apiKey: '...', sampleRate: 1.0),
);
await SessionReplay.instance.start();
runApp(const MyApp());                // no SessionReplayWidget wrapping needed

• init() is one-shot per lifecycle. Call await SessionReplay.instance.dispose() before re-initializing with a new config.
• Setters (setSessionId(), setDeviceId(), setOptOut()) still work between init() and start().

Hybrid and add-to-app

Replace the placeholder config and widget wrapper with a single attach() call:

// Before — placeholder config + widget wrapper
return SessionReplayWidget(
  sessionReplay: SessionReplay(
    const SessionReplayConfig(
      apiKey: 'YOUR_API_KEY',
      deviceId: 'YOUR_DEVICE_ID',
      shouldInitializeNativeSDK: false,
    ),
  ),
  app: MaterialApp(...),
);

// After — one line per entry point, no config needed
void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SessionReplay.instance.attach(); // native owns config and lifecycle
  runApp(const MyApp());
}

• Call attach() in every Dart entry point. Each Flutter engine is its own isolate with its own SessionReplay.instance.
• Remove any host-app native SDK version pin (for example, a Gradle resolutionStrategy.force(...)) and let it resolve within the range the Flutter plugin declares.

Session Replay properties

The AmpMask, AmpUnmask, and AmpBlock privacy widgets are unchanged.

Data retention, deletion, and privacy

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

Retention period

If your Amplitude plan includes Session Replay, Amplitude retains raw replay data for 30 days from the date of ingestion.

If you purchase extra session volume, Amplitude retains raw replay data for 90 days from the date of ingestion. If you need a more strict policy, contact Amplitude support to set the value to 30 days.

Changes to the retention period impact replays ingested after the change. Sessions captured and ingested before a retention period change retain the previous retention period.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

DSAR API

{
  "amplitude_id": 123456789,
  "app": 12345,
  "event_time": "2020-02-15 01:00:00.123456",
  "event_type": "first_event",
  "server_upload_time": "2020-02-18 01:00:00.234567",
  "device_id": "your device id",
  "user_properties": { ... }
  "event_properties": {
    "[Amplitude] Session Replay ID": "cb6ade06-cbdf-4e0c-8156-32c2863379d6/1699922971244"
  }
  "session_id": 1699922971244,
}

Data deletion

When you delete the Amplitude project on which you use Session Replay, Amplitude deletes that replay data.

Bot filter

Known limitations

1. Beta status: APIs may change. Expect breaking changes before the stable release.
2. RSuperellipse capture: Requires Flutter 3.32 or later. Base functionality works on Flutter 3.29.2+.
3. Multi-view apps: In Flutter-only mode, the SDK captures the app's primary render view. For hybrid and add-to-app setups that run multiple Flutter engines, call attach() in each Dart entry point (refer to Hybrid and add-to-app).
4. Remote config override: When enableRemoteConfig is true, server settings can override the local sampleRate and privacy settings.
5. Native SDK dependencies: iOS uses AmplitudeSessionReplay ~>0.12.2. Android uses session-replay-android [0.27.0, 0.28.0).

Troubleshooting

Session replays don't appear in Amplitude

Session replays may not appear because of:

• Lack of network connectivity.
• Sampling excluded the session (sampleRate too low).
• No events sent with matching deviceId and sessionId for the session.
• A missing SessionReplay.instance.start() call after init().

Verify your configuration

1. Check that sampleRate is greater than 0. The default is 0.0, which captures no sessions.
2. Confirm you call SessionReplay.instance.start() after SessionReplay.instance.init().
3. Ensure the apiKey, deviceId, and sessionId match the values you send with analytics events.

Verify network connectivity

Ensure your app has access to the internet and try again.

Check sample rate

Session Replay processing errors

Replays appear in Amplitude within minutes of ingestion. Delays or errors may result from:

• Mismatched API keys or device IDs between Session Replay and your analytics instrumentation.
• Session Replay references the wrong project.
• Short sessions. If a user bounces within a few seconds of initialization, the SDK may not have time to upload replay data.