Android Session Replay installation

Contents

  1. Install the dependency

    Required

    Add the PostHog Android SDK to your build.gradle dependencies:

    build.gradle
    dependencies {
        implementation("com.posthog:posthog-android:3.+")
    }
    SDK version

    Session replay requires PostHog Android SDK version 3.4.0 or higher. We recommend always using the latest version.

  2. Enable session recordings in project settings

    Required

    Go 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

    Required

    Add sessionReplay = true to your PostHog configuration. Here are all the available options:

    SampleApp.kt
    class SampleApp : Application() {
    

        companion object {
            const val POSTHOG_TOKEN = "<ph_project_token>"
            const val POSTHOG_HOST = "https://us.i.posthog.com"
        }
    

        override fun onCreate() {
            super.onCreate()
    

            val config = PostHogAndroidConfig(
                apiKey = POSTHOG_TOKEN,
                host = POSTHOG_HOST
            )
    

            // Enable session recording. Requires enabling in your project settings as well.
            // Default is false.
            config.sessionReplay = true
    

            // Whether text and text input fields are masked. Default is true.
            // Password inputs are always masked regardless
            config.sessionReplayConfig.maskAllTextInputs = true
    

            // Whether images are masked. Default is true.
            config.sessionReplayConfig.maskAllImages = true
    

            // Capture logs automatically. Default is true.
            // 
            // Support for remote configuration 
            // in the [session replay settings](https://app.posthog.com/settings/project-replay#replay-log-capture)
            // requires SDK version 3.32.0 or higher.
            config.sessionReplayConfig.captureLogcat = true
    

            // Whether replays are created using high quality screenshots. Default is false.
            // If disabled, replays are created using wireframes instead.
            // The screenshot may contain sensitive information, so use with caution
            config.sessionReplayConfig.screenshot = false
    

            // Throttle delay used to reduce the number of snapshots captured. Default is 1000ms
            config.sessionReplayConfig.throttleDelayMs = 1000
    

            // 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.
            // Default is null (all sessions are recorded).
            // 
            // Support for remote configuration
            // in the [session replay triggers](https://us.posthog.com/settings/project-replay#replay-triggers)
            // requires SDK version 3.34.0 or higher.
            config.sessionReplayConfig.sampleRate = null
    

            PostHogAndroid.setup(this, config)
        }
    }

    For more configuration options, see the Android session replay docs.

    Requirements

    Requires Android API 26 or higher. Jetpack Compose is only supported if screenshot is enabled.

  4. Watch session recordings

    Recommended

    Visit 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.

    Watch your first recording →

  5. Next steps

    Recommended

    Now that you're recording sessions, continue with the resources below to learn what else Session Replay enables within the PostHog platform.

    ResourceDescription
    Watching recordingsHow to find and watch session recordings
    Privacy controlsHow to mask sensitive data in recordings
    Network recordingHow to capture network requests in recordings
    Console log recordingHow to capture console logs in recordings
    More tutorialsOther real-world examples and use cases

Configure screenshot capture

Lowering screenshot resolution and using the smaller RGB_565 pixel format reduce capture time and memory use. 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 screenshot resolution, compression, and bitmap memory use independently. They only apply when sessionReplayConfig.screenshot is true. They don't enable Session Replay or affect wireframe capture.

  • screenshotScale (default: 1.0f) – 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 (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 (default: ARGB_8888) – 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.

The defaults retain full-resolution screenshots with ARGB_8888 and WebP quality 30. The SDK reuses compatible screenshot buffers automatically, including with these defaults.

Apply the recommended settings before calling PostHogAndroid.setup(this, config):

Kotlin
import com.posthog.android.replay.PostHogScreenshotColorMode


config.sessionReplay = true
config.sessionReplayConfig.screenshot = true
config.sessionReplayConfig.screenshotScale = 0.5f
config.sessionReplayConfig.screenshotCompressionQuality = 30
config.sessionReplayConfig.screenshotColorMode = PostHogScreenshotColorMode.RGB_565

Keep these trade-offs in mind:

  • Resolution – Lower scales reduce image detail. The SDK rounds each scaled dimension up to at least one pixel. Replay viewport dimensions and mask positions remain aligned with the original screen. NaN and infinite scale values reset to 1.0.
  • Color and transparency – With RGB_565, transparent window regions appear black. If a device rejects this format, the 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.

Still have questions?

Was this page useful?