Screenshots

Sentry makes it possible to automatically take a screenshot and include it as an attachment when a user experiences an error, an exception or a crash.

This feature is only available for SDKs with a user interface, like the ones for mobile and desktop applications. It's also limited by whether taking a screenshot is possible or not. For example, in some environments, like native iOS, taking a screenshot requires the UI thread, which often isn't available in the event of a crash. Another example where a screenshot might not be available is when the event happens before the screen starts to load. So inherently, this feature is a best effort solution.

Enabling Screenshots

Because screenshots may contain PII, they are an opt-in feature.

Enable screenshots by setting the attachScreenshot option to true and wrap your root widget with SentryWidget.

await SentryFlutter.init(
  (options) {
    options.attachScreenshot = true;
  },
  appRunner: () => runApp(
    SentryWidget(
      child: MyApp(),
    ),
  ),
);

Customize Screenshot Capturing

By default, Flutter limits screenshot captures to once every 2 seconds to minimize performance impact. While this debounce interval cannot be changed, you can customize capture behavior by implementing the beforeCaptureScreenshot callback in SentryFlutter.init.

This callback gives you fine-grained control over screenshot captures based on event and hint data, allowing you to implement conditional logic.

Return true to capture the screenshot, or false to skip it.

options.beforeCaptureScreenshot = (event, hint, shouldDebounce) async {
  // If shouldDebounce is active, skip capturing
  if (shouldDebounce) {
    return false;
  }
  // Capture screenshot if it's a fatal event
  return event.level == SentryLevel.fatal;
};

Redact Screenshots via masking

The masking feature is enabled by default for screenshots, but can be disabled or configured by adjusting the options.privacy option.

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. This approach allows the SDK to automatically mask widgets that are part of the Flutter SDK itself. However, for third-party widgets, you need to manually configure the privacy settings to mask their content. Read more about Third Party Widgets below.

Privacy Configuration

The following options can be configured in the options.privacy field of your Sentry Flutter SDK, in SentryFlutter.init((options) { ... }):

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:

options.privacy.mask<IconButton>();
options.privacy.unmask<Image>();
options.privacy.maskCallback<Text>(
    (Element element, Text widget) =>
        (widget.data?.contains('secret') ?? false)
            ? SentryMaskingDecision.mask
            : SentryMaskingDecision.continueProcessing);

To disable masking for Screenshots and Session Replay (not to be used on applications with sensitive data):

options.privacy.maskAllText = false;
options.privacy.maskAllImages = false;

Third Party Widgets

The Sentry Flutter SDK cannot automatically mask widgets from third party packages. You need to manually configure the privacy configuration to mask the content of these widgets.

For example, if you are using the FlutterMap package, you need to add the following privacy configuration:

options.privacy.mask<FlutterMap>();

Viewing Screenshots

If one is available, you'll see a thumbnail of the screenshot when you click on a specific issue from the Issues page.

Once you've clicked on the event ID of a specific issue, you'll be able to see an overview of all the attachments as well as associated events in the "Attachments" tab.