React Native Session Replay with UXCam: Setup Guide

If you're reading this, you probably want to see what users actually do inside your React Native app. Where do they hesitate? Which taps don't register? Why do they leave a flow halfway through? There's an even higher chance you've tried a tool built for native apps and found it doesn't quite fit a React Native codebase.

The good news: This guide explains what session replay is, how it works in React Native, and how to set it up with UXCam. One SDK records your iOS and Android apps, Expo projects included. The same UXCam account also covers your website through UXCam's web SDK. You'll learn how to name screens with React Navigation, mask sensitive views, and link every replay to events, users, and crashes. That way, each recording answers a real question.

What is session replay?

A session replay is a visual, step-by-step reconstruction of how a user moves through your app. It captures every tap, swipe, scroll, and screen transition. Your team sees the real user journey instead of a row of metrics.

Instead of guessing where friction happens, you watch the actual experience. You see the hesitation before a button, the form field the keyboard covers, and the third tap on a button that isn't responding. This matters even more in React Native. The same JavaScript renders different native components on iOS and Android, so a screen that works on a new iPhone can behave very differently on a mid-range Android phone.

UXCam turns these interactions into privacy-safe recordings. Teams use them to debug issues, improve flows, and ship features with confidence. You also don't have to guess which recordings to watch. Tara, UXCam's AI analyst, looks across your sessions and tells you what changed and where users struggle. The replays are the evidence.

How session replay works in React Native

React Native draws real native views, but your screens, state, and navigation are JavaScript. Say a user moves from Home to Product Details in React Navigation. Nothing on the native side announces a new screen, the way a new view controller or Activity would in a fully native app. That's why tools that infer screens from the native lifecycle often record a React Native app as one long screen.

UXCam's React Native SDK is the react-native-ux-cam package. It wraps UXCam's native iOS and Android SDKs to record what's on screen. You name the screens from your JavaScript code.

Each recorded session includes:

• Screen video: What the user saw, including transitions, modals, and the keyboard.

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

• Screen names: The names you tag from JavaScript. They 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: Native crashes, ANRs, UI freezes, and rage taps, flagged automatically so you can jump straight to them.

A session ends when the app moves to the background, and that's also when it uploads. It shows up in your UXCam dashboard within about a minute. The SDK has supported the React Native New Architecture since version 6.0.0. Recent releases also improved how WebView content is captured.

Plan for two things early. First, automatic screen tagging isn't reliable in React Native, so you'll tag screens yourself. With React Navigation, that takes a few lines. Second, only password fields and standard credit card inputs are masked automatically. Everything else shows in the replay until you hide it, and the privacy section below walks through the options.

How to set up session replay in React Native with UXCam

Before you start, you'll need a UXCam account and the app key from your dashboard. Your project should run React Native 0.68 or later, or Expo SDK 47 or later. Builds need an iOS deployment target of 12.0 or later and Android minSdkVersion 21 or later.

1. Add the package: Run npm install react-native-ux-cam, or yarn add react-native-ux-cam. Then run pod install in your ios folder to link the native iOS SDK.

2. Initialize UXCam once: Import RNUxcam from react-native-ux-cam and start it in a useEffect in your root App component. First call RNUxcam.optIntoVideoRecording(), which screen video needs on both iOS and Android. Then call RNUxcam.startWithConfiguration() with your app key. UXCam's React Native quick start also recommends two settings: enableAutomaticScreenNameTagging set to false and enableImprovedScreenCapture set to true.

3. Tag your screens: Call RNUxcam.tagScreenName() in each screen, usually inside React Navigation's useFocusEffect. The next section shows the patterns that work best.

4. Check your first session: Run the app on a device or simulator and move through three or four screens for about 30 seconds. Then send the app to the background. That ends the session and starts the upload, and the session appears in your dashboard within about a minute.

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

Nothing showing up? Turn on enableIntegrationLogging and tie it to __DEV__, so it stays off in release builds. Then check the native logs in Xcode's console on iOS and in Android Studio's Logcat on Android. They don't appear in Metro, VS Code, or Cursor, which catches a lot of React Native developers out.

