feat: Flutter replay custom masking warning (#11778)

* feat: Flutte replay custom masking warning

* update replay privacy docs

* Update index.mdx

Author: vaind

docs/platforms/flutter/session-replay/index.mdx

@@ -56,12 +56,26 @@ Sampling allows you to control how much of your website's traffic will result in
 2. `onErrorSampleRate` - The sample rate for replays that are recorded when an error happens. This type of replay will record
    up to a minute of events prior to the error and continue recording until the session ends.
 
-Sampling starts as soon as a session begins. The `sessionSampleRate` is then evaluated. If the session is sampled, replay recording will start immediately. If not, `onErrorSampleRate` will be evaluated. If the session is sampled at this point, the replay will be buffered and will only be uploaded to Sentry if an error occurs.
+Sampling starts as soon as a session begins. The <PlatformIdentifier name="replays-session-sample-rate" /> is then evaluated. If the session is sampled, replay recording will start immediately. If not, <PlatformIdentifier name="replays-on-error-sample-rate" /> will be evaluated. If the session is sampled at this point, the replay will be buffered and will only be uploaded to Sentry if an error occurs. 
 
 ## Privacy
 
-The SDK is recording and aggressively redacting (masking) all text and images, according to the configuration in `options.experimental.replay`.
-You can tune this and add custom masking rules to fit your needs. For example, you can explicitly mask or unmask widgets by type,
+The SDK is recording and aggressively redacting (masking) all `Text`, `EditableText`, and `Image` widgets.
+Masking in the Sentry Flutter SDK is based on Widget *types*, e.g. `Image`, not the string representation of the type (i.e. we check whether
+a `widgetInstance` should be masked by checking `if (widgetInstance is Image)` instead of `if (widgetInstance.runtimeType == 'Image')`).
+This means we can ensure masking works regardless of obfuscation in release builds and also works for subclasses.
+However, it also means we can only automatically mask widgets that are part of the Flutter SDK itself.
+
+<Alert level="warning">
+We cannot mask widgets defined in various 3rd-party packages (because the type is not known in the Sentry Flutter SDK),
+even though many should be masked.
+
+Therefore, you need to consider the widgets your application uses and ensure they're masked correctly with custom masking rules.
+Examples of widgets that usually should be masked include (but are not limited to): VideoPlayer, WebView, Chart, etc.
+</Alert>
+
+You can tune this and add custom masking rules to fit your needs by adjusting the configuration in `options.experimental.replay`.
+For example, you can explicitly mask or unmask widgets by type,
 or you can even have a callback to decide whether a specific widget instance should be masked:
 
 ```dart