React Native Session Replay installation
Contents
- 1
Install the packages
RequiredInstall the PostHog React Native library, its dependencies, and the session replay plugin:
Plugin renamed in 4.47.0+@posthog/react-native-plugin(>= 2.0.1) is the renamedposthog-react-native-session-replayplugin — it was renamed inposthog-react-native4.47.0+ and now also powers native error tracking. If you're on aposthog-react-nativeversion earlier than 4.47.0, installposthog-react-native-session-replayinstead.SDK versionSession replay requires PostHog React Native SDK version 3.2.0 or higher. We recommend always using the latest version.
- 2
Enable session recordings in project settings
RequiredGo to your PostHog Project Settings and enable Record user sessions. Session recordings will not work without this setting enabled.
- 3
Configure PostHog with session replay
RequiredAdd
enableSessionReplay: trueto your PostHog configuration. Here are all the available options:App.tsxFor more configuration options, see the React Native session replay docs.
RequirementsRequires Android API 26+ and iOS 13+. Expo Go is not supported - use a development build. Session replay is only supported on Android and iOS platforms.
- 4
Watch session recordings
RecommendedVisit 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.
- 5
Next steps
RecommendedNow 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
iOS dependency resolution
The native plugin supports three additive iOS dependency paths:
- CocoaPods for the plugin and
posthog-ios. This remains the default path. - CocoaPods for the plugin, with
posthog-iosresolved through Swift Package Manager. - React Native's experimental full Swift Package Manager integration, with no CocoaPods. PostHog verifies an iOS-only React Native 0.87.1 app with React Native Community CLI 20.2.0. This path requires
@posthog/react-native-plugin2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target.
See iOS dependency paths for the React Native native plugin for the requirements and setup steps. This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate full Swift Package Manager for your configuration.
Troubleshooting
- If session replay looks janky or drops frames on high-refresh-rate (120Hz ProMotion) iPhones, turn on the experimental
sessionReplayConfig.screenshotModeBackgroundCaptureoption (iOS only, requiresposthog-react-native4.45.0 or higher) to move screenshot capture off the main thread. This can trigger Xcode's Main Thread Checker warnings, so disable it in your scheme's Run diagnostics if that happens.