From 4b3d1e5154afb1c2febf3431d0c17cb6ae760292 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Fri, 30 Oct 2026 10:19:47 +0100 Subject: [PATCH 1/2] docs(unity): Describe how screenshots get captured Explain which events get a screenshot, that it's taken at the end of the frame and sent in the event's envelope, shared by events captured while it's taken, and read back asynchronously in the frame's own format unless SetBeforeSendScreenshot is set (getsentry/sentry-unity#2835, getsentry/sentry-unity#2917). List native screenshots per platform, document SetBeforeSendScreenshot and ScreenshotCompression, and that feedback screenshots are only taken on request. Supersedes #19972. --- .../unity/configuration/options/index.mdx | 18 +++++- .../enriching-events/screenshots/index.mdx | 63 ++++++++++++++++++- .../platforms/unity/troubleshooting/index.mdx | 2 +- docs/platforms/unity/user-feedback/index.mdx | 2 +- 4 files changed, 77 insertions(+), 8 deletions(-) diff --git a/docs/platforms/unity/configuration/options/index.mdx b/docs/platforms/unity/configuration/options/index.mdx index 23b124b910765..c3329cb13d27c 100644 --- a/docs/platforms/unity/configuration/options/index.mdx +++ b/docs/platforms/unity/configuration/options/index.mdx @@ -94,14 +94,20 @@ Grouping in Sentry is different for events with stack traces and without. As a r -Takes a screenshot of the application when an error happens and includes it as an attachment. +Attaches a screenshot of the game to events, such as errors and messages, and sends it in the same envelope as the event. Screenshots aren't attached in the Editor, in batch mode, or on WebGL. Learn more about enriching events with screenshots in our Screenshots documentation. -The quality of the attached screenshot. It can be set to `full`, `high`, `medium` or `low`. +The resolution of the attached screenshot. `Full` keeps the game's resolution, while `High`, `Medium`, and `Low` scale it down so that its longest side is at most 1920, 1280, or 854 pixels. + + + + + +The JPEG quality of the attached screenshot, from 1 to 100. Higher values result in better quality and larger files. @@ -191,7 +197,13 @@ By the time is executed, -A callback function that controls screenshot capture behavior. Return `false` to prevent a screenshot from being captured for a specific event. This allows for fine-grained control over when screenshots are included with error reports. +A callback function that controls screenshot capture behavior. Return `false` to prevent a screenshot from being attached to a specific event. It can run on a background thread and runs before and sampling. Learn more in our Screenshots documentation. + + + + + +A callback function that receives the screenshot as a `Texture2D` before it gets compressed, along with the event it belongs to. Modify or replace the texture and return it, or return `null` to discard the screenshot. Setting it makes the SDK read and compress screenshots on the main thread. Learn more in our Screenshots documentation. diff --git a/docs/platforms/unity/enriching-events/screenshots/index.mdx b/docs/platforms/unity/enriching-events/screenshots/index.mdx index d84cbce3b0a78..02ca6e1c615ac 100644 --- a/docs/platforms/unity/enriching-events/screenshots/index.mdx +++ b/docs/platforms/unity/enriching-events/screenshots/index.mdx @@ -22,12 +22,33 @@ Or, like so, if you're [configuring things programmatically](/platforms/unity/co options.AttachScreenshot = true; ``` -## Screenshot capture mechanism +Screenshots aren't attached in the Editor, in batch mode, or on WebGL. + +## Screenshot Capture Mechanism Since the Unity SDK internally consists of multiple SDKs, the mechanism with which a screenshot gets captured depends on where the error originates. -- C# errors from within your game will be captured through Unity's built-in [ScreenCapture](https://docs.unity3d.com/ScriptReference/ScreenCapture.html). This means that screenshots only contain things visible within your game. Overlays on top of your game will not be visible. -- Native errors get captured by their respective SDK. If you're using a native plugin to display an overlay and an error occurs then that SDK will try to capture a screenshot that contains the overlay. +### C# Errors + +Events captured by the C# SDK, such as exceptions, messages, and errors logged through `Debug.LogError`, get a screenshot. Transactions and user feedback don't. The SDK captures the screenshot through Unity's built-in [ScreenCapture](https://docs.unity3d.com/ScriptReference/ScreenCapture.html), so it only contains what your game renders. Overlays on top of your game aren't visible. + +The SDK takes the screenshot at the end of the frame, so it shows the fully rendered frame. Events captured on background threads get a screenshot as well, taken at the end of a following frame. Events captured while a screenshot is still being taken, for example several errors within the same frame, share it. Events that get dropped by or sampling don't trigger a screenshot. + +The screenshot gets scaled down according to `ScreenshotQuality` and compressed to JPEG according to `ScreenshotCompression`, and is attached as `screenshot.jpg`. It's sent in the same envelope as the event it belongs to. If the event gets dropped, for example because of rate limiting, its screenshot gets dropped along with it. + +To keep the cost of an error low, the main thread only issues the capture to the GPU. Where the device supports [asynchronous GPU readback](https://docs.unity3d.com/ScriptReference/SystemInfo-supportsAsyncGPUReadback.html), the SDK reads the screenshot back [asynchronously](https://docs.unity3d.com/ScriptReference/Rendering.AsyncGPUReadback.html) in the frame's own format and compresses it on a background thread. Otherwise, or when is set, it reads and compresses the screenshot on the main thread. On Nintendo Switch, screenshots are always read on the main thread. + +If the screenshot can't be taken, for example because the main thread doesn't reach the end of the frame within one second while it's blocked or the game is paused, the event gets sent without it. + +### Native Errors + +| Platform | Screenshot for native errors and crashes | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| iOS | Captured by sentry-cocoa, only with build time initialization | +| Windows | Captured by sentry-native when the game crashes | +| Android, macOS, Linux | None | + +These screenshots are taken by the native SDK, so they include overlays, and and don't apply to them. @@ -35,6 +56,42 @@ Screenshots might contain PII of your app. For example, if your game has a regis +## Customize Screenshot Capturing + +To decide whether an event gets a screenshot, use . It runs on the thread that captured the event, which can be a background thread, so don't call the Unity API from within it: + +```csharp +options.SetBeforeCaptureScreenshot(sentryEvent => +{ + // Don't attach screenshots while the payment screen is open + return !PaymentScreen.IsOpen; +}); +``` + +## Modifying or Discarding Screenshots + +To edit a screenshot before it's sent, for example to black out sensitive areas, or to discard it, use : + +```csharp +options.SetBeforeSendScreenshot((screenshot, sentryEvent) => +{ + // Return null to discard the screenshot instead + return screenshot; +}); +``` + +The callback runs once per screenshot, and events that share a screenshot also share the result. + + + +Since hands out the screenshot as a `Texture2D`, setting it makes the SDK read and compress every screenshot on the main thread, which stalls your game. + + + +## User Feedback + +Automatic screenshots don't get attached to user feedback. To attach one, pass `addScreenshot: true` to `SentrySdk.CaptureFeedback`. The SDK takes the screenshot right away, so call it from the main thread, ideally after `WaitForEndOfFrame`, so the frame is fully rendered. Feedback screenshots don't depend on , aren't passed to the screenshot callbacks, and are also taken in the Editor. Learn more in User Feedback. + ## Viewing Screenshots If one is available, you'll see a thumbnail of the screenshot when you click on a specific issue from the [**Issues**](https://demo.sentry.io/issues/) page. diff --git a/docs/platforms/unity/troubleshooting/index.mdx b/docs/platforms/unity/troubleshooting/index.mdx index f7a1319aa7946..57557090d8f44 100644 --- a/docs/platforms/unity/troubleshooting/index.mdx +++ b/docs/platforms/unity/troubleshooting/index.mdx @@ -96,4 +96,4 @@ Outside of this helper function, Sentry is unaware of any **real world** crash t ### Screenshot contain artifacts -The screenshot capture relies on Unity's `ScreenCapture.CaptureScreenshotIntoRenderTexture` function. When capturing errors in the Editor, this might lead to artifacts or scaling issues in the captured screenshot. +The screenshot capture relies on Unity's `ScreenCapture.CaptureScreenshotIntoRenderTexture` function. In the Editor, the SDK only takes screenshots for user feedback, and these can contain artifacts or scaling issues. diff --git a/docs/platforms/unity/user-feedback/index.mdx b/docs/platforms/unity/user-feedback/index.mdx index 02cd797a35a4d..65465e77ac9ac 100644 --- a/docs/platforms/unity/user-feedback/index.mdx +++ b/docs/platforms/unity/user-feedback/index.mdx @@ -27,7 +27,7 @@ The Unity SDK includes a ready-to-use prefab that provides a complete user feedb - Name (optional) - Email (optional) - Message/feedback (required) - - Screenshot (optional, taken automatically) + - Screenshot (optional, the user can choose to add one; the form hides itself before the screenshot gets taken) ### Adding the Prefab to Your Scene From f2b53c8ba0f62ef216274a5bb04fdb137a75a515 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Fri, 30 Oct 2026 11:02:24 +0100 Subject: [PATCH 2/2] docs(unity): Fix screenshot statements found in fact-check --- docs/platforms/unity/enriching-events/screenshots/index.mdx | 4 ++-- docs/platforms/unity/user-feedback/index.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/unity/enriching-events/screenshots/index.mdx b/docs/platforms/unity/enriching-events/screenshots/index.mdx index 02ca6e1c615ac..514fba3fadf24 100644 --- a/docs/platforms/unity/enriching-events/screenshots/index.mdx +++ b/docs/platforms/unity/enriching-events/screenshots/index.mdx @@ -36,9 +36,9 @@ The SDK takes the screenshot at the end of the frame, so it shows the fully rend The screenshot gets scaled down according to `ScreenshotQuality` and compressed to JPEG according to `ScreenshotCompression`, and is attached as `screenshot.jpg`. It's sent in the same envelope as the event it belongs to. If the event gets dropped, for example because of rate limiting, its screenshot gets dropped along with it. -To keep the cost of an error low, the main thread only issues the capture to the GPU. Where the device supports [asynchronous GPU readback](https://docs.unity3d.com/ScriptReference/SystemInfo-supportsAsyncGPUReadback.html), the SDK reads the screenshot back [asynchronously](https://docs.unity3d.com/ScriptReference/Rendering.AsyncGPUReadback.html) in the frame's own format and compresses it on a background thread. Otherwise, or when is set, it reads and compresses the screenshot on the main thread. On Nintendo Switch, screenshots are always read on the main thread. +To keep the cost of an error low, the main thread only issues the capture to the GPU. Where the device supports [asynchronous GPU readback](https://docs.unity3d.com/ScriptReference/SystemInfo-supportsAsyncGPUReadback.html), the SDK reads the screenshot back [asynchronously](https://docs.unity3d.com/ScriptReference/Rendering.AsyncGPUReadback.html) and compresses it on a background thread. Otherwise, or when is set, it reads and compresses the screenshot on the main thread. On Nintendo Switch, screenshots are always read on the main thread. -If the screenshot can't be taken, for example because the main thread doesn't reach the end of the frame within one second while it's blocked or the game is paused, the event gets sent without it. +If the screenshot can't be taken, for example because the main thread doesn't reach the end of the frame within one second while it's blocked or the app is in the background, the event gets sent without it. ### Native Errors diff --git a/docs/platforms/unity/user-feedback/index.mdx b/docs/platforms/unity/user-feedback/index.mdx index 65465e77ac9ac..ecb9177e7eba7 100644 --- a/docs/platforms/unity/user-feedback/index.mdx +++ b/docs/platforms/unity/user-feedback/index.mdx @@ -27,7 +27,7 @@ The Unity SDK includes a ready-to-use prefab that provides a complete user feedb - Name (optional) - Email (optional) - Message/feedback (required) - - Screenshot (optional, the user can choose to add one; the form hides itself before the screenshot gets taken) + - Screenshot (optional, included by default and the user can uncheck it; the form hides itself before the screenshot gets taken) ### Adding the Prefab to Your Scene