Android SDK

Record real user sessions, fire analytics events, and capture crashes from your Android app with a single init call.

Install

The SDK resolves from Maven Central. Most Android projects already have google() and mavenCentral() in their repositories — if so, skip straight to the dependency. JitPack stays available as a fallback for versions published before Maven Central.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        // Fallback only (pre–Maven Central pins):
        // maven { url = uri("https://jitpack.io") }
    }
}

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        // Fallback only (pre–Maven Central pins):
        // maven { url 'https://jitpack.io' }
    }
}

Then add the dependency to your app module:

dependencies {
    implementation("app.replayfy:android-sdk:0.0.4")
}

dependencies {
    implementation 'app.replayfy:android-sdk:0.0.4'
}

Requires minSdk 21 or higher. No manifest changes needed.

Initialize

Call init from Application.onCreate

One call starts recording and wires tap capture, screen detection, crash handling, and performance monitoring.

import android.app.Application
import com.replayfy.android.Replay
import com.replayfy.android.ReplayConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Replay.init(
            this,
            ReplayConfig(
                apiKey = "rpl_pk_YOUR_KEY",
                apiHost = "https://us.replayfy.app",  // or your self-hosted API URL
            ),
        )
    }
}

Point android:name at your Application subclass in AndroidManifest.xml.

<application android:name=".MyApp" ... />

Identify users and track events (optional)

Replay.identify("user_123", mapOf("email" to "[email protected]", "plan" to "pro"))
Replay.track("purchase", mapOf("amount" to 4200, "currency" to "USD"))

A "picture" (alias "avatar") entry set to a public https image URL sets the user’s avatar shown on the recording header and Users list; non-URL values are ignored.

Verify

Reload the app and foreground it. Your first session appears in the Replayfy dashboard within a few seconds. Wire addVerificationListener to fire a callback after the first successful upload for an in-app “Verify integration” flow.

Configuration

Only apiKey and apiHost are required; every other option has a sensible default. Pass overrides through ReplayConfig.

Option	Type	Default	Description
`apiKey`	`String`	required	Project API key from your dashboard.
`apiHost`	`String`	required	Ingest base URL — `https://us.replayfy.app` (or your self-hosted API URL).
`projectId`	`String?`	`null`	Only needed when one key spans multiple projects.
`distinctId`	`String?`	`null`	Known user id at init time; otherwise an install-stable anonymous id is generated.
`flushIntervalMs`	`Long`	`5000`	How often the buffered batch is uploaded (ms).
`maxBufferSize`	`Int`	`500`	Events buffered in memory before a flush is forced.
`captureConsole`	`Boolean`	`true`	Capture `Log.x` / stdout / stderr output.
`captureNetwork`	`Boolean`	`false`	Capture HTTP requests (off by default to avoid PII).
`captureErrors`	`Boolean`	`true`	Capture uncaught exceptions and crashes.
`captureTouch`	`Boolean`	`true`	Capture taps and gestures from the view tree.
`captureHeaders`	`Boolean`	`false`	Include request/response headers in network capture (PII risk).
`captureBodies`	`Boolean`	`true`	Include request/response bodies in network capture (capped, PII risk).
`maxBodyBytes`	`Int`	`4096`	Max captured body bytes per network event; larger bodies are truncated.
`captureSnapshotPixels`	`Boolean`	`true`	Pixel-accurate playback vs. lighter tree-only “wireframe” playback.
`snapshotIntervalMs`	`Long`	`500`	Screen-capture cadence (~2 FPS); floored at 200 ms.
`autoScreenName`	`Boolean`	`true`	Auto-name the current screen from each Activity’s class name.
`useRemoteConfig`	`Boolean`	`true`	Let dashboard settings override these values at runtime (your values act as cold-start fallbacks; ~15-minute refresh).
`excludedScreens`	`List<String>`	`emptyList()`	Screen names whose frame capture is paused while they’re foreground (see Screen tracking). Case-insensitive; taps, network, and console still record. Mutable at runtime via `Replay.excludeScreen`/`setExcludedScreens`.

API reference

All methods are exposed on the Replay singleton and are static-callable from Kotlin and Java.

Identity & events

Method	Description
`identify(distinctId, properties?)`	Attach a known-user identity; earlier anonymous sessions link retroactively.
`track(name, properties?)`	Record a custom timeline / funnel event.
`setUserProperty(key, value)`	Attach a property that sticks to the user across sessions.
`setSessionProperty(key, value)`	Attach a property to the current session only.
`addTagWithProperties(name, properties?)`	Add a session-level tag for filtering the session list.
`markSessionAsFavorite()`	Star the current session so it surfaces in the “starred” filter.
`setAppVersion(version, build?)`	Override the auto-detected app version/build.
`setPushNotificationToken(token, platform?)`	Attach the device push token (`platform` defaults to `"fcm"`).

Error monitoring

Method	Description
`captureException(error, handled?, properties?)`	Report a caught throwable. `handled = false` marks it fatal (crash) vs. exception.
`reportBugEvent(name, description?, properties?)`	Flag a user-submitted bug report and trigger a fresh screen capture.
`log(level, message, stack?)`	Bridge your logging framework into the console tab. `level` ∈ `log`/`info`/`warn`/`error`/`debug`.

Screen tracking

