Flutter Session Replay (Android)

Session Replay records what a user saw and did in your Flutter application, so you can watch a bug happen instead of reconstructing it from a stack trace. Replays are linked to the RUM session they belong to, so you can move from an error straight to the recording.

Session Replay ships as a separate package, atatus_session_replay, and runs on top of RUM.

Prerequisites

• RUM is set up in your application. See Flutter Monitoring Setup.
• Flutter 3.27.0 or higher and Dart SDK 3.6.0 or higher.

Setup

1. Add the package

Add atatus_session_replay alongside the plugin in your pubspec.yaml:

dependencies:
  atatus_flutter_plugin: ^1.0.4
  atatus_session_replay: ^1.0.4

Then fetch the packages:

flutter pub get

2. Enable Session Replay

Call enableSessionReplay on your AtatusConfiguration. RUM must be configured for replay to record anything:

import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';
import 'package:atatus_session_replay/atatus_session_replay.dart';

void main() {
  final configuration = AtatusConfiguration(
    licenseKey: '<LICENSE_KEY>',
    env: '<ENV_NAME>',
    appName: '<APP_NAME>',
    rumConfiguration: AtatusRumConfiguration(),
  )..enableSessionReplay(
      AtatusSessionReplayConfiguration(
        // Percentage of sampled RUM sessions that record a replay
        replaySampleRate: 30.0,
        textAndInputPrivacyLevel: TextAndInputPrivacyLevel.maskAll,
        imagePrivacyLevel: ImagePrivacyLevel.maskAll,
        touchPrivacyLevel: TouchPrivacyLevel.hide,
      ),
    );

  AtatusSdk.runApp(configuration, TrackingConsent.granted, () async {
    runApp(const MyApp());
  });
}

3. Add the capture widget

Add a SessionReplayCapture widget at the root of your widget tree, above MaterialApp or your equivalent application widget. A Key is required:

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  // A key is required for SessionReplayCapture
  final captureKey = GlobalKey();

  @override
  Widget build(BuildContext context) {
    return SessionReplayCapture(
      key: captureKey,
      rum: AtatusSdk.instance.rum!,
      sessionReplay: AtatusSessionReplay.instance,
      child: MaterialApp(
        home: const HomeScreen(),
      ),
    );
  }
}

Configuration Options

AtatusSessionReplayConfiguration accepts the following options:

Privacy

Session Replay masks everything by default. Loosen the defaults only for the parts of your application you are sure carry no personal data.

Default privacy levels

TextAndInputPrivacyLevel controls text and input widgets:

ImagePrivacyLevel controls images:

TouchPrivacyLevel controls touch indicators:

Override privacy for part of the tree

Wrap a subtree in SessionReplayPrivacy to change the privacy level for that part of the application, or to hide it entirely:

// Record this screen's text, but keep everything else masked
SessionReplayPrivacy(
  textAndInputPrivacyLevel: TextAndInputPrivacyLevel.maskSensitiveInputs,
  child: const ProductDetailScreen(),
);

// Hide a payment form completely
SessionReplayPrivacy(
  hide: true,
  child: const PaymentForm(),
);

Setting an option to null leaves that level unchanged for the subtree.

Validate That Replay Data Is Being Sent

To confirm the SDK is recording and uploading replays, raise its verbosity before you initialize it:

AtatusSdk.instance.sdkVerbosity = CoreLoggerLevel.debug;

Verbosity defaults to CoreLoggerLevel.warn, and internal logging only runs in debug builds. Session Replay upload messages from the underlying Android SDK then appear in the device log.

Tracking Consent

Session Replay follows the same tracking consent value as the rest of the SDK, which you set at initialization and can update at any time. See Set Tracking Consent (GDPR).

Current Limitations

• Recording cannot be started or stopped at runtime. Recording begins when Session Replay is enabled and continues for the session. Use replaySampleRate to control which sessions are recorded, or call enableSessionReplay conditionally to decide at startup.
• Web view content is not captured in the replay. The recorder walks the Flutter widget tree, so anything a web view renders appears as an opaque region. RUM events from web views are still collected (use the atatus_webview_tracking package for that), but they do not produce replay footage.

Next steps

• Configure the rest of the agent in Flutter Agent Configuration Options.
• Correlate replays with your logs using Flutter Log Collection.