Session Replay Flutter Standalone SDK

This article covers the installation of Session Replay for Flutter.

Before you begin

Use the latest version of the amplitude_session_replay package.

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.1

Then run flutter pub get.

Configure your application code:

1. Create a SessionReplay instance with SessionReplayConfig, passing your API key, device ID, and session ID.
2. Call start() to initialize the native SDK and begin recording.
3. Wrap your app with SessionReplayWidget so the recording engine has a Flutter render context.
4. 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();

  final sessionReplay = SessionReplay(
    SessionReplayConfig(
      apiKey: 'YOUR_AMPLITUDE_API_KEY',
      deviceId: 'your-device-id',
      sessionId: DateTime.now().millisecondsSinceEpoch,
      sampleRate: 0.1,
    ),
  );

  await sessionReplay.start();

  runApp(SessionReplayWidget(sessionReplay: sessionReplay, app: const MyApp()));
}

Configuration

Pass the following options through SessionReplayConfig when you create the SessionReplay instance:

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.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.

final sessionReplay = SessionReplay(
  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.

final sessionReplay = SessionReplay(
  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.setSessionId(newSessionId);

Start and stop recording

Control recording for specific pages or features:

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

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

Disable replay collection

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

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

Call sessionReplay.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.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, set shouldInitializeNativeSDK: false in SessionReplayConfig. This tells the Flutter SDK to skip native SDK initialization and let the host app's native SDK own the API key, device ID, session ID, sampling, and upload lifecycle. You still need SessionReplayWidget to enable recording.

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

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

  final sessionReplay = SessionReplay(
    SessionReplayConfig(
      apiKey: 'YOUR_AMPLITUDE_API_KEY',
      deviceId: 'your-device-id',
      sessionId: DateTime.now().millisecondsSinceEpoch,
      shouldInitializeNativeSDK: false,
    ),
  );

  await sessionReplay.start();

  runApp(SessionReplayWidget(sessionReplay: sessionReplay, app: const MyApp()));
}

Methods

The SessionReplay class exposes the following methods:

Lifecycle

Created → start() → Started → stop() → Stopped → start() → Started ...
                                              ↘ dispose() → Disposed

You can call dispose() from any state. It's idempotent — calling it on an already-disposed instance is a no-op. Use dispose() for permanent teardown only. For temporarily pausing and resuming recording, use stop() and start() instead.

Once disposed, the instance can't be reused. To resume recording after disposal, create a new SessionReplay instance and remount SessionReplayWidget with the new instance (for example, by assigning a new Key to force a rebuild). The engine is bound to the widget at mount time and doesn't rebind when SessionReplay is replaced.

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

The Amplitude DSAR API returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a [Amplitude] Session Replay ID event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

{
  "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

Session Replay uses Amplitude's User Privacy API to handle deletion requests. Successful deletion requests remove all session replays for the specified user.

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

Bot filter

Session Replay uses the same block filter available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

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: The SDK captures only the first attached FlutterView. The SDK doesn't support runWidget, FlutterEngineGroup, or view remounts after start().
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.10.0. Android uses session-replay-android [0.26.0, 0.27.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.
• sessionReplay.start() wasn't called after construction.

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.start() after constructing the SessionReplay instance.
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

The default sampleRate is 0.0. Update the rate to a higher number. For more information, refer to Sampling 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.