The Flutter Session Replay Tool: UXCam

Quick summary

If you're reading this, you're probably trying to see what users actually do inside your Flutter app: where they hesitate, which taps don't register, and why they abandon a flow halfway through. There's an even higher chance you're looking for a session replay tool that actually works with Flutter, which draws every widget with its own rendering engine instead of using native views.

The good news: This guide explains what session replay is, how it works in Flutter, and how to set it up with UXCam. A single Flutter SDK records sessions in your iOS and Android apps and in Flutter Web, so one integration covers mobile and the web. You'll also see how to name screens, mask sensitive widgets, and connect replays to events and crashes, so every recording answers a real question.

What is a session replay?

A session replay is a visual, step-by-step reconstruction of how users navigate your app. It captures every tap, swipe, scroll, and screen transition so teams can see the real user journey, not just metrics.

Instead of guessing where friction happens, session replay lets you watch the actual experience: hesitation before tapping a button, broken flows, confusing UI elements, or moments of frustration. For Flutter apps, this is especially important because widgets can behave differently across devices.

UXCam turns these interactions into secure, privacy-safe recordings that help teams debug issues, improve flows, and build better features with confidence.

How session replay works in Flutter

Flutter doesn't build its interface from native iOS or Android views. It paints every widget itself, which is why analytics tools that read native view hierarchies often miss what Flutter users actually see. UXCam's Flutter SDK, the flutter_uxcam package on pub.dev, records what's on screen instead, together with the interaction data that explains it.

On iOS and Android, the plugin wraps UXCam's native SDKs. Each recorded session includes:

• Screen video: A visual recording of what the user saw, including widget rebuilds, transitions, and dialogs.

• Gestures: Taps, long presses, swipes, scrolls, and back navigation, shown on the replay and on the session timeline.

• Screen names: Route names from Flutter's Navigator, or names you tag yourself, which split every replay into screens with the time spent on each.

• Events and user properties: The custom events you log and the attributes you attach to users, pinned to the moment they happened.

• Issues: Crashes, UI freezes, and rage taps, flagged automatically so you can jump straight to them.

Sessions upload when the app moves to the background and appear in your UXCam dashboard shortly after. Recent SDK releases also skip frame capture while a list is actively scrolling, which keeps recordings reliable on long, fast-moving screens. On Flutter Web, the same plugin records the canvas Flutter draws your app into, so web sessions are video-based as well (more on that below).

One thing to plan for early: Flutter doesn't hide anything from recordings by default. Sensitive widgets, such as password fields or card numbers, need to be wrapped in UXCam's OccludeWrapper, which hides them on the device before anything is uploaded. The privacy section below walks through the options.

How to set up session replay in Flutter with UXCam

Before you start, you'll need a UXCam account, a Flutter project, and an app key from your dashboard. Mobile builds require iOS 12.0 or later and Android minSdkVersion 21 or later. Flutter Web uses its own web app key, and you don't need to add UXCam's standalone web SDK, because the Flutter plugin handles both.

1. Add the package: Run flutter pub add flutter_uxcam in your project. This adds flutter_uxcam to your pubspec.yaml, and the same package serves iOS, Android, and Flutter Web.

2. Initialize UXCam once: Import package:flutter_uxcam/flutter_uxcam.dart and call FlutterUxcam.startWithConfiguration() with a FlutterUxConfig in the initState of your root StatefulWidget, so recording starts with the app. On mobile, call FlutterUxcam.optIntoVideoRecording() first and pass your mobile app key. On the web, pass your web app key. A kIsWeb check lets one codebase pick the right key.

3. Decide how screens get named: For most Flutter apps, UXCam recommends setting enableAutomaticScreenNameTagging to false and adding FlutterUxcamNavigatorObserver to your navigator. The next section explains why.

4. Run the app and check your first session: On a device or emulator, move through a few screens and send the app to the background. The session appears in your dashboard within minutes. On the web, look for the “[UXCam] connected successfully” message in the browser console, then close the tab; web sessions usually show up within 5 to 10 minutes.

5. Customize in the dashboard: Rename screens, set up occlusion rules, define the events that matter, and save the filters your team will use most.

For code samples and every configuration option, see the UXCam Flutter quick start and the full Flutter integration guide.

How to tag Flutter screens for clearer replays

A replay is only as useful as the screen names around it. Screen names split each session into blocks on the timeline, drive screen-level filters, and feed heatmaps, funnels, and journey analysis. Because Flutter handles navigation inside the widget tree, it's worth deciding how screens get named before you ship.

