React Native session replay installation
Contents
Session Replay is currently supported only on Android and iOS platforms.
- 1
Add PostHog to your app
RequiredOur React Native enables you to integrate PostHog with your React Native project. For React Native projects built with Expo, there are no mobile native dependencies outside of supported Expo packages.
To install, add the
posthog-react-nativepackage to your project as well as the required peer dependencies.Expo apps
TerminalReact Native apps
TerminalReact Native Web and macOS
If you're using React Native Web or React Native macOS, do not use the expo-file-system package since the Web and macOS targets aren't supported, use the @react-native-async-storage/async-storage package instead.
Configuration
With the PosthogProvider
The recommended way to set up PostHog for React Native is to use the
PostHogProvider. This utilizes the Context API to pass the PostHog client around, and enables autocapture.To set up
PostHogProvider, add it to yourApp.jsorApp.tsfile:App.jsThen you can access PostHog using the
usePostHog()hook:React NativeWithout the PosthogProvider
If you prefer not to use the provider, you can initialize PostHog in its own file and import the instance from there:
posthog.tsThen you can access PostHog by importing your instance:
React NativeYou can even use this instance with the PostHogProvider:
React NativeRequires PostHog React Native SDK version >= 3.2.0, and it's recommended to always use the latest version.
- 2
Install the session replay plugin
RequiredTerminal - 3
Enable session recordings in your project settings
RequiredEnable session recordings in your PostHog Project Settings.


- 4
Configure replay settings
RequiredAdd
enableSessionReplay: trueto your PostHog configuration alongside any of your other configuration options:TypeScriptOr using the
PostHogProvider:TypeScript
Expo
Mobile Session Replay for Expo works normally, but prefer the expo tools for installing and running your project.
Install the session replay plugin.
Expo Go isn't supported since it uses Native plugins, please use development build.
Limitations
- On Android, requires API >= 26.
- On iOS, minimum deployment target is iOS13
- Keyboard is not supported. A placeholder will be shown.
- Wireframe mode isn't supported, only screenshot mode.
- Expo Go isn't supported since it uses Native plugins, please use development build.
- Masking individual view components within a WebView isn't supported, if your WebView displays sensitive view components, you've to mask the whole WebView.
- Session Replay is currently supported only on Android and iOS platforms.
Troubleshooting
- Run a clean build if you experience issues such as
The package 'posthog-react-native-session-replay' doesn't seem to be linked. - Update your SDK and iOS Pods.
- 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_calledevents, so theUsagetab on the feature flag page won't show anything. We're tracking this feature request in issue #250.