Android session replay installation

  1. Add PostHog to your app

    Required

    The best way to install the PostHog Android library is with a build system like Gradle. This ensures you can easily upgrade to the latest versions.

    All you need to do is add the posthog-android module to your App's build.gradle or build.gradle.kts:

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

    Configuration

    The best place to initialize the client is in your Application subclass.

    Kotlin
    import android.app.Application
    import com.posthog.android.PostHogAndroid
    import com.posthog.android.PostHogAndroidConfig
    class SampleApp : Application() {
    companion object {
    const val POSTHOG_API_KEY = "<ph_project_api_key>"
    // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
    const val POSTHOG_HOST = "https://us.i.posthog.com"
    }
    override fun onCreate() {
    super.onCreate()
    val config = PostHogAndroidConfig(
    apiKey = POSTHOG_API_KEY,
    host = POSTHOG_HOST
    )
    PostHogAndroid.setup(this, config)
    }
    }

    Session replay requires PostHog Android SDK version >= 3.4.0, and it's recommended to always use the latest version.

  2. Enable session recordings in your project settings

    Required

    Enable session recordings in your PostHog Project Settings.

    Enable session recordings in your PostHog'
  3. Configure replay settings

    Required

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

    Android
    val config = PostHogAndroidConfig(apiKey = "<ph_project_api_key>").apply {
    // Enable session recording. Requires enabling in your project settings as well.
    // Default is false.
    sessionReplay = true
    // Whether text and text input fields are masked. Default is true.
    // Password inputs are always masked regardless
    sessionReplayConfig.maskAllTextInputs = true
    // Whether images are masked. Default is true.
    sessionReplayConfig.maskAllImages = true
    // Capture logs automatically. Default is true.
    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
    sessionReplayConfig.screenshot = false
    // Throttle 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.8.2
    // Available from version 3.10.0 (Before it was called debouncerDelayMs)
    sessionReplayConfig.throttleDelayMs = 1000
    }

Limitations

  • Requires Android API >= 26.
  • Jetpack Compose is only supported if screenshot is enabled.
  • Custom views are partly supported, and only fully supported if screenshot is enabled.
  • WebView is only supported if screenshot is enabled. A placeholder will be shown as a fallback.
  • Keyboard is not supported. A placeholder will be shown.

Troubleshooting

  • Update your SDK.
  • 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_called events, so the Usage tab on the feature flag page won't show anything. We're tracking this feature request in issue #250.

Community questions

Was this page useful?

Questions about this page? or post a community question.