Mixpanel Session Replay SDKs: Android

Getting started

The Session Replay SDK for Android is an supplementary SDK that complements the main Android SDK, enabling you to visually replay your users’ app interactions through the Session Replay feature. Please refer to our developer guide on implementing Session Replay for a detailed walkthrough.

If you have not installed the main Swift SDK yet, navigate to the Quickstart Guide.

The Library Source Code is documented in our GitHub repo.

Installing the Library

You can integrate the Mixpanel Android Session Replay SDK into your Android project by embedding the Android Archive (AAR) file below.

1. Open your existing Android Studio project where you want to integrate the Mixpanel Android Session Replay SDK.

2. Download and unzip mixpanel-android-session-replay.aar.zip to your local drive.

3. Copy the AAR file to the app/libs folder in your Android project.

4. Configure your project’s Gradle settings:

   • For Kotlin DSL (settings.gradle.kts): Add to the repositories section under dependencyResolutionManagement:

   flatDir {
       dirs("libs")
   }
   • For Groovy DSL (build.gradle): Add to the repositories section under buildScripts:

   flatDir {
       dirs("libs")
   }

5. Add the following dependencies to your module’s build.gradle or build.gradle.kts:

implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:+")
implementation("com.squareup.curtains:curtains:+")
implementation(files("libs/mixpanel-android-session-replay.aar"))

6. Sync your project with Gradle files.

Initialize

You should have the main Mixpanel Android SDK installed (minimum version v8.0.2). If not, please refer to the Quickstart Guide.

Initialize the MPSessionReplay SDK in your Application class:

Example Usage

private fun initializeMixpanel() {
    val token = "MY_PROJECT_TOKEN"
    val trackAutomaticEvents = true
 
    val mixpanel = MixpanelAPI.getInstance(this, token, trackAutomaticEvents)
    mixpanel.identify("DISTINCT_ID")
 
 
    val config = MPSessionReplayConfig(
        wifiOnly = false,
        recordSessionsPercent = 100.0
    )
 
    MPSessionReplay.initialize(this, token, mixpanel.distinctId, config)
}

Capturing Replays

You can capturing replay data using a sampling method (recommended), or customize when and where replays are captured manually using methods provided by the Session Replay Android SDK.

Sampling

To enable Session Replay and set your sampling rate, create a SessionReplayConfig object and set the recordSessionsPercent with a value between 0.0 and 100.0.

At 0.0 no sessions will be recorded, at 100.0 all sessions will be recorded.

Example Usage

// records 1% of all sessions
MPSessionReplayConfig(
            recordSessionsPercent = 1.0
        )

Manual Capture

To programatically start and stop replay capture, use the .startRecording() and .stopRecording() methods.

Start Recording

Call .startRecording() to force recording to begin, regardless of the recordSessionsPercent init option.

The recording automatically stops when the app goes to the background. Therefore, if you want to continuously record the replays, you will need to restart the replay once the app becomes active again.

This will have no effect if replay data collection is already in progress.

Example Usage

// manually trigger a replay capture
MPSessionReplay.getInstance()?.startRecording()
// no effect if recording is already in progress

Stop Recording

Call .stopRecording() to stop any active replay data collection. The SDK automatically stops recording when the app goes to the background.

Example Usage

// manually end a replay capture
MPSessionReplay.getInstance()?.stopRecording()
// no effect if no recording in progress

Config Options

Upon initialization you can provide a SessionReplayConfig object to customize your replay capture.

Currently, there are three config options:

Example Usage

// mask images only
// only send recordings on wifi
MPSessionReplayConfig(
            wifiOnly = true,
            autoMaskedViews = mutableSetOf(AutoMaskedView.ImageView)
        )

Mark Views as Sensitive

Mark any views as sensitive by setting the mpReplaySensitive property to true or calling the addSensitiveView() method. Views marked as “sensitive” will be masked.

Set mpReplaySensitive to false or calling the removeSensitiveView() to mark any view as safe. Views marked as “safe” will not be masked.

Example Usage

// Compose
Image(
    painter = painterResource(id = R.drawable.family_photo),
    contentDescription = "Family Photo",
    modifier = Modifier.mpReplaySensitive(true)
)
 
// XML
val creditCardView: ImageView = findViewById(R.id.creditCardView)
MPSessionReplay.getInstance()?.addSensitiveView(creditCardView)

All EditText and TextView components are masked by default. EditText cannot be unmasked, while TextView can be unmasked.

Get Replay ID

Use the getReplayId() method to return the Replay ID for the current replay recording. The method will return an empty object if there is no active replay capture in progress.

Example Usage

// return the $mp_replay_id for the currently active capture
MPSessionReplay.getInstance()?.getReplayId()
// {$mp_replay_id: '19221397401184-063a51e0c3d58d-17525637-1d73c0-1919139740f185'}

Debug Mode

No toggle is needed to enable debug logs; logging is always enabled in your developer/debug environment.

Replay Retention

User replays are stored for 30 days after the time of ingestion.

Release History

See all releases.