Method	Description
`tagScreenName(name)`	Manually set the current screen name.
`addObservedView(view, screenName, viewName?)`	Track a Compose/custom view as a screen (emits on attach/detach).
`setAutomaticScreenNameTagging(enabled)`	Toggle Activity-based auto screen naming at runtime.
`excludeScreen(name)`	Exclude a screen from frame capture by name (case-insensitive; matched against the tagged / auto-tagged screen name). While it’s foreground the screenshot loop pauses — taps, network, console, and performance events keep flowing — and resumes on the next non-excluded screen.
`unexcludeScreen(name)`	Stop excluding a screen — frame capture resumes next time it’s shown.
`setExcludedScreens(names)`	Replace the entire excluded-screens list in one call.

Exclusion is distinct from occludeSensitiveScreen(true) — that keeps recording but blanks the frame, whereas an excluded screen captures no frames at all. Seed the list at init, or manage it at runtime:

// Seed at init:
Replay.init(
    this,
    ReplayConfig(
        apiKey = "rpl_pk_YOUR_KEY",
        apiHost = "https://us.replayfy.app",  // or your self-hosted API URL
        excludedScreens = listOf("Paywall", "PinEntry"),
    ),
)

// …or manage at runtime:
Replay.excludeScreen("Paywall")               // pause frames while "Paywall" is foreground
Replay.unexcludeScreen("Paywall")             // resume
Replay.setExcludedScreens(listOf("PinEntry", "CardScanner"))

Text input tracking

Method	Description
`addObservedInput(editText)`	Record an `EditText`’s value on focus-loss (passwords auto-masked).
`trackInput(label, value, masked)`	Record a value not backed by an `EditText`; `masked = true` sends `"***"`.

Network capture

Add the interceptor to your OkHttp client. When captureNetwork is off, it passes through with zero overhead.

val client = OkHttpClient.Builder()
    .addInterceptor(Replay.networkInterceptor())
    .build()

Method	Description
`networkInterceptor()`	Returns an OkHttp `Interceptor` that records requests when `captureNetwork` is on.

Session control

Method	Description
`isRecording()`	Whether the SDK is currently recording.
`pauseRecording()` / `resumeRecording()`	Pause/resume screen capture while keeping the interaction timeline.
`startNewSession()`	Force-end the current session and start a new one (logout/login, re-bucketing).
`stop()`	End the current session and flush the buffered batch. The next foregrounding starts a fresh session.
`stopApplicationAndUploadData(timeoutMs?)`	Stop and block (up to `timeoutMs`, default 5000) until the batch is uploaded or persisted.
`cancelSession()`	Discard the current session without uploading — clears the in-memory buffer and deletes any on-disk batches still queued, so the server drops whatever already streamed. A fresh session can start afterward. Contrast with `stop()`, which ends the session gracefully and uploads.
`enableAdvancedGestureRecognizer(enabled)`	Capture pinch and rotate gestures in addition to the always-on tap / swipe / long-press (off by default).
`allowShortBreakForAnotherApp(allow, breakWindowMs?)`	Keep the same session across a brief switch to another app — a background gap up to `breakWindowMs` (default `30000`) resumes the session; a longer gap starts a fresh session on return.
`setMultiSessionRecord(enabled)`	Record multiple sessions per app launch (default `true`), or only one — when `false`, the current/next session records and then no further sessions fire this process.
`addVerificationListener(listener)` / `removeVerificationListener(listener)`	Fire a callback after the first successful upload.

Privacy & masking

All masking happens on-device before anything is uploaded. Password fields are masked automatically; everything else is opt-in.

Replay.addPrivacyView(cardNumberField)             // mask one view (and its children)
Replay.removePrivacyView(cardNumberField)

Replay.occludeAllTextFields(true)                  // mask every EditText
Replay.occludeAllTextView(true)                    // mask every TextView / Button
Replay.applyOcclusion(CreditCardView::class.java)  // mask all instances of a view class
Replay.removeOcclusion(CreditCardView::class.java)
Replay.occludeSensitiveScreen(true)                // mask the entire screen

Replay.setMaskStyle(ReplayMaskStyle.BLUR)          // BLUR (default) or OVERLAY
Replay.setBlurDownscale(12)                        // stronger blur = larger factor

Method	Description
`addPrivacyView(view)` / `removePrivacyView(view)`	Mask a single view (marks propagate to descendants).
`occludeAllTextFields(occlude)`	Mask every `EditText` in the app.
`occludeAllTextView(occlude)`	Mask every `TextView` / `Button`.
`applyOcclusion(viewClass)` / `removeOcclusion(viewClass)`	Mask every instance of a custom view class.
`occludeSensitiveScreen(occlude)`	Mask the entire captured screen.
`setMaskStyle(style)`	Default masking style — `ReplayMaskStyle.BLUR` or `ReplayMaskStyle.OVERLAY`.
`setBlurDownscale(factor)`	Blur strength for `BLUR` regions (default 12; higher = stronger).

Identify users

Attach known-user identities so anonymous sessions link retroactively.

Track events

Fire custom events that power funnels, retention, and filters.

Privacy & masking

Redact sensitive views and inputs before anything leaves the device.

Get started

Self-hosting

Install the SDK

Products

Platform

Guides

Help

Install

Initialize

Verify

Configuration

API reference

Identity & events

Error monitoring

Screen tracking

Text input tracking

Network capture

Session control

Privacy & masking

Identify users

Track events

Privacy & masking

​Install

​Initialize

​Verify

​Configuration

​API reference

​Identity & events

​Error monitoring

​Screen tracking

​Text input tracking

​Network capture

​Session control

​Privacy & masking

Identify users

Track events

Privacy & masking

Install

Initialize

Verify

Configuration

API reference

Identity & events

Error monitoring

Screen tracking

Text input tracking

Network capture

Session control

Privacy & masking