Session replay installation

Last updated:

|Edit this page|

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:

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.

Step two: Enable session recordings in your project settings

Enable session recordings in your PostHog Project Settings.

Enable session recordings in your PostHog'

Step three: Configure replay settings

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 here.
    • 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 here.

Questions? Ask Max AI.

It's easier than reading through 669 pages of documentation

Community questions

Was this page useful?

Next article

How to watch recordings

To watch recordings, you can visit the Replay page. When watching replays, you can change the playback speed, as well as select the option 'skip inactivity' - this skips parts of the recording where the user was inactive on the page. You can also watch recordings by clicking on any data point in an insight. This opens a list of persons and displays a "watch recording" button if available. This is especially useful in funnels , where you can drill down and watch recordings of users who…

Read next article

PostHog.com doesn't use third party cookies - only a single in-house cookie.

No data is sent to a third party.

Ursula von der Leyen, President of the European Commission