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. You can enable screenshots as shown below:

<application>
  <meta-data
    android:name="io.sentry.attach-screenshot"
    android:value="true"
  />
</application>

Customize Screenshot Capturing

Because capturing screenshots can be a resource-intensive operation on Android, it's limited to one screenshot every 2 seconds using a debouncing mechanism. This behavior can be overruled if you supply a BeforeCaptureCallback for screenshots in the SentryAndroidOptions.

The BeforeCaptureCallback also allows you to customize the behavior based on event data, so you can decide when to capture a screenshot and when not to. For example, you can decide to only capture screenshots of crashed and fatal events:

import io.sentry.android.core.SentryAndroid;

SentryAndroid.init(this, options -> {
    options.setBeforeScreenshotCaptureCallback((event, hint, debounce) -> {
        // always capture crashed events
        if (event.isCrashed()) {
            return true;
        }

        // if debounce is active, skip capturing
        if (debounce) {
            return false;
        } else {
            // also capture fatal events
            return event.getLevel() == SentryLevel.FATAL;
        }
    });
});

Screenshot Masking

Screenshot masking allows you to mask sensitive data in screenshots before they are captured. You can customize this behavior to fit your needs.

dependencies {
  implementation 'io.sentry:sentry-android-replay:8.38.0'
}

Default Masking Behavior

Unlike Session Replay, screenshot masking is disabled by default. You can enable masking for all text and image content:

<application>
  <meta-data
    android:name="io.sentry.screenshot.mask-all-text"
    android:value="true"
  />
  <meta-data
    android:name="io.sentry.screenshot.mask-all-images"
    android:value="true"
  />
</application>

Mask by View Class

You can choose which type of view to mask or unmask by using addMaskViewClass or addUnmaskViewClass. These accept fully-qualified class names and apply to all subclasses of the specified class as well.

import io.sentry.android.core.SentryAndroid

SentryAndroid.init(this) { options ->
  options.screenshot.addMaskViewClass("com.example.MyCustomView")
  options.screenshot.addUnmaskViewClass("com.example.PublicLabel")
}

Mask by View Instance

You can mask or unmask specific view instances using extension functions from the sentry-android-replay module:

import io.sentry.android.replay.sentryReplayMask
import io.sentry.android.replay.sentryReplayUnmask

myTextView.sentryReplayMask()
myImageView.sentryReplayUnmask()

You can also set masking via XML layout tags:

<TextView
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:text="Sensitive data"
>
  <tag android:id="@id/sentry_privacy" android:value="mask" />
</TextView>

Alternatively, you can use the android:tag attribute with the sentry-mask or sentry-unmask string values:

<TextView
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:tag="sentry-mask"
  android:text="Sensitive data"
/>

In Java, you can use view tags with the sentry_privacy resource ID:

import io.sentry.android.replay.R;

view.setTag(R.id.sentry_privacy, "mask");
view.setTag(R.id.sentry_privacy, "unmask");

Jetpack Compose

For Jetpack Compose, use the sentryReplayMask() and sentryReplayUnmask() modifiers:

import io.sentry.android.replay.sentryReplayMask
import io.sentry.android.replay.sentryReplayUnmask

@Composable
fun MyScreen() {
  Column {
    Text(
      text = "Sensitive info",
      modifier = Modifier.sentryReplayMask()
    )
    Text(
      text = "Public info",
      modifier = Modifier.sentryReplayUnmask()
    )
  }
}

General Masking Rules

View Groups

• If a ViewGroup is marked as masked, all its child views will also be masked, even if some children would normally not be masked. This prioritizes safety and ensures no sensitive information is unintentionally exposed.

• If a ViewGroup is marked as unmasked, its child views don't automatically inherit this behavior. You'll need to explicitly mark each child view as unmasked if you want them to appear unmasked.

Masking Priority

Masking and unmasking rules are applied in the following order:

1. Check if a view is marked as unmasked via a tag/extension or modifier.
2. Check if a view is marked as masked via a tag/extension or modifier.
3. Check if a view's class is marked as unmasked via addUnmaskViewClass.
4. Check if a view's class is marked as masked via addMaskViewClass.

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.