Flutter session replay installation

  1. Add PostHog to your app

    Required

    Session replay requires PostHog Flutter SDK version >= 4.7.0, and it's recommended to always use the latest version.

    Note: For session replay, you must setup the SDK manually.

    Manual installation

    First, add posthog_flutter to your pubspec.yaml:

    pubspec.yaml
    # rest of your code
    dependencies:
    flutter:
    sdk: flutter
    posthog_flutter: ^5.0.0
    # rest of your code

    Then complete the manual setup for each platform:

    Android setup

    Add your PostHog configuration to your AndroidManifest.xml file located in the android/app/src/main:

    android/app/src/main/AndroidManifest.xml
    <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.package.name">
    <application>
    <!-- ... other configuration ... -->
    <meta-data android:name="com.posthog.posthog.AUTO_INIT" android:value="false" />
    </application>
    </manifest>

    You'll also need to update the minimum Android SDK version to 21 in android/app/build.gradle:

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

    iOS setup

    Add your PostHog configuration to the Info.plist file located in the ios/Runner directory:

    ios/Runner/Info.plist
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
    <!-- rest of your configuration -->
    <key>com.posthog.posthog.AUTO_INIT</key>
    <false/>
    </dict>
    </plist>

    You'll need to set the minimum platform version to iOS 13.0 in your Podfile:

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

    Dart setup

    Then setup the SDK manually:

    Dart
    import 'package:flutter/material.dart';
    import 'package:posthog_flutter/posthog_flutter.dart';
    Future<void> main() async {
    // init WidgetsFlutterBinding if not yet
    WidgetsFlutterBinding.ensureInitialized();
    final config = PostHogConfig('<ph_project_api_key>');
    config.debug = true;
    config.captureApplicationLifecycleEvents = true;
    // or EU Host: 'https://eu.i.posthog.com'
    config.host = 'https://us.i.posthog.com';
    await Posthog().setup(config);
    runApp(MyApp());
    }

    Widget and Observer setup

    This configuration is only needed for mobile session replay.

    Wrap your app with the PostHogWidget Widget and Install the PosthogObserver Observer.

    Dart
    import 'package:flutter/material.dart';
    import 'package:posthog_flutter/posthog_flutter.dart';
    class MyApp extends StatefulWidget {
    const MyApp({super.key});
    State<MyApp> createState() => _MyAppState();
    }
    class _MyAppState extends State<MyApp> {
    void initState() {
    super.initState();
    }
    Widget build(BuildContext context) {
    return PostHogWidget(
    child: MaterialApp(
    navigatorObservers: [PosthogObserver()],
    title: 'My App',
    home: const HomeScreen(),
    ),
    );
    }
    }

    If you're using go_router, check this page to learn how to set up the PosthogObserver.

  2. Enable session recordings in your project settings

    Required

    Enable session recordings in your PostHog Project Settings.

    If you're using Flutter Web, also enable the Canvas capture in your project settings. This is needed as Flutter renders your app using a browser canvas element.

    Enable session recordings in your PostHog'
  3. Configure replay settings

    Required

    Add sessionReplay = true to your PostHog configuration alongside any of your other configuration options:

    Dart
    final config = PostHogConfig('<ph_project_api_key>');
    /// Enable Recording of Session replay for Android and iOS.
    /// Requires Record user sessions to be enabled in the PostHog Project Settings.
    /// Defaults to false.
    config.sessionReplay = true;
    /// Enable masking of all text and text input fields.
    /// Default: true.
    config.sessionReplayConfig.maskAllTexts = false;
    /// Enable masking of all images.
    /// Default: true.
    config.sessionReplayConfig.maskAllImages = false;
    /// Throttling delay used to reduce the number of snapshots captured and reduce performance impact.
    /// This is used for capturing the view as a screenshot.
    /// The lower the number, the more snapshots will be captured but higher the performance impact.
    /// Defaults to 1s.
    /// Ps: it was called [debouncerDelay] until version 4.7.1
    config.sessionReplayConfig.throttleDelay = const Duration(milliseconds: 1000);

Limitations for mobile session replay

  • On Android, requires API >= 26.
  • On iOS, minimum deployment target is iOS13.
  • Wireframe mode isn't supported, only screenshot mode.
  • Network performance recording isn't supported yet.

Limitations for flutter web session replay

Troubleshooting

  • Update your SDK and iOS Pods.
  • Make sure to set the minimum platform version to iOS 13.0 in your Podfile.
  • Make sure you have disabled automatic SDK intialization.
  • Run a clean build if you experience issues.
  • For blank recordings for mobile session replay, be sure to set up the Widget and Observer.
  • For blank recordings for flutter web session replay, be sure to enable Canvas capture.
  • If you have enabled session replay using feature flags, the flags are evaluated on the device once the PostHog SDK starts as early as possible. The SDK might be using the cached flags from the previous SDK start. If you have changed the flag or its condition, kill and reopen the app to force a new SDK start at least once.
    • This will also happen in production, and you might experience some delay for the new flag/conditions to take effect on your users. We're tracking this bug in issue #263.
    • Session replay feature flag evaluation does not capture $feature_flag_called events, so the Usage tab on the feature flag page won't show anything. We're tracking this feature request in issue #250.

Community questions

Was this page useful?

Questions about this page? or post a community question.