UXCam's screen tagging guide recommends FlutterUxcamNavigatorObserver for most apps, with automatic screen name tagging turned off. Automatic tagging was designed for native UIKit and Android Activity hierarchies, so it can misread Flutter route changes, while the observer listens to the Navigator directly. Add it to navigatorObservers on your MaterialApp if you use Navigator 1.0, or to your router's observers if you use Navigator 2.0 through a package like go_router. Name your routes too, since unnamed routes tend to show up as a bare slash.

Bottom navigation bars and tab bars need one extra step. The observer doesn't see tab switches, so every tab would otherwise be recorded under the parent screen's name, and your timeline, heatmaps, and funnels would blend them together. Call FlutterUxcam.tagScreenName() with a name like Home Tab in your BottomNavigationBar onTap callback or in a TabController listener, and the replay shows which tab the user was really on. Manual tagging with tagScreenName() also covers custom routing setups where no observer fits.

Flutter Web follows the browser's rules, so pages are identified by URL rather than by route name. Call usePathUrlStrategy() before you start UXCam so your URLs are clean paths instead of hash fragments, then use page definition rules in the dashboard to rename pages and group dynamic paths such as /products/123 under one name.

Whichever approach you use, check that each screen appears in the dashboard with a duration above zero seconds. A 0s screen usually means two tags fired in the same frame, often because automatic and manual tagging are both switched on.

Session replay for Flutter Web

UXCam's Flutter support isn't limited to phones. The flutter_uxcam plugin also records Flutter Web apps, so teams that ship one Flutter codebase to mobile and the browser can review both kinds of sessions in the same UXCam dashboard. You initialize it with a web app key, and your UXCam calls for screen tagging, events, and user properties carry over unchanged.

Flutter Web replays are video-based rather than DOM-based, because UXCam captures the canvas that Flutter draws your app into. That has a few practical effects. You see tap indicators instead of mouse movement, the same way gestures appear in mobile replays. A replay can open with a brief white screen before your first frame appears, while gestures, screens, and events stay aligned with the video from the start. And iframes embedded through HtmlElementView show up blank, because the browser renders them outside Flutter's canvas.

The core experience is shared across platforms: session recording, screen tagging, events, and user properties all work on Flutter Web, and standard OccludeWrapper masking is supported too. A few APIs are mobile-only, including recording controls such as pause and resume, crash and ANR handling, the opt-in and opt-out consent methods, and debug logging. Calling them on the web is safe because they do nothing there, but wrapping them in a kIsWeb check keeps your intent clear. Heatmaps and Tara, UXCam's AI analyst, aren't available for Flutter Web sessions yet, and the Flutter Web platform support page keeps the current feature matrix.

Benefits of UXCam's session replay for your Flutter app

For apps built with Flutter, UXCam’s session replay offers a powerful way to understand user behavior and optimize performance. Here’s what you get:

• Effortless integration: UXCam's Flutter SDK is one lightweight package for iOS, Android, and Flutter Web. Setup takes a few lines of code, and recording starts without tagging every widget.

• Screen tracking that follows Flutter navigation: FlutterUxcamNavigatorObserver picks up route changes from Navigator 1.0 and 2.0, so replays split into named screens without extra instrumentation.

• Privacy-first design: OccludeWrapper and dashboard occlusion rules hide sensitive widgets on the device, so that data never reaches UXCam's servers. You get the insights you need without compromising user privacy or app security.

• Issues tied to real sessions: Crashes, UI freezes, and rage taps are flagged inside the replay, so you can watch exactly what led up to them.

Overview of UXCam’s session replay for Flutter

UXCam provides high-quality session replays backed by powerful filters, tagging, notes, and event analytics. Teams can quickly find sessions that matter, watch only the relevant moments, and collaborate on issues directly inside the dashboard.

Every session includes essential user details, such as, location, device, crashes, UI freezes, and custom properties, giving teams full context before reviewing the replay.

Key components of a UXCam session

Here are the details you’ll find in a UXCam session recording

Session information bar

The top panel of the replay shows user identification (Alias or User ID), location, device, session time, and labels. If a crash or UI freeze occurs, UXCam flags it automatically. Clicking the indicator reveals technical logs so developers can diagnose the issue quickly.

Detailed timeline (Activity Tab)