Look for "Verification successful" and "Session uploaded". The React Native troubleshooting guide covers the most common causes. They range from a wrong app key to an app that never goes to the background during testing. For every configuration option and code sample, see the full React Native integration guide.

How to tag React Native 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 and drive screen-level filters. They also feed heatmaps, funnels, and journey analysis.

In React Native, screen names are something you set on purpose. Your screens are JavaScript components, so they don't fire the native lifecycle events that automatic tagging depends on. That's why UXCam's screen tagging guide rates automatic tagging as unreliable for React Native. It strongly recommends manual tagging, with enableAutomaticScreenNameTagging set to false.

With React Navigation, the simplest pattern is to call RNUxcam.tagScreenName() inside useFocusEffect, wrapped in useCallback. The tag then fires every time a screen comes into focus, including when users navigate back to it. Many teams wrap this in a small useScreenTracking hook and call it at the top of each screen.

Prefer to keep tagging in one place? Add an onStateChange handler to your NavigationContainer, read the current route name from a navigation ref, and tag it whenever it changes. Either way, use readable names like Product Details or Checkout Payment, not component names. Those are the names your product team will search and filter by.

Tabs and modals need one extra thought. Tag each tab screen separately, with a name like Home Tab. Otherwise every tab ends up under one parent screen, and your timeline, heatmaps, and funnels blend them together. Tag modals when they become visible, so they show up as their own screen.

Keep dynamic IDs out of names. Product Details - Electronics is a useful screen name. Product Details - 12345 turns one screen into thousands and fragments your data. If a screen's name depends on data you fetch, tag it once that data has arrived.

UXCam's navigation tagging guide covers other setups too. In Wix's React Native Navigation, componentDidAppear does the job. In Expo Router, you tag from your root layout using useSegments. For screens built on WebViews, the WebView tagging guide shows how to tag pages from URL changes. When the URL doesn't change, you can use a JavaScript bridge instead.

Whichever approach you choose, check the result in a debug session. Every screen should appear exactly once, with a duration above zero seconds, and no Unknown or component-name entries. A 0s screen usually means two tags fired in the same frame, often because of a re-render. Tags less than 300 milliseconds apart also collapse together, so debounce rapid tab switches.

Session replay in Expo apps

UXCam works in Expo projects with one condition: it can't run inside Expo Go. UXCam's SDK includes native iOS and Android code, and Expo Go can only load the native modules it ships with. So use a development build or EAS Build instead. That's how most production Expo apps are built anyway.

In practice, you install the EAS CLI and run eas build:configure. Then you add react-native-ux-cam with the same initialization code as above. Create a development build with eas build --profile development for iOS or Android, and start the dev server with npx expo start --dev-client. UXCam then initializes with full access to its native modules.

Two errors are worth knowing. If you see "RNUxcam is null" or "undefined", the app is running in Expo Go. If a build fails with a missing native module, run npx expo prebuild and build again.

Everything else in this guide applies unchanged. Tag your screens, mask sensitive views, and log the events that matter. Expo Router apps can do the tagging once in the root layout. UXCam's Expo installation guide has the full steps and a table of common Expo errors.

Benefits of UXCam's session replay for your React Native app

UXCam's session replay shows you how people use your React Native app on both platforms, from one integration. Here's what you get:

• Setup that fits React Native: One package for iOS and Android and a few lines in your root component. Recording starts without tagging every button, and the New Architecture and Expo development builds are supported.

• Screens that match your navigation: Tag screens from React Navigation, Expo Router, or Wix navigation. Replays then split into the screens your team actually talks about.

• Privacy on the device: Password and card fields are masked automatically. Dashboard rules, configuration occlusions, and view-level masking hide everything else before a session leaves the phone.

• Issues tied to real sessions: Native crashes, ANRs, UI freezes, and rage taps are flagged inside the replay. You can watch exactly what led up to them.

• Insights before you ask: Tara works on the same autocaptured data. It surfaces what changed and where users struggle, so you start from a finding instead of a blank session list.

Key components of a UXCam session

