React Native Session Replay installation

Configure Android screenshot capture

Lowering screenshot resolution and using the smaller RGB_565 pixel format reduce capture time and memory use on Android. This helps keep your app responsive while recording.

For the best balance of performance and image quality, we recommend a scale of 0.5, the RGB_565 color mode, and compression quality 30.

Use these experimental sessionReplayConfig options to control Android screenshot resolution, compression, and bitmap memory use independently. They require @posthog/react-native-plugin and don't affect iOS recordings. Session Replay must still be enabled with enableSessionReplay: true and in your project settings.

• screenshotScale (Android default: 1.0) – Multiplies the physical width and height of screenshots. Values are clamped to 0.1–1.0. A scale of 0.5 captures half the width and height, or one quarter of the pixels.

• screenshotCompressionQuality (Android default: 30) – WebP compression quality, as an integer clamped to 0–100. Higher values generally retain more detail and produce larger payloads. This doesn't change screenshot resolution.

• screenshotColorMode (Android default: ARGB_8888) – Android bitmap pixel format. ARGB_8888 uses four bytes per pixel and preserves transparency and color precision before compression. RGB_565 uses two bytes per pixel, with reduced color precision and no transparency.

For example, capture Android screenshots at half the width and height while retaining the default color mode:

import { PostHogProvider } from "posthog-react-native"

export function MyApp() {
    return (
        <PostHogProvider
            apiKey="<ph_project_token>"
            options={{
                host: "https://us.i.posthog.com",
                enableSessionReplay: true,
                sessionReplayConfig: {
                    screenshotScale: 0.5,
                    screenshotCompressionQuality: 30,
                },
            }}
        >
            <RestOfApp />
        </PostHogProvider>
    )
}

Keep these trade-offs in mind:

• Resolution – Lower scales reduce image detail. The Android SDK rounds each scaled dimension up to at least one pixel. Replay viewport dimensions and mask positions remain aligned with the original screen.
• Color and transparency – With RGB_565, transparent window regions appear black. If a device rejects this format, the Android SDK uses ARGB_8888 for later captures.
• Compression – WebP compression is lossy, including at quality 100, except on Android 10 (API 29), where quality 100 uses lossless compression.

To capture fewer snapshots instead, increase sessionReplayConfig.throttleDelayMs. Screenshot resolution, compression quality, and color mode don't change the capture interval. Check text readability and privacy masking in your app before deploying these settings.

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-ios resolved 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-plugin 2.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.screenshotModeBackgroundCapture option (iOS only, requires posthog-react-native 4.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.