Getting Started with Fullstory for Flutter Mobile Apps

Fullstory for Flutter captures sessions from your Flutter apps, including privacy-first visual session replay of your Flutter UI. Data from your Flutter apps can be combined in Fullstory with sessions from your website and other mobile apps to provide a comprehensive view of your digital experience.

This article will cover the following:

• Setup
  • Install the SDK
• Using Fullstory's Advanced Features
• Limitations and Known Issues

Setup

To set up Fullstory for your Flutter app, install and configure the fullstory_flutter library. This captures your Flutter sessions, including privacy-first visual session replay of your Flutter UI.

Install the SDK

Fullstory for Flutter captures user events, session details, and privacy-first visual session replay to help you understand your users' experience with your app. This data can be used to analyze key metrics, understand user journeys, and identify drop-off points in your most important user funnels.

See Fullstory for Flutter Mobile Apps - API Overview for a list of all supported API methods for Flutter. In addition to the data captured via those API methods, Fullstory automatically captures the following for Flutter apps:

• Session metadata (e.g. device details, OS, location, app version, etc.)
• Navigate events at top-level FlutterViewController/FlutterActivity
• Network and Console capture
• Visual capture of parts of the app built via a native mobile framework

Follow the instructions below to install and configure fullstory_flutter via pub.dev.

1. Install the fullstory_flutter Dart library by running the following command in the root directory of your Flutter app:

   flutter pub add fullstory_flutter

   This also installs the Fullstory CocoaPod for iOS apps. The Android library requires separate installation.

2. Follow the guides below to configure this for your Android or iOS app.

   • Android Apps: Install and configure the Android library by following Getting Started with Android Data Capture.

     Note: Follow Step 5 for Android (Subclass from Application), as the default Flutter setup does not work. Ensure the Android SDK version in pubspec.yaml matches the Flutter version—for example, if Flutter is 0.70.1, Android should be 1.70.1.

   • iOS Apps: Configure iOS starting from Step 1: Adding the Fullstory framework via CocoaPods Pod > Add the Build Phase in Getting Started with iOS Data Capture. In Step 1, skip the Add the Plugin step found under the via CocoaPods Pod instructions and begin immediately with the Add the Build Phase instructions.

   Note: If you add your Flutter code to an existing Android or iOS app as an add-to-app module, follow the directions above, applying Android and iOS steps to your native apps, not the Flutter module. When building the Flutter module for Android, you may need the following additional options when running flutter build aar (note: Flutter's -P flag requires a space, unlike Gradle's): -P shrink=false is needed if you get the error Execution failed for task ':flutter:minifyReleaseWithR8'—this option skips the minification phase for release builds, which is currently broken for plugins like Fullstory's. -P fsTarget=1.56.0 (or your installed version) is needed if you encounter errors due to a version mismatch between your Android and Flutter Fullstory plugins.

3. Enable session replay. In your app's main.dart (or wherever the app is started):
   • Add import 'package:fullstory_flutter/fullstory_flutter.dart';.
   • Replace runApp($YourAppHere$) with runFullstoryApp($YourAppHere$).
   • If you use runWidget, replace it with runFullstoryWidget. Please contact us if you encounter issues with runFullstoryWidget.
   • If you use WidgetsFlutterBinding.ensureInitialized(), replace it with FullstoryBinding.ensureInitialized().
4. If you build your release app with --obfuscate, enable obfuscation support before building or Unmasking will not work.
5. Build and run your app, then verify that a session is captured in Fullstory.

Using Fullstory's Advanced Features

See the sections below for additional configuration options.

Identifying users

Associate your own user identities and properties with Fullstory sessions. See Identify Users and Set User Properties for details.

Custom classes and attributes

Use FSCustomAttributes to add custom classes or attributes to a widget, or use the FSMask, FSUnmask, and FSExclude convenience widgets to apply privacy rules to a subtree. See Classes and Attributes for usage details and examples.

WebView support

Some packages, such as WebView for Flutter, require additional configuration to enable WebView support in session replay. Other packages, such as InAppWebView, do not have this requirement by default.

Flutter disables JavaScript injection on all WebViews it creates by default. To allow Fullstory to include Flutter WebViews in session replay, call the following on each WebViewController you want to capture:

controller.setJavaScriptMode(JavaScriptMode.unrestricted)

Additional data capture options

To enable additional data capture options, such as pages and network requests, see the Fullstory for Flutter developer documentation.

Capturing images

Image and icon capture is available as an opt-in feature in Fullstory for Flutter. To enable it, pass captureImages: true to runFullstoryApp():

runFullstoryApp(YourApp(), captureImages: true);

Logging

Log level is now configured via the native platform configuration:

• Android: Set the logLevel property in the fullstory block of your build.gradle file. See Android Configuration.
• iOS: Set the LogLevel key in the Fullstory dictionary in your Info.plist file. See iOS Configuration.

Obfuscation support

If you use --obfuscate to obfuscate your release app, follow these steps to see unobfuscated selectors in replay. This is necessary for Unmasking to work.

On Android, the Fullstory Gradle plugin picks up the mapping file automatically, so only step 2 below is required. On iOS, you must also complete step 1 so the Fullstory iOS SDK knows where to find the mapping file.

1. iOS only: Before building, set an environment variable so the Fullstory iOS SDK can find the mapping file:

   export FS_FLUTTER_OBFUSCATION_MAP=/path/to/file.json

   Note: The path must be an absolute path, not a relative path.

2. Android and iOS: When building, pass the following additional flag to save the obfuscation map:

   --extra-gen-snapshot-options=--save-obfuscation-map=/path/to/file.json

Disable obfuscation support

To disable obfuscation support, use the following build-time configuration:

• Android: Pass -P flutterSelectorDeobfuscationEnabled=false.
• iOS: Do not set FS_FLUTTER_OBFUSCATION_MAP.

Limitations and Known Issues

Fullstory's Flutter support provides privacy-first visual wireframe replay. Developers should be aware of the following limitations and known issues.

Limitations

Note the following limitations for Fullstory Flutter features:

• Image and icon capture is available as an opt-in feature via the captureImages parameter on runFullstoryApp(); see Capturing images. It is expected to become enabled by default in a future release.
• Watched elements are not supported.

Known Issues

Fullstory's Flutter support has the following known issues:

• Not compatible with tools and frameworks like Patrol which also use custom bindings. Please contact us to determine a way to combine our binding with your framework's.
• Apps which have multiple FlutterViews on screen at the same time aren't supported yet. Please contact us if you use multiple FlutterViews.
• Flutter views cannot be unmasked using selectors for native views. Use a RootWidget or similar instead.
• Flutter Web is not supported.
• The Flutter SDK may emit a warning about lack of built-in Kotlin support for Flutter apps built with Flutter versions earlier than 3.44. This warning is expected and will be resolved in a future Fullstory release.