UXCam's session replay comes with filters, tags, notes, and event analytics. Your team can find the sessions that matter, jump to the right moment, and work through issues together in the dashboard. Each session also shows who the user is: location, device, OS and app version, crashes, UI freezes, and your custom properties. You have the context before you press play.

Session information bar

The top panel of the replay shows the user's alias or user ID, location, device, session time, and labels. If a crash or UI freeze occurred, UXCam flags it automatically. Click the indicator to open the technical logs, so developers can diagnose the issue quickly.

Detailed timeline (Activity tab)

The timeline shows the full journey across screens and actions. Blocks represent your tagged screens, and each block shows how long the user stayed. Click any interaction to jump to that point in the replay. Icons mark taps, gestures, rage taps, and custom events, so you can move through a long session without watching all of it.

Advanced filters to find key sessions

Filters surface the right sessions instantly. You can narrow results by:

• User actions (taps, swipes, scrolls, and the screens visited)

• Technical issues (crashes, UI freezes)

• User attributes (device, location, OS, app version, and your custom properties)

• Session characteristics (duration, engagement level)

You can also exclude internal testers. Filter for frustration signals such as rage taps and unresponsive gestures to see where usability issues occur, and on which platform.

Tag sessions

Tags help you find and group sessions around a problem. Add a tag like "checkout bug" or a specific error message. Anyone on the team can then filter thousands of sessions down to the ones that show it. Tags also keep product, design, QA, and engineering aligned on the same issue.

Leave notes to align your team

Notes let you flag a moment right on the replay timeline, describe what went wrong, or suggest an improvement. Teammates who open the session later get that context immediately, even from another time zone.

Analyze events

Event analysis takes you from a custom event straight to the moment it happened in the replay. It's the fastest way to understand behavior around key actions, such as purchases, onboarding steps, or failed payments. Watch the sessions tied to an event, or pivot into reports to see the trend behind it.

Privacy and security for React Native session replay

Session replay records what users see, so build privacy into the integration from day one. UXCam masks content on the device. Anything occluded is hidden before the session uploads, so it never reaches UXCam's servers. UXCam is compliant with GDPR and CCPA, and the security and privacy page explains how data is stored and processed.

Out of the box, TextInput fields with secureTextEntry and standard credit card inputs are masked automatically. Everything else stays visible in the replay until you hide it, from names and addresses to account balances. Plan masking alongside screen tagging.

The quickest option needs no code at all. In your UXCam dashboard, open Settings and then Video Recording Privacy. Choose Record, Occlude, or Blur for every screen or for specific screens. You can adjust the blur radius and choose whether gestures are recorded. Dashboard rules take priority: a screen-specific rule wins over a global one, and both win over rules set in the SDK.

In code, UXCam recommends putting privacy rules in your configuration, so they're active from the first frame. The occlusions array takes three rule types: an overlay with a color, a blur with a radius, or a rule that hides all text fields. Each rule gets a list of screen names and a hideGestures option. The type names are OcclusionType.Overlay, OcclusionType.Blur, and OccludeAllTextFields.

This is where good screen names pay off a second time. One rule for Login Form and Payment Details covers those screens wherever users reach them. There's one platform difference to know. On Android, the screen list is ignored for OccludeAllTextFields, so it applies to every screen, and per-screen scoping only works on iOS.

For a single component, pass its ref to RNUxcam.occludeSensitiveView(), for example on a card number or ID field. Custom inputs that wrap TextInput need to forward the ref to the underlying view. The current SDK also includes a UXCamOccludedView component. Wrap it around any sensitive region, and it registers the occlusion through the native view's lifecycle without waiting for a JavaScript mount callback.

Want to hide every text input while a sensitive screen is open? Call RNUxcam.occludeAllTextFields(true), and switch it off again when the user leaves. The occlusion guide and the view-level occlusion guide have examples for forms, modals, and dynamic lists.

WebViews need their own plan. You can add the uxcam-occlude class to sensitive HTML elements, or inject CSS when you don't control the page. But element-level masking drops for about a second while the WebView loads a new page. It also can't see inside cross-origin iframes, such as payment widgets or SSO forms.

