Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

10.9 KB
Raw Blame
import { OnboardingComponentsContext, createInstallation } from 'scenes/onboarding/shared/OnboardingDocsContentWrapper'

import { StepDefinition } from '../steps'

export const getReactNativeSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => {
    const { CodeBlock, Markdown, CalloutBox, dedent, snippets } = ctx
    const SessionReplayFinalSteps = snippets?.SessionReplayFinalSteps

    return [
        {
            title: 'Install the packages',
            badge: 'required',
            content: (
                <>
                    <Markdown>
                        Install the PostHog React Native library, its dependencies, and the session replay plugin:
                    </Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'bash',
                                file: 'Expo',
                                code: dedent`
                                    npx expo install posthog-react-native expo-file-system expo-application expo-device expo-localization @posthog/react-native-plugin
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'yarn',
                                code: dedent`
                                    yarn add posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize @posthog/react-native-plugin

                                    # for iOS
                                    cd ios && pod install
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'npm',
                                code: dedent`
                                    npm i -s posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize @posthog/react-native-plugin

                                    # for iOS
                                    cd ios && pod install
                                `,
                            },
                        ]}
                    />
                    <CalloutBox type="fyi" title="Plugin renamed in 4.47.0+">
                        <Markdown>
                            {dedent`
                                \`@posthog/react-native-plugin\` (\`>= 2.0.1\`) is the renamed \`posthog-react-native-session-replay\` plugin — it was renamed in \`posthog-react-native\` 4.47.0+ and now also powers [native error tracking](https://posthog.com/docs/error-tracking/installation/react-native). If you're on a \`posthog-react-native\` version earlier than 4.47.0, install \`posthog-react-native-session-replay\` instead.
                            `}
                        </Markdown>
                    </CalloutBox>
                    <CalloutBox type="fyi" title="SDK version">
                        <Markdown>
                            Session replay requires PostHog React Native SDK version 3.2.0 or higher. We recommend
                            always using the latest version.
                        </Markdown>
                    </CalloutBox>
                </>
            ),
        },
        {
            title: 'Enable session recordings in project settings',
            badge: 'required',
            content: (
                <>
                    <Markdown>
                        Go to your PostHog [Project Settings](https://us.posthog.com/settings/project-replay) and enable
                        **Record user sessions**. Session recordings will not work without this setting enabled.
                    </Markdown>
                </>
            ),
        },
        {
            title: 'Configure PostHog with session replay',
            badge: 'required',
            content: (
                <>
                    <Markdown>
                        Add `enableSessionReplay: true` to your PostHog configuration. Here are all the available
                        options:
                    </Markdown>
                    <CodeBlock
                        blocks={[
                            {
                                language: 'tsx',
                                file: 'App.tsx',
                                code: dedent`
                                    import { PostHogProvider } from 'posthog-react-native'

                                    export function MyApp() {
                                        return (
                                            <PostHogProvider
                                                apiKey="<ph_project_token>"
                                                options={{
                                                    host: "<ph_client_api_host>",

                                                    // Enable session recording. Requires enabling in your project settings as well.
                                                    // Default is false.
                                                    enableSessionReplay: true,

                                                    sessionReplayConfig: {
                                                        // Whether text inputs are masked. Default is true.
                                                        // Password inputs are always masked regardless
                                                        maskAllTextInputs: true,

                                                        // Whether images are masked. Default is true.
                                                        maskAllImages: true,

                                                        // Experimental screenshot settings (Android only, requires @posthog/react-native-plugin).
                                                        // We recommend these values to balance performance and image quality.
                                                        // Lower resolution and RGB_565 reduce capture time and memory use.

                                                        // Scale each screenshot dimension from 0.1 to 1.0. Default is 1.0.
                                                        // A scale of 0.5 captures one quarter of the pixels, with less image detail.
                                                        screenshotScale: 0.5,

                                                        // RGB_565 uses two bytes per pixel instead of four, with lower color precision
                                                        // and no transparency. Transparent window regions appear black. Default is ARGB_8888.
                                                        screenshotColorMode: "RGB_565",

                                                        // WebP compression quality from 0 to 100. Default is 30.
                                                        // Lower quality reduces payload size at the cost of image detail.
                                                        screenshotCompressionQuality: 30,

                                                        // Capture logs automatically. Default is true.
                                                        // Android only (Native Logcat only)
                                                        //
                                                        // Support for remote configuration 
                                                        // in the [session replay settings](https://app.posthog.com/settings/project-replay#replay-log-capture)
                                                        // requires SDK version 4.35.0 or higher.
                                                        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
                                                        //
                                                        // Support for remote configuration 
                                                        // in the [session replay settings](https://app.posthog.com/settings/project-replay#replay-network)
                                                        // requires SDK version 4.35.0 or higher.
                                                        captureNetworkTelemetry: true,

                                                        // Sample rate for session recordings. A value between 0.0 and 1.0.
                                                        // 1.0 means 100% of sessions will be recorded. 0.5 means 50%, and so on.
                                                        // Local config has precedence over remote config when both are set.
                                                        // Default is undefined (all sessions are recorded).
                                                        sampleRate: undefined,

                                                        // Throttling delay used to reduce the number of snapshots captured
                                                        // and reduce performance impact. Default is 1000ms
                                                        throttleDelayMs: 1000,
                                                    },
                                                }}
                                            >
                                                <RestOfApp />
                                            </PostHogProvider>
                                        )
                                    }
                                `,
                            },
                        ]}
                    />
                    <Markdown>
                        For more configuration options, see the [React Native session replay
                        docs](https://posthog.com/docs/session-replay/installation?tab=React+Native).
                    </Markdown>
                    <CalloutBox type="fyi" title="Requirements">
                        <Markdown>
                            Requires 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.
                        </Markdown>
                    </CalloutBox>
                </>
            ),
        },
        {
            title: 'Watch session recordings',
            badge: 'recommended',
            content: <>{SessionReplayFinalSteps && <SessionReplayFinalSteps />}</>,
        },
    ]
}

export const ReactNativeInstallation = createInstallation(getReactNativeSteps)