UXCam’s timeline visualizes the full journey across screens and actions. Blocks represent screens, and each block shows how long a user stayed. Clicking any interaction jumps directly to that point in the replay, making it easy to investigate friction. Smart event icons highlight taps, gestures, rage taps, or custom events, allowing you to navigate sessions without watching the entire recording.

Advanced filters to find key sessions

UXCam’s filters help you surface the right sessions instantly. You can narrow results by:

• User actions (taps, swipes, scrolls)

• Technical issues (crashes, freezes)

• User attributes (device, location, OS)

• Session characteristics (duration, engagement level)

You can also exclude internal testers and filter for frustration signals like rage taps or dead taps. This helps Flutter teams understand exactly where usability issues occur. 

Tag sessions

UXCam enables you to easily identify and investigate user issues with its tagging feature. By adding custom tags, like "crash" or a specific error message, it's easier to filter through high volumes of sessions for the ones that contain relevant information about potential problems your users are experiencing. Additionally, it improves cross-functional collaboration between product, design, QA, and engineering teams helping stay aligned on the same issue. 

Leave notes to align your team

With notes, you can highlight issues that a user may have experienced or provide suggestions for improvement directly on specific parts of replay sessions. Plus, team collaboration is made simpler as well; share your notes with other members and give them meaningful context about observed behaviors, even if they're remote.

Analyze events

Event analysis lets you jump from a custom event directly to the moment it happened in the replay. This gives you faster insight into user behavior around key actions, purchases, taps, onboarding steps, failed attempts, etc. You can watch sessions tied to that event or pivot into reports to analyze trends. This dual functionality empowers you to gain insights into user interactions with specific events in their app swiftly and effectively. 

Privacy and security for Flutter session replay

UXCam is committed to the highest standard of user data privacy and security. With IBM's Cost of a Data Breach Report 2026 putting the global average cost of a breach at a record $4.99 million, built-in privacy protections are an essential safeguard, not an optional extra.

Flutter doesn't occlude anything by default, so masking is something you set up on purpose. The simplest tool is OccludeWrapper: pass any widget as its child, from a single Text widget to a whole Column, and UXCam hides it in the recording. Occlusion happens on the device before the session is uploaded, which means masked content never reaches UXCam's servers.

For entire screens, such as login or payment, you can apply a blur or a solid overlay with FlutterUXBlur or FlutterUXOverlay, either at runtime or through your configuration with a list of screen names. Both hide gestures on those screens by default, which is what you want around password inputs. If you'd rather not ship code for it, the video recording privacy settings in your UXCam dashboard let you record, occlude, or blur all screens, or set rules for specific screens. These screen-level options apply to iOS and Android; on Flutter Web, OccludeWrapper is the supported approach.

Consent and identity matter too. If your app asks permission before recording, call FlutterUxcam.optIntoVideoRecording() or optOutOfVideoRecording() to respect each user's choice. Identify users with an internal ID rather than an email address or phone number, and keep personal data out of event and user properties. UXCam is compliant with GDPR and CCPA, and the occlusion guide covers each option in detail.

Add events, user identity, and crash context

Screens tell you where users go; events show what they do. UXCam's event tracking guide suggests a focused set of 5 to 15 events around flow milestones, key feature use, errors, and cancellations. Log them with FlutterUxcam.logEvent(), or use logEventWithProperties() to attach up to 20 properties such as plan or price. Every event appears as a marker on the replay timeline, so filtering for something like Payment_Failed takes you straight to the moment it happened.

Two signals come without any code. A rage tap is recorded when a user taps three or more times within 300 milliseconds in the same spot, and a UI freeze is recorded when the main thread is blocked for two seconds or more. Filtering for either is one of the fastest ways to find frustrated users in a large Flutter app.

When a support ticket names a specific user, you want their sessions, not a random alias. FlutterUxcam.setUserIdentity() replaces UXCam's default alias with your own user ID, and setUserProperty() lets you add up to 100 attributes, such as subscription type or role, that become filters and segments for your replays. The user properties guide has the details.

On iOS and Android, set enableCrashHandling to true in your FlutterUxConfig to capture crashes and ANRs alongside the session, and forward errors from FlutterError.onError to UXCam so handled exceptions show up in context as well. The crash handling guide shows the full setup. Crash capture is part of the mobile SDK, so it doesn't apply to Flutter Web.

Performance impact and recording control

Many developers ask the same question before adding any SDK: “Will session replay slow down my Flutter app?”

