Session replay installation

Last updated:

|Edit this page

Session replay enables you to record users navigating through your website or mobile app and play back the individual sessions to watch how real users use your product.

🚧 NOTE: React Native session replay is considered beta and is free while in beta. We are keen to gather as much feedback as possible so if you try this out please let us know. You can send feedback via the in-app support panel or one of our other support options.

Step one: Add PostHog to your app

Our 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-native package to your project as well as the required peer dependencies.

Expo apps

Terminal
npx expo install posthog-react-native expo-file-system expo-application expo-device expo-localization

React Native apps

Terminal
yarn add posthog-react-native @react-native-async-storage/async-storage react-native-device-info
# or
npm i -s posthog-react-native @react-native-async-storage/async-storage react-native-device-info

React 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, enable autocapture, and ensure that the queue is flushed at the right time.

To set up PostHogProvider, add it to your App.js or App.ts file:

App.js
// App.(js|ts)
import { usePostHog, PostHogProvider } from 'posthog-react-native'
...


export function MyApp() {
    return (
        <PostHogProvider apiKey="<ph_project_api_key>" options={{
            // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
            host: 'https://us.i.posthog.com', 
        }}>
            <MyComponent />
        </PostHogProvider>
    )
}

Then you can access PostHog using the usePostHog() hook:

React Native
const MyComponent = () => {
    const posthog = usePostHog()


    useEffect(() => {
        posthog.capture("event_name")
    }, [posthog])
}

Without 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.ts
import PostHog from 'posthog-react-native'


export const posthog = new PostHog('<ph_project_api_key>', {
  // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'  
  host: 'https://us.i.posthog.com' 
})

Then you can access PostHog by importing your instance:

React Native
import { posthog } from './posthog'


export function MyApp1() {
    useEffect(async () => {
        posthog.capture('event_name')
    }, [posthog])


    return <View>Your app code</View>
}

You can even use this instance with the PostHogProvider:

React Native
import { posthog } from './posthog'


export function MyApp() {
  return <PostHogProvider client={posthog}>{/* Your app code */}</PostHogProvider>
}

Requires PostHog React Native SDK version >= 3.2.0, and it's recommended to always use the latest version.

Install the session replay plugin.

Terminal
yarn add posthog-react-native-session-replay
# or npm
npm i -s posthog-react-native-session-replay

Step two: Configure replay settings

Add enableSessionReplay: true to your PostHog configuration alongside any of your other configuration options:

JavaScript
export const posthog = new PostHog(
  '<ph_project_api_key>',
  {
    // Enable session recording. Requires enabling in your project settings as well.
    // Default is false.
    enableSessionReplay: true,
    sessionReplayConfig: {
      // Whether text and text input fields are masked. Default is true.
      // Password inputs are always masked regardless
      maskAllTextInputs: true,
      // Whether images are masked. Default is true.
      maskAllImages: true,
      // Enable masking of all sandboxed system views like UIImagePickerController, PHPickerViewController and CNContactPickerViewController. Default is true.
      // iOS only
      maskAllSandboxedViews = true,
      // Capture logs automatically. Default is true.
      // Android only (Native Logcat only)
      captureLog: true,
      // Whether network requests are captured in recordings. Default is true
      // Only metric-like data like speed, size, and response code are captured.
      // No data is captured from the request or response body.
      // iOS only
      captureNetworkTelemetry: true,
      // Deboucer delay used to reduce the number of snapshots captured and reduce performance impact. Default is 1000ms
      // Ps: it was 500ms (0.5s) by default until version 3.3.7
      androidDebouncerDelayMs: 1000,
      // Deboucer delay used to reduce the number of snapshots captured and reduce performance impact. Default is 1000ms
      iOSdebouncerDelayMs: 1000,
    },
  },
);

Or using the PostHogProvider:

JavaScript
<PostHogProvider
        apiKey="<ph_project_api_key>"
        options={{
          enableSessionReplay: true,
          ...
        }}
      >

Expo

Mobile Session Replay for Expo works normally, but prefer the expo tools for installing and running your project.

Install the session replay plugin.

Terminal
npx expo install posthog-react-native-session-replay

Expo Go isn't supported since it uses Native plugins, please use development build.

Terminal
# Run Android development build 
npx expo run:android --no-build-cache --device


# Run iOS development build 
npx expo run:ios --no-build-cache --device

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.

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 iOS Pods.

Questions? Ask Max AI.

It's easier than reading through 552 docs articles.

Community questions

Was this page useful?

Next article

How to watch recordings

To watch recordings, you can visit the Replay page. When watching replays, you can change the playback speed, as well as select the option 'skip inactivity' - this skips parts of the recording where the user was inactive on the page. You can also watch recordings by clicking on any data point in an insight. This opens a list of persons and displays a "watch recording" button if available. This is especially useful in funnels , where you can drill down and watch recordings of users who…

Read next article

PostHog.com doesn't use third party cookies - only a single in-house cookie.

No data is sent to a third party.

Ursula von der Leyen, President of the European Commission