feat(observability-android): report the outcome of LDReplay.start and allow forcing past sampling

[abelonogov-ld]

Why

LDReplay.start() returned Unit and delegated straight to isEnabled = true. That setter short-circuits on no-change:

override var isEnabled: Boolean
    set(value) {
        if (_isEnabled.value == value) return
        ...

So a session that is enabled but not recording was unreachable. The common way to get into that state is sampling: attemptStart sets _isEnabled = true, then SessionReplaySamplingSession loses the roll and leaves _isRunning = false. Every later start() hits the guard and returns, and sampleRate is only re-evaluated after a stop() resets the decision. A caller also had no way to distinguish a start that began recording from one that was sampled out or refused by the backend — start() reported nothing at all.

iOS already solves both: LDReplay.shared.start(ignoreSampling:) returns a SessionReplayStartResult. Android had neither the parameter nor the result, and attemptStart(ignoreSampling:) was private.

This came up while fixing a React Native bug where configureSessionReplay({ isEnabled: false }) followed by startSessionReplay() never records. The RN adapter needs to force a start and to report why one didn't happen, and it can't do either on Android today.

What changed

LDReplay.start(ignoreSampling: Boolean = false): SessionReplayStartResult, mirroring the Swift API so a cross-platform bridge reports the same outcome on both platforms.

• New public SessionReplayStartResult — UNAVAILABLE, STARTED, ALREADY_STARTED, SAMPLED_OUT, UNRECOVERABLE_ERROR, plus isRunning. Cases and semantics match SessionReplayStartResult.swift.
• SessionReplayService.start takes over the enable half of the isEnabled setter, which now delegates to it. It deliberately omits the no-change short-circuit, which is what makes a forced start able to override a sampling decision already made for this enable cycle. The gate check still sets _isEnabled under the gate's lock, so a backend refusal racing an enable cannot be overwritten.
• attemptStart returns the outcome instead of a bare Boolean. Each existing early return maps to the case it already represented, so the control flow is unchanged.
• PreInitReplayBuffer now buffers the pre-init intent as Start(ignoreSampling) / Stop rather than a plain Boolean?, so a forced start issued before SDK init (e.g. from Application.onCreate) is still forced when bind applies it. Pre-init calls return UNAVAILABLE, because the outcome isn't settled until bind. Last-write-wins between start and stop is preserved.

ignoreSampling = true works even after a sampled-out decision because SessionReplaySamplingSession.shouldStartCapture checks it before decisionMade.

Compatibility

Source-compatible. The parameter is defaulted, the result can be ignored, and @JvmOverloads keeps the no-arg overload for Java. The three in-repo callers (e2e/android x2, the React Native adapter) all use start() in statement position and need no change. The return type change is a binary break, so consumers recompile — normal for a minor release here.

Testing

./gradlew :lib:testDebugUnitTest passes (26 tests in LDReplayTest, 0 failures). Ten new cases cover: the result being forwarded from the service, SAMPLED_OUT not reporting as running, ignoreSampling defaulting to false and being forwarded when set, the isEnabled setter never ignoring sampling, a pre-init start reporting UNAVAILABLE and being replayed at init with its ignoreSampling preserved, stop winning over a buffered start, and resetForTest clearing it. A new SessionReplayStartResultTest pins the isRunning mapping that bridges depend on.

:lib:build fails lintDebug, but on five pre-existing NewApi errors in CustomSampler.kt, JsonCommonAdapter.kt, KotlinTracer.kt, and UserInteractionManager.kt — all untouched here, and lint is not part of CI. I could not run e2e/android's :app:testComposeDebugUnitTest locally (the build host ran out of disk resolving geckoview), so that job is worth watching in CI, though the call sites there are unchanged.

Follow-up

This unblocks the React Native fix, which is a separate PR: startSessionReplay() there still re-applies the configured isEnabled on every call, so isEnabled: false plus a later start never records.

---

Note

Overview
LDReplay.start() now returns SessionReplayStartResult (aligned with Swift) so callers can tell whether replay actually began or was SAMPLED_OUT, UNRECOVERABLE_ERROR, etc. isRunning on that enum gives a simple boolean for bridges.

start(ignoreSampling = false) always tries to start capture, unlike isEnabled = true, which no-ops when already enabled—fixing the “enabled but not recording” case after sampleRate excludes a session. ignoreSampling = true forces recording until stop() resets sampling.

SessionReplayService exposes start(); the isEnabled setter delegates there for enable. PreInitReplayBuffer stores Start(ignoreSampling) / Stop so pre-init forced starts replay correctly at bind, returning UNAVAILABLE until then.

README documents the new return value and sampling behavior. Unit tests cover forwarding, pre-init buffering, and isRunning mapping.

^{Reviewed by Cursor Bugbot for commit 21fa7f2. Bugbot is set up for automated code reviews on this repo. Configure here.}