Update Session Replay and Feedback Widget documentation (#14053)

Author: bruno-garcia

develop-docs/sdk/expected-features/index.mdx

@@ -66,7 +66,7 @@ ignore_transactions = ['GET /api/health','/api/v1/*']
 
 ## Rate Limiting
 
-Respect Sentry’s HTTP 429 `Retry-After` header, or, if the SDK supports multiple payload types (e.g. errors and transactions), the `X-Sentry-Rate-Limits` header. Outgoing SDK requests should be dropped during the backoff period.
+Respect Sentry's HTTP 429 `Retry-After` header, or, if the SDK supports multiple payload types (e.g. errors and transactions), the `X-Sentry-Rate-Limits` header. Outgoing SDK requests should be dropped during the backoff period.
 
 See <Link to="/sdk/expected-features/rate-limiting">Rate Limiting</Link> for details.
 
@@ -104,7 +104,7 @@ So users can easily spot errors during development, the SDK can automatically en
 
 ## In-App frames
 
-Stack parsing can tell which frames should be identified as part of the user’s application (as opposed to part of the language, a library, or a framework), either automatically or by user configuration at startup, often declared as a package/module prefix.
+Stack parsing can tell which frames should be identified as part of the user's application (as opposed to part of the language, a library, or a framework), either automatically or by user configuration at startup, often declared as a package/module prefix.
 
 ## Surrounding Source in Stack Trace
 
@@ -153,6 +153,16 @@ implement the `onCrashedLastRun` callback on the options. This callback gets cal
 terminated with a crash. The SDK should execute the callback only once during the entire run of the program to avoid multiple callbacks if there are multiple
 crash events to send.
 
+#### Session Replay Integration with Feedback Widgets
+
+When a feedback widget is added to an application and Session Replay's `onErrorSampleRate` is greater than 0, the SDK must sample the replay when the widget **opens**, not when the feedback is submitted. This timing is critical because:
+
+- Sampling when the widget opens captures the user's session leading up to the feedback moment
+- Sampling only when feedback is submitted would result in the replay buffer primarily showing the user typing their message, which provides minimal debugging context
+- The replay buffer should contain the user's actions and application state prior to encountering the issue they're reporting
+
+SDKs should trigger replay sampling and flushing as soon as the feedback widget becomes visible to the user, ensuring the complete context is captured regardless of whether the user ultimately submits the feedback.
+
 ### Backend Platforms
 
 On backend platforms, SDKs should document how to use the [last event ID](#retrieve-last-event-id) to prompt the user for feedback themselves.

develop-docs/sdk/telemetry/feedbacks.mdx

@@ -114,7 +114,7 @@ SDKs should implement a `beforeSendFeedback` callback to allow users to modify t
 
 ### Scope Data and Event Processors
 
-The scope is applied to the feedbacks, including tags, user, trace and contexts. The scope’s _event processors_ are invoked, too.
+The scope is applied to the feedbacks, including tags, user, trace and contexts. The scope's _event processors_ are invoked, too.
 
 ### Rate Limiting
 
@@ -127,3 +127,13 @@ There is no sample rate for feedbacks, as they are always sampled. However, a fe
 ### Session Replay Integration
 
 When sending feedback, SDKs are expected to flush the current Session Replay, if running. This ensures a meaningful replay recording exists and can be included in the `replay_id` attribute of the feedback context.
+
+#### Timing of Replay Sampling with Feedback Widgets
+
+For feedback widgets specifically, when Session Replay's `onErrorSampleRate` is greater than 0, SDKs must sample and flush the replay when the widget **opens**, not when the user submits the feedback. This timing is critical because:
+
+- The replay buffer captures the user's session leading up to opening the feedback widget, providing context about what the user experienced before deciding to provide feedback
+- If sampling only occurs on submission, the buffer would primarily contain the user's interactions with the feedback form itself (typing their message), which provides minimal debugging value
+- Early sampling ensures the complete user context is preserved regardless of whether the user ultimately submits the feedback
+
+This behavior ensures that developers receive meaningful session replay data that shows the user's experience prior to the feedback moment, rather than just their interaction with the feedback widget itself.