Session Replay: support custom User Feedback flows without promoting buffer mode on capture

首先检查当前移动端 replay 在 flush()、pause()、stop() 和 startBuffering() 周围的生命周期，包括日志中提到的 Android ReplayCache.persistSegmentValues 和 BufferCaptureStrategy.stop 路径。将内置的反馈协调机制与自定义流程的需求进行比较，并与 iOS 协调 API 设计。当自定义反馈能够保留、附加或丢弃 buffer，排除表单输入，并在不进行 promotion 且不破坏连续性的情况下恢复 buffering 时，即视为完成。

Problem Statement

For custom in-app User Feedback flows on mobile, there is currently no clean way to associate feedback with the pre-feedback replay context without changing replay lifecycle semantics.

Today, the closest workaround in buffer mode is roughly:

1. custom feedback UI opens
2. call replay.flush()
3. call replay.pause() to avoid recording form entry
4. on submit, send feedback with that replay id attached
5. optionally replay.stop() + replay.startBuffering() to return to normal buffering

This is not equivalent to the behavior customers want.

What customers want

When a custom feedback form opens, they want to:

1. preserve the last ~30 seconds before the form opened
2. avoid recording the user filling out the form
3. attach that preserved replay to the feedback if the user submits
4. avoid sending anything if the user cancels
5. return to normal buffer-mode behavior afterward

Why the current API is not enough

flush() is too strong for this use case.

In buffer mode, flush() does not just send the buffered replay. It also promotes the current replay from buffer mode to session mode for the rest of that replay's lifetime.

That creates several problems:

• it changes replay behavior after feedback-open
• cancel / dismiss semantics are awkward
• returning to buffer mode requires stopping and starting a new replay
• stopping and restarting breaks continuity and creates a new replay id / timeline
• the workaround is brittle because it coordinates several async lifecycle operations

pause() and stop() also do not solve the core problem on their own:

• pause() prevents further recording but does not create a stable "frozen buffer handle"
• stop() ends the replay entirely rather than preserving and deferring attachment cleanly

Current behavior

This is especially visible for custom mobile feedback UIs.

If the host app owns the feedback UI lifecycle, the SDK does not have a public API for:

• "feedback opened"
• "freeze current buffer now"
• "attach this preserved replay later on submit"
• "discard it on cancel"
• "resume buffering without promotion"

The built-in feedback UI can coordinate replay behavior internally, but custom flows cannot.

Requested behavior

Expose a supported public API for custom feedback flows that separates:

• freeze/preserve current buffered replay context
  from
• flush and promote into session mode

In other words, the missing primitive is something like:

• preserve current rolling buffer at feedback-open
• optionally pause/exclude the form interval
• attach/send the preserved replay on submit
• discard it on cancel
• resume normal buffering behavior afterward

The exact API shape is open, but the semantics are the important part.

Example use case

A customer has Replay running in buffer mode and a custom in-app bug report UI.

A user encounters a bug, opens the feedback form, types for 20-30 seconds, and submits.

Expected result:

• the attached replay primarily shows the lead-up to the bug and the moment the user decided to report it
• the form-entry period is excluded or not dominant
• the SDK can return to buffer mode cleanly afterward

Actual result today:

• if replay is captured at submit time, the replay mostly shows the user filling out the form
• if the app uses flush() as a workaround, replay is promoted from buffer mode to session mode
• if the app stops and restarts replay to get back to buffering, continuity is broken

Additional context

This came up from a real customer integration using custom in-app feedback with mobile Session Replay.

We also saw Android logs during workaround testing that may indicate lifecycle/storage brittleness during this flow:

Failed to execute task CaptureStrategy.runInBackground
java.io.IOException: No such file or directory
...
at io.sentry.android.replay.ReplayCache.persistSegmentValues
...
at io.sentry.android.replay.capture.BufferCaptureStrategy.stop

That log may be a separate bug, but it reinforces that the current workaround path is not robust enough to treat as the intended solution.

Cross-platform coordination required

This is a cross-platform issue; we'll want to coordinate any solution with iOS. Writing a develop-docs PR could be a good place to start.

Related

• getsentry/sentry-javascript#16541 fixed the built-in JS feedback widget behavior
• getsentry/sentry-javascript#10581 is adjacent but broader / older
• this issue is specifically about custom mobile feedback flows and the lack of a public replay lifecycle primitive for them

Possible acceptance criteria

• A host app can preserve the current buffer at feedback-open without promoting the replay to session mode
• A host app can later attach/send that preserved replay on feedback submit
• A host app can discard the preserved replay on cancel
• A host app can exclude or pause the form-entry interval
• A host app can resume normal buffer-mode recording afterward without forcing a new full-session replay model