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.
Step one: Add PostHog to your app
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
:
dependencies {implementation("com.posthog:posthog-android:3.+")}
Configuration
The best place to initialize the client is in your Application
subclass.
import android.app.Applicationimport com.posthog.android.PostHogAndroidimport com.posthog.android.PostHogAndroidConfigclass 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.
Step two: Enable session recordings in your project settings
Enable session recordings in your PostHog Project Settings.


Step three: Configure replay settings
Add sessionReplay = true
to your PostHog configuration alongside any of your other configuration options:
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 regardlesssessionReplayConfig.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 cautionsessionReplayConfig.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 here.
- Session replay feature flag evaluation does not capture
$feature_flag_called
events, so theUsage
tab on the feature flag page won't show anything. We're tracking this feature request here.