For payment, health, and other regulated flows, occlude the whole WebView instead by passing its ref to occludeSensitiveView. That mask is applied natively to the container and stays in place across navigations. You can still log an event for each step to keep funnel visibility. The WebView occlusion guide explains the trade-offs.

Sometimes no frames should exist at all, for example during biometric authentication. Call RNUxcam.pauseScreenRecording() there, and resumeScreenRecording() afterwards. The session continues, but nothing is captured while recording is paused. Prefer occlusion when you still want gestures and timing for that screen.

Consent matters too, and the SDK opts users in by default. RNUxcam.optOutOverall() stops and deletes the current session and disables recording for that user. To turn recording back on, call optInOverall(), and optInOverallStatus() returns the current state.

The opt-out setting resets after a reinstall. So store the user's choice and apply it at startup, or only start UXCam once a user has agreed. The opt-in and opt-out guide shows a full consent flow. Identify users with an internal ID rather than an email address or phone number, and keep personal data out of event and user properties.

Add events, user identity, and crash context

Screens tell you where users go; events show what they do. RNUxcam.logEvent() takes an event name and, optionally, up to 20 properties such as plan or price. Values can be strings, numbers, or booleans.

Names and property keys are case sensitive, so agree on a convention early. UXCam's event tracking guide recommends snake_case names like checkout_completed. Keep dynamic values in properties, not in the name. Every event appears as a marker on the replay timeline, so filtering for payment_failed takes you straight to the moment it happened.

Some signals need no code at all. Rage taps and UI freezes are detected automatically and logged as events. A UI freeze is recorded when the main thread stops responding for two seconds or more. Filtering for either is one of the fastest ways to find frustrated users in a large app.

Because UXCam autocaptures gestures and screens, you can also define smart events later in the dashboard, without shipping a new release.

When a support ticket names a specific user, you want their sessions, not a random alias. RNUxcam.setUserIdentity() replaces the alias UXCam generates from the install ID with your own user ID. Call it as soon as a user logs in.

RNUxcam.setUserProperty() adds attributes such as subscription type or role. You can use up to 100 property keys per app, and they become filters and segments for your replays. For facts about a single session, such as an A/B test group or a QA flag, use RNUxcam.setSessionProperty() instead. The user properties guide has the details.

On the crash side, UXCam captures native iOS and Android crashes automatically, along with ANRs and UI freezes. Each one links to its replay under Issues in the dashboard.

JavaScript exceptions work differently. The React Native runtime handles them before they reach the native layer, so they don't appear as crashes. The React Native SDK also has no reportExceptionEvent() call. UXCam's crash handling guide suggests a simple workaround instead.

Wrap React Native's global error handler, ErrorUtils.setGlobalHandler. In your wrapper, log a js_error event with the error's name, its message, and whether it was fatal. Then pass the error on to the previous handler. The same logEvent call works in an error boundary's componentDidCatch or in a catch block. Filter for js_error, and you get the replay behind every JavaScript error.

Do you also use Firebase Crashlytics or another crash reporter? Then decide at startup which tool owns crashes, because two crash handlers can conflict. To leave crashes to the other tool, set enableCrashHandling to false in UXCam's configuration. On iOS, this also turns off ANR and UI freeze capture.

Either way, RNUxcam.urlForCurrentSession() returns a link to the current session. Attach it to a crash report, a bug ticket, or a support conversation.

Performance impact and recording control

Many developers ask the same question before adding any SDK: "Will session replay slow down my React Native app?"

UXCam records in its native iOS and Android SDKs, not in your JavaScript bundle. It uploads sessions when the app goes to the background, not while users are interacting. You can read more about how the SDK is built in why UXCam has one of the best performing SDKs. As with any SDK, measure the effect yourself before a wide rollout, using a release build on a low-end Android device.

Control what gets recorded

Sessions end when the app goes to the background. The recording control APIs give you finer control on top of that.

RNUxcam.stopSessionAndUploadData() ends and uploads a session on demand. That's useful when a user finishes a flow without leaving the app. It also accepts a callback for when the upload is done.

After a stop, startNewSession() starts recording again, 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

