Flutter session replay installation

1
Install the package
Required
Add the PostHog Flutter SDK to your pubspec.yaml:
pubspec.yaml
posthog_flutter: ^5.0.0
SDK version
Session replay requires PostHog Flutter SDK version 4.7.0 or higher. We recommend always using the latest version.

Disable auto-init for Android

Required

For session replay, you need to use manual initialization. Add this to your AndroidManifest.xml to disable auto-init:

android/app/src/main/AndroidManifest.xml
<application>
    <activity>
        [...]
    </activity>
    <meta-data android:name="com.posthog.posthog.AUTO_INIT" android:value="false" />
</application>

Update the minimum Android SDK version to 21 in android/app/build.gradle:

android/app/build.gradle
defaultConfig {
    minSdkVersion 21
    // rest of your config
}

Disable auto-init for iOS

Required

Add this to your Info.plist to disable auto-init:

ios/Runner/Info.plist
<dict>
    [...]
    <key>com.posthog.posthog.AUTO_INIT</key>
    <false/>
    [...]
</dict>

Update the minimum platform version to iOS 13.0 in your Podfile:

Podfile
platform :ios, '13.0'
# rest of your config

4
Enable session recordings in project settings
Required
Go to your PostHog Project Settings and enable Record user sessions. Session recordings will not work without this setting enabled.
If you're using Flutter Web, also enable the Canvas capture setting. This is required as Flutter renders your app using a browser canvas element.

Initialize PostHog with session replay

Required

Initialize PostHog in your main.dart with session replay enabled. Here are all the available options:

main.dart
import 'package:flutter/material.dart';
import 'package:posthog_flutter/posthog_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final config = PostHogConfig('<ph_project_token>');
  config.host = 'https://us.i.posthog.com';
  config.debug = true;
  config.captureApplicationLifecycleEvents = true;

  // Enable session recording. Requires enabling in your project settings as well.
  // Default is false.
  config.sessionReplay = true;

  // Enable masking of all text and text input fields. Default is true.
  config.sessionReplayConfig.maskAllTexts = false;

  // Enable masking of all images. Default is true.
  config.sessionReplayConfig.maskAllImages = false;

  // Throttling delay used to reduce the number of snapshots captured. Default is 1s.
  config.sessionReplayConfig.throttleDelay = const Duration(milliseconds: 1000);

  await Posthog().setup(config);
  runApp(MyApp());
}

For more configuration options, see the Flutter session replay docs.

Wrap your app with PostHogWidget

Required

For Session Replay to work, wrap your app with PostHogWidget and add the PosthogObserver:

MyApp.dart
import 'package:flutter/material.dart';
import 'package:posthog_flutter/posthog_flutter.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return PostHogWidget(
      child: MaterialApp(
        navigatorObservers: [PosthogObserver()],
        title: 'My App',
        home: const HomeScreen(),
      ),
    );
  }
}

MyApp.dart
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:posthog_flutter/posthog_flutter.dart';

final GoRouter _router = GoRouter(
  observers: [PosthogObserver()],
  routes: [
    GoRoute(
      name: 'home',  // Name your routes for proper screen tracking
      path: '/',
      builder: (context, state) => const HomeScreen(),
    ),
  ],
);

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return PostHogWidget(
      child: MaterialApp.router(
        routerConfig: _router,
        title: 'My App',
      ),
    );
  }
}

7
Watch session recordings
Recommended
Visit your site or app and interact with it for at least 10 seconds to generate a recording. Navigate between pages, click buttons, and fill out forms to capture meaningful interactions.
Watch your first recording →

Next steps

Recommended

Now that you're recording sessions, continue with the resources below to learn what else Session Replay enables within the PostHog platform.

Resource	Description
Watching recordings	How to find and watch session recordings
Privacy controls	How to mask sensitive data in recordings
Network recording	How to capture network requests in recordings
Console log recording	How to capture console logs in recordings
More tutorials	Other real-world examples and use cases

Flutter session replay installation

Install the package

Disable auto-init for Android

Disable auto-init for iOS

Enable session recordings in project settings

Initialize PostHog with session replay

Wrap your app with PostHogWidget

Watch session recordings

Next steps

Community questions

Was this page useful?