feat(session-replay-react-native): honor isEnabled: false and add initializeSessionReplay

[abelonogov-ld]

The bug

The README documents deferred recording as isEnabled: false plus a later startSessionReplay(), but that never recorded. startSessionReplay() re-applied the configured isEnabled, so for a deferred start it wrote the false straight back:

• iOS — LDReplay.shared.isEnabled = sessionReplayOptions.isEnabled
• Android — applyEnabled(localReplayOptions.enabled), which calls LDReplay.stop() on false

The same code is the plugin's lazy-initialization path, which is why it read the config at all: one method was doing double duty as "initialize, honoring config" and as the public "start recording". Those wants are contradictory, so this splits them.

The fix

	before	after
plugin auto-start	startSessionReplay()	initializeSessionReplay() — initializes, honors isEnabled
public start	startSessionReplay() — re-applied isEnabled	startSessionReplay() — initializes if needed, then always enables

Neither adapter writes false any more; stopSessionReplay() is the only thing that stops recording. That also fixes a quieter bug: a re-init — a JS soft/OTA reload re-running plugin setup, for instance — used to silently stop a recording an earlier startSessionReplay() had begun, because the native instance outlives the JS context.

configureAndStart feature-detects initializeSessionReplay, since a JS-only OTA update can run this bundle against an older native binary. Falling back to startSessionReplay() there is safe: honoring isEnabled on the first start is exactly the old binary's behavior.

Both platforms now also report why a start didn't record, instead of always resolving as success. They call LDReplay.start(ignoreSampling: false) and map the result identically: started / alreadyStarted and sampledOut resolve — honoring sampleRate is not a failure — while unavailable and unrecoverableError reject. start is used over isEnabled = true because the setter's no-change guard would otherwise swallow a start on a session that is enabled but not recording.

Dependency bumps

Both are needed for start(ignoreSampling:) and its result enum:

• iOS — LaunchDarklySessionReplay ~> 0.53.1 → ~> 0.56.0
• Android — launchdarkly-observability-android 0.66.1 → 0.69.0, which carries #783

Verification

• iOS, on device, against pod 0.56.0. A single configure, then both new paths firing as designed:

  [SR init] configure: ... enabled=false, sampleRate=1.0
  LaunchDarkly Session Replay started, version: 0.56.0
  [SR init] start: leaving recording off (isEnabled=false)   <- init honors the config
  [SR init] start: already initialized, forceEnable=true     <- explicit start overrides it
  

  Recording was confirmed positively, not by absence of errors: a control run with sampleRate: 0 logs Session Replay skipped by sampling, and that line is absent at sampleRate: 1.0.
• JS — 21/21, including that the plugin calls initializeSessionReplay and not startSessionReplay, that isEnabled: false does not force recording on, and the OTA fallback.
• Android — 10/10 against 0.69.0, including that both entry points reject a start that configure() never set up.

One coverage gap worth flagging: the Android result mapping sits after Handler.post, which the package's plain JVM unit tests cannot reach, so it is not covered here. The enum-to-behavior mapping itself is covered by the core SDK's tests in #783, and iOS has no adapter-level test for its equivalent either.

Other changes

• README gains a "Delaying recording" section and an isEnabled row in the options table, and the sampleRate description no longer implies it only applies via isEnabled.
• The example app now exercises the deferred path as a user would, replacing the configure-with-isEnabled: true workaround it needed before.

---

Note

Overview
Fixes deferred session replay: isEnabled: false plus a later startSessionReplay() used to leave recording off because the native start path re-applied the configured isEnabled (and could even stop an active recording on JS re-init).

The plugin now auto-starts via initializeSessionReplay(), which initializes native replay/observability and only turns on recording when isEnabled is true. startSessionReplay() still initializes if needed but always enables recording, without another configure call. Only stopSessionReplay() stops recording.

iOS and Android adapters take a forceEnable flag, stop toggling enabled off on start, and call LDReplay.start(ignoreSampling: false) with mapped outcomes (sampledOut succeeds; unavailable / unrecoverable errors reject). Native deps are bumped (LaunchDarklySessionReplay ~> 0.56.0, launchdarkly-observability-android 0.69.0). JS adds OTA fallback when initializeSessionReplay is missing, README/docs for delaying recording, example Start replay button, and expanded tests.

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6d3a1b8. Configure here.}