UXCam is built to stay out of the way of Flutter's rendering pipeline. It captures frames and gesture data without blocking the UI thread or slowing animations, and recent releases skip capture during active scrolling to keep recordings smooth and reliable. You can read more about how the SDK is engineered in why UXCam has one of the best performing SDKs.

Control what gets recorded

The recording control APIs give you fine-grained control on mobile. FlutterUxcam.pauseScreenRecording() and resumeScreenRecording() stop video capture on a sensitive screen while the session itself continues, stopSessionAndUploadData() ends a session on demand, and isRecording() tells you the current state. You can also start UXCam conditionally, for example only after a user has given consent.

Keep test sessions out of production data

To keep development and QA sessions out of your production data, start UXCam only in release builds or when your environment flag says production. Combined with dashboard filters that exclude internal testers, this keeps your replays focused on real users and your analytics free of test noise.

Common Flutter issues solved using session replay

Session replay helps teams diagnose Flutter-specific problems that are hard to catch with logs or analytics. These include;

• Gesture failures: Sometimes taps don’t register due to gesture detector conflicts or invisible overlays.

• Layout overflow issues: On certain device sizes, Flutter widgets overflow or misalign. Session replay reveals exactly where.

• Keyboard UI problems: The keyboard often covers input fields in Flutter apps. Replays show how users struggle with forms.

• Scroll and list issues: Infinite scroll, sticky headers, and custom list views sometimes behave incorrectly.

• Silent UI freezes: Flutter can freeze due to async operations blocking the UI thread, replays show the moment it happens.

• Onboarding drop-offs: Session replay uncovers why users abandon during multi-step flows.

• Browser-specific layout issues: If you ship Flutter Web, replays show where layouts break at certain window sizes or where input behaves differently in the browser.

Session Replay Best Practices in Flutter

To get the most value from session replay, follow these recommended practices for setup, analysis, and cross-team collaboration.

1. Mask sensitive widgets early

Privacy should be configured from the start. Wrap sensitive widgets, such as password inputs, payment details, or personal information forms, in OccludeWrapper, and add blur or overlay rules for whole screens like checkout. Masking ensures that protected data never appears in session replays, keeping recordings safe, compliant, and suitable for team-wide review.

2. Track key events for context

Session replay becomes far more meaningful when paired with event data. By tracking interactions like button taps, form submissions, feature usage, and error states, you give your team the context needed to understand why users behave the way they do. Combining replays with event metadata makes it easier to verify feature adoption, troubleshoot failed actions, and validate design decisions.

3. Use funnels to diagnose drop-offs

Funnels reveal where users abandon important workflows such as onboarding, checkout, or sign-ups. When you connect these funnels to session replays, you can jump directly into real sessions where drop-offs happen. This combination helps you understand the exact friction points users encounter and why they fail to complete certain tasks, allowing for precise UX improvements.

4. Review sessions from different devices and platforms

Flutter apps often behave differently across devices with varying screen sizes, processing power, and refresh rates, and Flutter Web adds browsers and window sizes to the mix. Watching replays from small screens, tablets, low-end devices, high-refresh displays, and desktop browsers helps you identify layout issues, rendering anomalies, or performance slowdowns that you won’t see in controlled internal testing environments. This ensures your app works smoothly for your entire user base, not just the devices used during QA.

5. Involve product, design, and QA teams

Session replay is most effective when used across teams, not just engineering. Product managers can validate whether new features work as intended. Designers can observe real-world usability and interaction patterns. QA can pinpoint bugs faster by watching replays instead of reproducing complex steps. When the whole team collaborates around session data, decisions become faster, clearer, and grounded in actual user behavior.

Create a better user experience with UXCam

UXCam gives Flutter teams a clear view of how users interact with their apps on iOS, Android, and the web, from session replays and event tagging to privacy-first analytics. Its seamless Flutter integration, intuitive filters, and quick setup make it a powerful tool for uncovering friction and improving usability.

Instead of guessing what users experience, you can watch sessions, track detailed gestures, and see how real people navigate your app. Combined with heatmaps, funnel analysis, and AI-driven insights, UXCam turns complex behavior data into clear, actionable insights that help you optimize every user journey.

Ready to improve your product experience? Try UXCam for free today.

You might also be interested in these;

10 Session Replay Tools for Mobile for Product Teams & Devs

Mobile app analytics tool for Flutter

Heatmap tool for Flutter

Top mobile app analytics tools

Best tool for Flutter crash reporting

.NET MAUI vs. Flutter: Guide to choosing the right framework

Flutter performance monitoring - Best tools and techniques