Use separate app keys for development and production, as UXCam's React Native guide recommends. Load them from environment variables or your CI pipeline, and never commit them to the repository. Alternatively, start UXCam only in release builds.

Add dashboard filters that exclude internal testers, too. Your replays stay focused on real users, and your analytics stay free of test noise.

Common React Native issues solved using session replay

Some React Native problems are hard to catch with logs or analytics alone. Session replay helps you diagnose them, including:

• Taps that don't register: Overlapping Pressable areas, an invisible view positioned on top of a button, or a touch target that's too small. Rage taps on the replay show exactly where users keep trying.

• Keyboard covering inputs: KeyboardAvoidingView behaves differently on iOS and Android. Replays show users scrolling and tapping around to reach a hidden field.

• Gesture conflicts: A swipeable row inside a scroll view, or a back swipe that fights a horizontal carousel. Users end up repeating the same gesture.

• List behavior: Blank areas in a FlatList during fast scrolling, or images that load slowly on older Android devices.

• Freezes and slow screens: Heavy work on the main thread can lock the interface. UXCam flags the UI freeze, and the replay shows what the user was doing when the app stopped responding.

• Platform differences: The same JavaScript renders different native components. Date pickers, modals, and permission prompts can behave differently on iOS and Android.

• Regressions after an over-the-air update: If you ship JavaScript changes with EAS Update, the app version doesn't change. Record the update ID as a session property and compare sessions from before and after.

• Onboarding drop-offs: Replays show why users abandon multi-step flows, from confusing copy to a permission prompt at the wrong moment.

Session replay best practices in React Native

These practices help you get the most from session replay, from setup to analysis to teamwork.

1. Tag screens and mask sensitive views before launch

Screen names and privacy rules are easiest to get right before your first production release. Tag every screen and check that each one appears once with a real duration. Then record a debug session through your login, payment, and profile flows, and confirm nothing sensitive is visible. Test on both iOS and Android, since some occlusion options behave differently per platform.

2. Track key events for context

Session replay is far more useful when it's paired with event data. Track a focused set of actions that define success in your app, such as sign-ups, purchases, and failed payments. Add the JavaScript errors you log from your global handler. With event properties next to the replays, it's easier to check feature adoption, debug failed actions, and validate design decisions.

3. Use funnels to diagnose drop-offs

Funnels show where users abandon important flows such as onboarding, checkout, or sign-up. Because UXCam connects funnels to session replay, you can jump from the step where users dropped off straight into their sessions and see the friction they hit. A conversion number turns into a specific fix.

4. Review sessions from both platforms and many devices

React Native apps often behave differently across screen sizes, processing power, and OS versions. Filter by platform and device, and watch replays from small phones, tablets, and older Android devices. You'll find layout issues, gesture conflicts, and slowdowns that internal testing on the latest hardware misses.

5. Let Tara point you to the sessions worth watching

Watching sessions at random doesn't scale. Tara, UXCam's AI analyst, works on the data UXCam already captures. It tells you what changed after a release, which screens frustrate users, and which segments behave differently. The relevant sessions come attached. If your team works in AI assistants such as Claude or Cursor, UXCam's MCP server brings the same data there.

6. Involve product, design, and QA teams

Session replay works best when every team uses it, and engineering is only the start. Product managers can check whether new features work as intended. Designers can watch real-world interaction patterns. QA can reproduce bugs from the replay instead of guessing the steps. When everyone works from the same sessions, decisions get faster and rest on actual user behavior.

Create a better user experience with UXCam

UXCam gives React Native teams a clear view of how users move through their iOS and Android apps. The same account covers your website through UXCam's web analytics. Tara surfaces what changed and where users struggle before you ask. Session replays and heatmaps show you why, and dashboards and funnels measure whether your fixes worked.

Setup takes a few lines in your root component, a tag per screen, and a privacy pass over sensitive views. Get started with UXCam and watch your first React Native session today.

You might also be interested in these:

Heatmap tool for React Native apps

React Native analytics: a guide for mobile app teams

React Native crash reporting: best tools and techniques

React Native performance monitoring: best tools and techniques

10 session replay tools for mobile apps

Top mobile app analytics tools