Flutter Session Replay installation

Control recording programmatically

Requires PostHog Flutter SDK version >= 5.14.0. Available on iOS, Android, and Web.

Setting config.sessionReplay = false in your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.

You can manually control when to start and stop session recordings using the following methods:

• startSessionRecording({bool resumeCurrent = true})
  • Set resumeCurrent to true to resume a previous session recording (default).
  • Set resumeCurrent to false to start a new session recording.
  • To begin a completely fresh session, call stopSessionRecording() first, then startSessionRecording(resumeCurrent: false).
• stopSessionRecording()
  • Stops/pauses the current session recording.
• isSessionReplayActive()
  • Returns a Future<bool> telling you whether a recording is currently active on this device. Resolves to false when session replay is off, hasn't started yet, or isn't supported on the current platform.

Note: Calling these methods will have no effect if session recordings are disabled in your PostHog Project Settings. Manual starts still respect project ingestion controls, including sampling and event triggers.

Pause recording on a sensitive screen

Masking hides what's drawn on screen, but the recording still includes where each touch lands. On a PIN, passcode, or card-number keypad, the tap positions alone can reveal the value entered, so stop recording while the screen is shown and resume it once the screen is dismissed:

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

  @override
  State<PinEntryScreen> createState() => _PinEntryScreenState();
}

class _PinEntryScreenState extends State<PinEntryScreen> {
  bool _wasRecording = false;

  @override
  void initState() {
    super.initState();
    // Asked before the stop is sent, so it reports the state on entry.
    Posthog().isSessionReplayActive().then((active) => _wasRecording = active);
    Posthog().stopSessionRecording();
  }

  @override
  void dispose() {
    if (_wasRecording) {
      Posthog().startSessionRecording();
    }
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return const PinKeypad();
  }
}

startSessionRecording() resumes the current session by default, so the replay continues as one recording with the keypad left out. The isSessionReplayActive() check matters: on iOS, startSessionRecording() installs the replay integration if it isn't there yet, so an app that wasn't recording would start when the screen closes. Only resuming when the screen found recording active keeps that from happening.

If you want taps left out of every recording rather than one screen's, set sessionReplayConfig.captureTouches = false before setup() instead (SDK >= 5.41.0); see privacy controls.

Record or ignore specific screens

You can combine these methods with your navigation to record only certain screens, or to pause recording on sensitive ones. For example, using a NavigatorObserver, stop recording on a sensitive route and resume otherwise:

const ignoredScreens = {'Payment', 'Settings'};

class RecordingByScreenObserver extends NavigatorObserver {
  void _update(Route<dynamic>? route) {
    final screenName = route?.settings.name;
    if (screenName != null && ignoredScreens.contains(screenName)) {
      Posthog().stopSessionRecording();
    } else {
      Posthog().startSessionRecording();
    }
  }

  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) => _update(route);

  @override
  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) => _update(previousRoute);
}

// Then register it on your MaterialApp:
// navigatorObservers: [RecordingByScreenObserver()]

Invert the check (startSessionRecording only for screens in an allowlist, stopSessionRecording otherwise) if you'd rather record just a specific set of screens.