Amplitude Session Replay Flutter SDK #

Warning This SDK is currently in alpha. APIs may change and there will be breaking changes before the stable release.

This is Amplitude's Session Replay SDK for Flutter.

Installation #

Add the package to your pubspec.yaml:

dependencies:
  amplitude_session_replay: ^1.0.0

Then run:

flutter pub get

Quick Start #

Call SessionReplay.instance.init with a SessionReplayConfig, then start recording when your app is ready:

import 'package:amplitude_session_replay/amplitude_session_replay.dart';

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

  final config = SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: 'your-device-id',
    sessionId: DateTime.now().millisecondsSinceEpoch, // from your analytics SDK
  );

  SessionReplay.instance.init(config);
  await SessionReplay.instance.start();

  runApp(const MyApp());
}

Hybrid Mode (Add-to-App) #

If your app already initializes the native Amplitude Session Replay SDK (iOS or Android — for example, an add-to-app embedding inside a host native application), call attach() instead of init(). The Flutter SDK installs its binary channel handler and lets the native SDK drive the recording lifecycle:

import 'package:amplitude_session_replay/amplitude_session_replay.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SessionReplay.instance.attach();
  runApp(const MyApp());
}

In hybrid mode, the native SDK owns recording state. start(), stop(), flush(), setOptOut(), setSessionId(), and setDeviceId() are no-ops in this mode (they log a warning and return) — set those options on the native SDK directly. dispose() tears down the Dart channel handler and engine but leaves the native SDK alone, since the host app owns its lifecycle.

Native plugin registration #

If automatic Flutter plugin registration is disabled, explicitly register this package's native Flutter plugin (AmplitudeSessionReplayPlugin) with each engine before that engine creates any native platform views, such as maps or WebViews. Views created before registration remain unblocked and may appear unmasked in replay, even briefly, exposing sensitive content. Registering the plugin later cannot remove content that has already been captured.

Register the native plugin before showing Flutter screens with native views and before starting recording. Calling SessionReplay.instance.attach() does not replace native plugin registration.

With standard automatic registration, Amplitude does not need to be first in the plugin list. Registration completes synchronously before Flutter processes platform-view creation; factories registered before or after Amplitude are covered by the creation hook.

Native Platform Views #

AmpMask, AmpUnmask, and AmpBlock also apply to supported embedded native views. See native-view privacy for platform differences and limitations.

Need Help? #

If you have any problems or issues over our SDK, feel free to create a GitHub issue or submit a request on Amplitude Help.