From df3c762bbd2f8427f4f842f1324de30980f89938 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 15:38:17 +0100 Subject: [PATCH 1/5] docs(unity): Fix data collected, privacy and enriching pages Describe the data the Unity SDK collects: the installation ID as the user, what SendDefaultPii adds, and the automatic app, os, device, gpu and unity contexts. Drop the HTTP and SQL sections that come from .NET. Document Unity's single global scope, list the C# scrubbing hooks and note that native crashes don't run them, fix the view hierarchy limits, keys and callbacks, and add Unity fingerprinting samples. --- .../unity/configuration/filtering.mdx | 6 ++ .../unity/data-management/data-collected.mdx | 76 ++++++++++--------- .../data-management/sensitive-data/index.mdx | 17 +++++ .../unity/enriching-events/context/index.mdx | 2 + .../unity/enriching-events/scopes/index.mdx | 47 ++---------- .../enriching-events/screenshots/index.mdx | 4 +- .../unity/enriching-events/tags/index.mdx | 2 +- .../enriching-events/view-hierarchy/index.mdx | 51 ++++++++++--- .../unity/usage/sdk-fingerprinting/index.mdx | 6 ++ .../set-fingerprint/basic/unity.mdx | 13 ++++ .../database-connection/unity.mdx | 13 ++++ .../set-fingerprint/rpc/unity.mdx | 31 ++++++++ 12 files changed, 177 insertions(+), 91 deletions(-) create mode 100644 platform-includes/set-fingerprint/basic/unity.mdx create mode 100644 platform-includes/set-fingerprint/database-connection/unity.mdx create mode 100644 platform-includes/set-fingerprint/rpc/unity.mdx diff --git a/docs/platforms/unity/configuration/filtering.mdx b/docs/platforms/unity/configuration/filtering.mdx index 06b922a4b6884..fa011738e01fa 100644 --- a/docs/platforms/unity/configuration/filtering.mdx +++ b/docs/platforms/unity/configuration/filtering.mdx @@ -20,6 +20,12 @@ All Sentry SDKs support the callback + + +The callback runs in C# only. Native crashes are captured by the native SDKs and don't run it. + + + Note also that breadcrumbs can be filtered, as discussed in [our Breadcrumbs documentation](/product/issues/issue-details/breadcrumbs/). ## Filtering Transaction Events diff --git a/docs/platforms/unity/data-management/data-collected.mdx b/docs/platforms/unity/data-management/data-collected.mdx index 8d209e8d7bbce..454b631417723 100644 --- a/docs/platforms/unity/data-management/data-collected.mdx +++ b/docs/platforms/unity/data-management/data-collected.mdx @@ -6,79 +6,81 @@ sidebar_order: 1 Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. -The category types and amount of data collected vary, depending on the integrations you've enabled in the Sentry SDK. Here's a list of data categories the Sentry .NET SDK collects: +The data the Sentry Unity SDK collects depends on the options and integrations you enable. Here's a list of data categories it collects: -## HTTP Headers +## HTTP Requests and Database Queries -By default, the Sentry SDK sends HTTP headers to Sentry but redacts any headers that may contain sensitive data. (See the [list of headers](https://github.com/getsentry/sentry-dotnet/blob/main/src/Sentry/Internal/RedactedHeaders.cs#L7) that are redacted). +The Unity SDK doesn't instrument HTTP requests or databases, so it doesn't send request URLs, headers, cookies, or SQL queries. -## Cookies +## Information About the User -By default, the Sentry SDK doesn't send cookies. +The SDK always sends an anonymous installation ID as `user.id`. On iOS, Android, and Nintendo Switch, it's the native SDK's installation ID, so C# events and native crashes share the same user. -If you want to send cookies, set the option `SendDefaultPii = true` when initializing the Sentry SDK. +If `SendDefaultPii` is set to `true`, the SDK also sends: -A [data scrubber](/platforms/dotnet/data-management/sensitive-data/) can be used to filter information before sending data to Sentry. +- The user's IP address. See [Users' IP Address](#users-ip-address). +- The device unique identifier. See [Device Unique Identifier](#device-unique-identifier). +- The device name. See [Device Name](#device-name). +- The operating system's user name as `user.username`, if **Auto Set UserName** (`IsEnvironmentUser`) is also enabled. Learn more in [Options](/platforms/unity/configuration/options/#IsEnvironmentUser). -Any [sensitive cookies](https://github.com/getsentry/relay/blob/249971e1702991c64cf0f7f89773fb019ffb4a95/relay-pii/src/convert.rs#L235-L263) that the SDK does send will be stripped by Relay before Sentry stores these. - -## Information About Logged-in User - -By default, the Sentry SDK doesn't send any information about the logged-in user, such as email address, user ID, or username. Even if enabled, the type of logged-in user information you'll be able to send depends on the integrations you enable in Sentry's SDK. Most integrations won't send any user information. Some will only set the user ID, but there are a few that will set the user ID, username, and email address. - -To start sending logged-in user information, set the option `SendDefaultPii = true` when initializing the Sentry SDK. +To send your own user information, [identify the user](../../enriching-events/identify-user/). ## Users' IP Address By default, the Sentry SDK doesn't send the user's IP address. -To enable sending the user's IP address, set the option `SendDefaultPii = true` when initializing the Sentry SDK. +If `SendDefaultPii` is set to `true`, the SDK sets the user's IP address to `{{auto}}`, and Sentry fills in the IP address the event came from. -Even if enabled, whether you're able to send the user's IP address or not, will depend on the integrations you enable in Sentry's SDK. Most integrations won't set the user's IP address at all. +You can [prevent Sentry from storing IP Addresses](../../enriching-events/identify-user/#ip_address) either by configuring this in the ["Security & Privacy"](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/security-and-privacy/) settings of your Sentry project or using [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). -You can [prevent Sentry from storing IP Addresses](/platforms/native/enriching-events/identify-user/#ip_address) either by configuring this in the ["Security & Privacy"](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/security-and-privacy/) settings of your Sentry project or using [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). - -## Request URL +## Device Unique Identifier -By default, the [HttpRequestUrl](https://learn.microsoft.com/en-us/dotnet/api/System.UriComponents) of outgoing and incoming HTTP requests is **always sent to Sentry**. This includes the Scheme, Host, Port, LocalPath, and Query data. +The Sentry SDK does not set the `Device Unique Identifier` by default. -If `SendDefaultPii` is set to `true` then the [AbsoluteUri](https://learn.microsoft.com/en-us/dotnet/api/System.UriComponents) of outgoing and incoming HTTP requests will be sent to Sentry (including the Scheme, UserInfo, Host, Port, LocalPath, Query, and Fragment data). +If `SendDefaultPii` is set to `true` then the SDK will capture `SystemInfo.deviceUniqueIdentifier` automatically and send this with any event. -Depending on your application, this could contain PII data. +## Device Name -## Request Query String +By default, the Sentry SDK doesn't send the device name. -The full request query string of outgoing and incoming HTTP requests is **always sent to Sentry**. Depending on your application, this could contain PII data. +If `SendDefaultPii` is set to `true`, the SDK sends the device's name as `device.name`. On desktop, this is the computer name. -## SQL Queries +The SDK never sends `ServerName`. -While SQL queries are sent to Sentry, neither the full SQL query (`SELECT * FROM users WHERE email = 'joe@shmoe.com'`), nor the values of its parameters will ever be sent. A parameterized version of the query (`SELECT * FROM users WHERE email = @email`) is sent instead. +## General Device Information -## Device Unique Identifier +The SDK collects information about the app, the operating system, the device, the GPU, and Unity, and sends it with every event. It sets these contexts when the SDK starts: -The Sentry SDK does not set the `Device Unique Identifier` by default. +- `app`: the product name, the start time, and whether it's a debug or release build. +- `os`: the operating system description. On Xbox and PlayStation, it's the name of the console. +- `device`: the processor count, CPU, time zone, vibration support, device type, model, and system memory. In the Unity Editor, the device is marked as a simulator. +- `gpu`: the GPU's ID, name, vendor name and ID, memory, graphics API and version, maximum texture size, shader level, multithreaded rendering, and support for non-power-of-two textures, instancing, ray tracing, and compute and geometry shaders. +- `unity`: the Editor version, install mode, target frame rate, copy texture support, and rendering threading mode. -If `SendDefaultPii` is set to `true` then the SDK will capture `SystemInfo.deviceUniqueIdentifier` automatically and send this with any event. +For events captured on the main thread, the SDK also adds: -## Machine Name +- The app's allocated memory (`app.memory`). +- The battery status and level, and the device orientation. +- The connection type, on iOS and Android. +- The name of the active scene, in the Unity Editor and in IL2CPP builds. -The Sentry SDK does not send the machine name by default. +Every event also records whether it was captured on the main thread (`unity.is_main_thread`). -If you assign a value to the `ServerName` in the Sentry options then Sentry SDK will send this with any events. +## Breadcrumbs -Otherwise, if `SendDefaultPii` is set to true then the Sentry SDK will capture the `Environment.MachineName` automatically and send this with any events. +The SDK records Unity log messages, scene changes, and app lifecycle events as breadcrumbs, and sends them with events. Log messages can contain PII, depending on what your game logs. Learn more in [Breadcrumbs](../../enriching-events/breadcrumbs/). -## General Device Information +## Screenshots and View Hierarchy -The Sentry SDK collects information about the device, such as the version and build of your operating system, CPU and GPU details etc. This information is sent to Sentry by default. +Screenshots and the view hierarchy are opt-in. Both can contain PII, such as names shown on screen or in the names of GameObjects. Learn more in [Screenshots](../../enriching-events/screenshots/) and [View Hierarchy](../../enriching-events/view-hierarchy/). ## Data captured by Mobile SDKs -On mobile platforms, the Sentry SDK for .NET can also capture data indirectly via the Android and iOS SDKs. You should refer to the documentation for those SDKs for more information on what data is captured. +On mobile platforms, the Sentry SDK for Unity can also capture data through the Android and iOS SDKs. Refer to the documentation for those SDKs for more information on what data they capture. - [Android](/platforms/android/data-management/data-collected/) - [iOS](/platforms/apple/data-management/data-collected/) ## Data captured by the Native SDK -When compiling for Windows, Linux or other platforms that use Sentry Native, you should refer to [data captured by the Native SDK](/platforms/native/data-management/data-collected/) to understand what data is sent with those events. +When compiling for Windows, Linux or other platforms that use Sentry Native, refer to [data captured by the Native SDK](/platforms/native/data-management/data-collected/) to understand what data is sent with those events. diff --git a/docs/platforms/unity/data-management/sensitive-data/index.mdx b/docs/platforms/unity/data-management/sensitive-data/index.mdx index 393cd2b10e6e2..3644a81c2fe6a 100644 --- a/docs/platforms/unity/data-management/sensitive-data/index.mdx +++ b/docs/platforms/unity/data-management/sensitive-data/index.mdx @@ -23,6 +23,23 @@ We offer the following options depending on your legal and operational needs: - [configuring server-side scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) to ensure Sentry does _not store_ data. Configuration changes are done in the Sentry UI and apply immediately for new events. - [running a local Relay](/product/relay/) on your own server between the SDK and Sentry, so that data is _not sent to_ Sentry while configuration can still be applied without deploying. +## Scrubbing Data in the SDK + +To remove sensitive data before it leaves the device, use these callbacks: + +- [`SetBeforeSend`](/platforms/unity/configuration/options/#SetBeforeSend): edit or drop error events. +- [`SetBeforeBreadcrumb`](/platforms/unity/configuration/options/#SetBeforeBreadcrumb): edit or drop breadcrumbs. +- [`SetBeforeSendTransaction`](/platforms/unity/configuration/options/#SetBeforeSendTransaction): edit or drop transactions. +- `SetBeforeSendLog`: edit or drop logs. Learn more in [Logs](/platforms/unity/logs/#before-log-handler). +- [`SetBeforeCaptureScreenshot`](/platforms/unity/configuration/options/#SetBeforeCaptureScreenshot) and [`SetBeforeSendScreenshot`](/platforms/unity/configuration/options/#SetBeforeSendScreenshot): skip, edit, or drop screenshots. +- [`SetBeforeCaptureViewHierarchy`](/platforms/unity/configuration/options/#SetBeforeCaptureViewHierarchy) and [`SetBeforeSendViewHierarchy`](/platforms/unity/configuration/options/#SetBeforeSendViewHierarchy): skip, edit, or drop the view hierarchy. + + + +These callbacks run in C# only. Native crashes, from C and C++, Java and Kotlin, or Objective-C and Swift code, are captured by the native SDKs and don't run them. Breadcrumbs reach the native SDKs after `SetBeforeBreadcrumb` runs, so breadcrumbs you edit or drop there stay that way in native crashes. To remove other data from native crashes, use [server-side scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). + + + Ensure that your team is aware of your company's policy around what can and cannot be sent to Sentry. We recommend determining this policy early in your implementation and communicating it as well as enforcing it via code review. diff --git a/docs/platforms/unity/enriching-events/context/index.mdx b/docs/platforms/unity/enriching-events/context/index.mdx index fa54f28d3fe42..4202c3d4270d9 100644 --- a/docs/platforms/unity/enriching-events/context/index.mdx +++ b/docs/platforms/unity/enriching-events/context/index.mdx @@ -31,6 +31,8 @@ Custom contexts are only added to C# events. Native crashes don't include them. There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. +The SDK sets five contexts itself: `app`, `os`, `device`, `gpu`, and `unity`. Don't use these names for your own contexts. For example, setting your own `device` context replaces the one the SDK collects. See the [list of data in these contexts](../../data-management/data-collected/#general-device-information). + Learn more about conventions for common contexts in the [contexts interface developer documentation](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/contexts/). ## Size Limitations diff --git a/docs/platforms/unity/enriching-events/scopes/index.mdx b/docs/platforms/unity/enriching-events/scopes/index.mdx index c70db4f1f633c..f7c930371a534 100644 --- a/docs/platforms/unity/enriching-events/scopes/index.mdx +++ b/docs/platforms/unity/enriching-events/scopes/index.mdx @@ -1,44 +1,15 @@ --- -title: Scopes and Hubs -description: "SDKs will typically automatically manage the scopes for you in the framework integrations. Learn what a scope is and how you can use it to your advantage." +title: Scopes +description: "Learn what the scope is in the Sentry Unity SDK, and how to attach data to all events or to a single event." --- -When an event is captured and sent to Sentry, SDKs will merge that event data with extra -information from the current scope. SDKs will typically automatically manage the scopes -for you in the framework integrations and you don't need to think about them. However, -you should know what a scope is and how you can use it for your advantage. +When an event is captured and sent to Sentry, the SDK merges that event with the data stored on the scope, such as [tags](../tags/), [contexts](../context/), [breadcrumbs](../breadcrumbs/), and the [user](../identify-user/). -## What's a Scope, What's a Hub +## How the Scope Works -You can think of the hub as the central point that our SDKs use to route an -event to Sentry. When you call `init()` a hub is created and a client and a -blank scope are created on it. That hub is then associated with the current -thread and will internally hold a stack of scopes. +Unity runs in global mode, with one scope shared by every thread. Data you set on the scope stays there and is added to every event until you change or clear it. `PushScope` has no effect. -The scope will hold useful information that should be sent along with the -event. For instance [contexts](../context/) or -[breadcrumbs](../breadcrumbs/) are stored on -the scope. When a scope is pushed, it inherits all data from the parent scope -and when it pops all modifications are reverted. - -The default SDK integrations will push and pop scopes intelligently. For -instance web framework integrations will create and destroy scopes around your -routes or controllers. - -## How the Scope and Hub Work - -As you start using an SDK, a scope and hub are automatically created for you out -of the box. It's unlikely that you'll interact with the hub directly unless you're -writing an integration or you want to create or destroy scopes. Scopes, on the -other hand are more user facing. You can call at any point in -time to modify data stored on the scope. This is useful for doing things like -[modifying the context](../context/). - - - -When you call a global function such as internally Sentry -discovers the current hub and asks it to capture an event. Internally the hub will -then merge the event with the topmost scope's data. +Native crashes include most of this data too. Learn more in Scope Sync. ## Configuring the Scope @@ -55,11 +26,9 @@ You can also apply this configuration when unsetting a user at logout: To learn what useful information can be associated with scopes see [the context documentation](../context/). -## Local Scopes +## Attaching Data to a Single Event -We also support pushing and configuring a scope within a single call. This is typically -called , or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if -you only want to send data for one specific event. +To attach data to one event only, use the scope callback of the capture methods. ### Using Scope Callback Parameter diff --git a/docs/platforms/unity/enriching-events/screenshots/index.mdx b/docs/platforms/unity/enriching-events/screenshots/index.mdx index 514fba3fadf24..098976b892ea7 100644 --- a/docs/platforms/unity/enriching-events/screenshots/index.mdx +++ b/docs/platforms/unity/enriching-events/screenshots/index.mdx @@ -16,9 +16,9 @@ Because screenshots may contain attachment. -This feature only applies to SDKs with a user interface, such as the ones for mobile and desktop applications. Capturing the scene and creating the view hierarchy requires the UI thread and in the event of a crash, that might not be available. Another example where the view hierarchy might not be available is when the event happens before the screen starts to load. So inherently, this feature is a best effort solution. +The SDK captures the view hierarchy of the active scene only, and only for events captured on the main thread. Events captured on background threads and native crashes don't get one. It works in the Unity Editor and on WebGL too. ## Enabling View Hierarchy Attachments @@ -17,9 +17,9 @@ View hierarchy debugging is an opt-in feature. You can enable attaching the view ![Options Screenshot Configuration](./img/editor-window.png) -Or, like so, if you're [configuring things programmatically](/platforms/unity/configuration/options/): +Or, like so, if you're [configuring things programmatically](/platforms/unity/configuration/options/programmatic-configuration/): -```csharp {tabTitle:ScriptableOptionsConfiguration} +```csharp options.AttachViewHierarchy = true; ``` @@ -27,19 +27,19 @@ options.AttachViewHierarchy = true; Because capturing view hierarchy can be a resource-intensive operation as the SDK traverses the scene at the time of an error, there are several controls available to you. - + Allows you to limit the amount of gameobjects to be traversed and included in the view hierarchy. - + Allows you to limit the maximum depth of child-gameobject the SDK will attempt to traverse to include in the view hierarchy. - + Allows you to limit the maximum count of child-gameobjects per individual gameobject the SDK will attempt to include in the view hierarchy. @@ -53,6 +53,33 @@ options.MaxViewHierarchyRootObjects = 100; options.MaxViewHierarchyObjectChildCount = 20; ``` +## Modifying or Discarding the View Hierarchy + +To decide whether an event gets a view hierarchy, use . Return `false` to skip it: + +```csharp +options.SetBeforeCaptureViewHierarchy(sentryEvent => +{ + // Don't capture the view hierarchy for warnings + return sentryEvent.Level != SentryLevel.Warning; +}); +``` + +To edit the view hierarchy before it's sent, or to discard it, use . Return `null` to discard it: + +```csharp +options.SetBeforeSendViewHierarchy((viewHierarchy, sentryEvent) => +{ + // The root node is the scene, and its children are the root GameObjects + foreach (var scene in viewHierarchy.Windows) + { + scene.Children.RemoveAll(node => node.Type == "AccountScreen"); + } + + return viewHierarchy; +}); +``` + ## Viewing View Hierarchy Attachments View hierarchies appear in the "Attachments" tab, where you can view all attachments, as well as associated events. Click the event ID to open the [Issue Details](/product/issues/issue-details/) page of that specific event. @@ -61,12 +88,12 @@ View hierarchies appear in the "Attachments" tab, where you can view all attachm On the **Issue Details** page, you can interact with the view hierarchy attachment in a section called "View Hierarchy". This section represents the state of your scene at the time of an error event. There are two displays: a tree view, and detailed view for a selected node. You can select nodes in the tree to view the properties collected by the SDK. The SDK will report on the following keys for each node in the view: -- `Tag` The gameobject's tag -- `Position` The gameobject's position -- `Rotation` The gameobject's rotation in euler angles -- `Scale` The gameobject's scale -- `Active` Whether the gameobject was active -- `Extra` A list of names of all the attached MonoBehaviours on that gameobject +- `tag` The gameobject's tag +- `position` The gameobject's position +- `rotation` The gameobject's rotation in euler angles +- `scale` The gameobject's local scale +- `active` Whether the gameobject itself was active (`activeSelf`) +- `extras` The type names of all components attached to the gameobject This feature can be used as an exploratory tool to debug reference issues, or gain a better understanding of the relationship between gameobjects. diff --git a/docs/platforms/unity/usage/sdk-fingerprinting/index.mdx b/docs/platforms/unity/usage/sdk-fingerprinting/index.mdx index aad876bd72c0b..4c44214d11f39 100644 --- a/docs/platforms/unity/usage/sdk-fingerprinting/index.mdx +++ b/docs/platforms/unity/usage/sdk-fingerprinting/index.mdx @@ -13,6 +13,12 @@ By default, Sentry will run one of our built-in grouping algorithms to generate In supported SDKs, you can override Sentry's default grouping that passes the fingerprint attribute as an array of strings. The length of a fingerprint's array is not restricted. This works similarly to the [fingerprint rules functionality](/concepts/data-management/event-grouping/fingerprint-rules/), which is always available and can achieve similar results. + + +Fingerprints you set in the SDK only apply to events captured in C#. Native crashes keep the default grouping. To group them, use [Fingerprint Rules](/concepts/data-management/event-grouping/fingerprint-rules/). + + + ## Basic Example In the most basic case, values are passed directly: diff --git a/platform-includes/set-fingerprint/basic/unity.mdx b/platform-includes/set-fingerprint/basic/unity.mdx new file mode 100644 index 0000000000000..dbf633a92bc8f --- /dev/null +++ b/platform-includes/set-fingerprint/basic/unity.mdx @@ -0,0 +1,13 @@ +```csharp +// Add this to your SentryOptionsConfiguration.Configure method +options.SetBeforeSend(@event => +{ + // SaveFileCorruptedException is an exception defined by your game + if (@event.Exception is SaveFileCorruptedException) + { + @event.SetFingerprint(new[] { "save-file-corrupted" }); + } + + return @event; +}); +``` diff --git a/platform-includes/set-fingerprint/database-connection/unity.mdx b/platform-includes/set-fingerprint/database-connection/unity.mdx new file mode 100644 index 0000000000000..2ce86ca3a70d2 --- /dev/null +++ b/platform-includes/set-fingerprint/database-connection/unity.mdx @@ -0,0 +1,13 @@ +```csharp +// Add this to your SentryOptionsConfiguration.Configure method +options.SetBeforeSend(@event => +{ + // BackendConnectionException is an exception defined by your game + if (@event.Exception is BackendConnectionException) + { + @event.SetFingerprint(new[] { "backend-connection-error" }); + } + + return @event; +}); +``` diff --git a/platform-includes/set-fingerprint/rpc/unity.mdx b/platform-includes/set-fingerprint/rpc/unity.mdx new file mode 100644 index 0000000000000..c99b484c884ed --- /dev/null +++ b/platform-includes/set-fingerprint/rpc/unity.mdx @@ -0,0 +1,31 @@ +```csharp +using System; +using System.Net; + +public class MyRpcException : Exception +{ + // The name of the RPC function that was called (e.g. "getPlayerInventory") + public string Function { get; set; } + + // For example a HTTP status code returned by the server. + public HttpStatusCode Code { get; set; } +} + +// Add this to your SentryOptionsConfiguration.Configure method +options.SetBeforeSend(@event => +{ + if (@event.Exception is MyRpcException ex) + { + @event.SetFingerprint( + new[] + { + "{{ default }}", + ex.Function, + ex.Code.ToString(), + } + ); + } + + return @event; +}); +``` From 9387762e0f4535521e9d2abebd119a0b6a8f8c9a Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 15:47:44 +0100 Subject: [PATCH 2/5] docs(unity): Address review of data collected and privacy docs Describe failed HTTP request capture in the Cocoa SDK and through SentryHttpMessageHandler, what logs carry, and how the installation ID is stored and replaced. List each SendDefaultPii item once, and add the runtime, culture and thread pool contexts. Split the view hierarchy callbacks into their own sections, trim the scopes page and align the fingerprint sample comments. --- .../unity/data-management/data-collected.mdx | 46 ++++++++----------- .../unity/enriching-events/context/index.mdx | 2 +- .../unity/enriching-events/scopes/index.mdx | 5 -- .../enriching-events/view-hierarchy/index.mdx | 6 +-- .../set-fingerprint/basic/unity.mdx | 2 +- .../database-connection/unity.mdx | 2 +- .../set-fingerprint/rpc/unity.mdx | 2 +- 7 files changed, 27 insertions(+), 38 deletions(-) diff --git a/docs/platforms/unity/data-management/data-collected.mdx b/docs/platforms/unity/data-management/data-collected.mdx index 454b631417723..6f7b1854776ae 100644 --- a/docs/platforms/unity/data-management/data-collected.mdx +++ b/docs/platforms/unity/data-management/data-collected.mdx @@ -8,54 +8,44 @@ Sentry takes data privacy very seriously and has default settings in place that The data the Sentry Unity SDK collects depends on the options and integrations you enable. Here's a list of data categories it collects: -## HTTP Requests and Database Queries - -The Unity SDK doesn't instrument HTTP requests or databases, so it doesn't send request URLs, headers, cookies, or SQL queries. - ## Information About the User -The SDK always sends an anonymous installation ID as `user.id`. On iOS, Android, and Nintendo Switch, it's the native SDK's installation ID, so C# events and native crashes share the same user. +The SDK always sends an anonymous installation ID as `user.id`. It's a random ID that the SDK stores in a file on the device. On platforms where the SDK can't write files, such as UWP and visionOS, it uses the MAC address of the network adapter or a hash of the machine name instead. On iOS, Android, Nintendo Switch, and macOS with the Cocoa backend, it's the native SDK's installation ID, so C# events and native crashes share the same user. -If `SendDefaultPii` is set to `true`, the SDK also sends: - -- The user's IP address. See [Users' IP Address](#users-ip-address). -- The device unique identifier. See [Device Unique Identifier](#device-unique-identifier). -- The device name. See [Device Name](#device-name). -- The operating system's user name as `user.username`, if **Auto Set UserName** (`IsEnvironmentUser`) is also enabled. Learn more in [Options](/platforms/unity/configuration/options/#IsEnvironmentUser). +With Unity as a Library, the game's events carry the user that the host app sets. To send your own user information, [identify the user](../../enriching-events/identify-user/). -## Users' IP Address - -By default, the Sentry SDK doesn't send the user's IP address. - -If `SendDefaultPii` is set to `true`, the SDK sets the user's IP address to `{{auto}}`, and Sentry fills in the IP address the event came from. +## Data Sent With SendDefaultPii -You can [prevent Sentry from storing IP Addresses](../../enriching-events/identify-user/#ip_address) either by configuring this in the ["Security & Privacy"](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/security-and-privacy/) settings of your Sentry project or using [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). - -## Device Unique Identifier +If `SendDefaultPii` is set to `true`, the SDK also sends: -The Sentry SDK does not set the `Device Unique Identifier` by default. +- The user's IP address. The SDK sets it to `{{auto}}`, and Sentry fills in the IP address the event came from. +- The device unique identifier (`SystemInfo.deviceUniqueIdentifier`). +- The device's name as `device.name`. On desktop, this is the computer name. +- The operating system's user name as `user.username`, if **Auto Set UserName** (`IsEnvironmentUser`) is also enabled. Learn more in [Options](/platforms/unity/configuration/options/#IsEnvironmentUser). -If `SendDefaultPii` is set to `true` then the SDK will capture `SystemInfo.deviceUniqueIdentifier` automatically and send this with any event. +Error events don't include a server name. -## Device Name +You can [prevent Sentry from storing IP Addresses](../../enriching-events/identify-user/#ip_address) either by configuring this in the ["Security & Privacy"](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/security-and-privacy/) settings of your Sentry project or using [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). -By default, the Sentry SDK doesn't send the device name. +## Failed HTTP Requests -If `SendDefaultPii` is set to `true`, the SDK sends the device's name as `device.name`. On desktop, this is the computer name. +On iOS and macOS with the Cocoa backend, the Cocoa SDK captures failed `NSURLSession` requests as native events, with the URL, query string, method, and sanitized headers. These events don't run the C# callbacks. To turn this off, set [`CaptureFailedRequests`](/platforms/unity/configuration/options/#CaptureFailedRequests) to `false`. -The SDK never sends `ServerName`. +In C#, the SDK only records HTTP requests sent through `SentryHttpMessageHandler`. For these, it adds `http` breadcrumbs with the URL, and captures failed requests as events with the URL and query string. If `SendDefaultPii` is set to `true`, these events also include the full URL, the headers, and the cookies. ## General Device Information -The SDK collects information about the app, the operating system, the device, the GPU, and Unity, and sends it with every event. It sets these contexts when the SDK starts: +The SDK collects information about the app, the operating system, the device, the GPU, the runtime, and Unity, and sends it with every event: - `app`: the product name, the start time, and whether it's a debug or release build. - `os`: the operating system description. On Xbox and PlayStation, it's the name of the console. - `device`: the processor count, CPU, time zone, vibration support, device type, model, and system memory. In the Unity Editor, the device is marked as a simulator. - `gpu`: the GPU's ID, name, vendor name and ID, memory, graphics API and version, maximum texture size, shader level, multithreaded rendering, and support for non-power-of-two textures, instancing, ray tracing, and compute and geometry shaders. - `unity`: the Editor version, install mode, target frame rate, copy texture support, and rendering threading mode. +- `runtime`: the .NET runtime the game runs on. +- The current culture and UI culture, and the thread pool's thread counts. For events captured on the main thread, the SDK also adds: @@ -70,6 +60,10 @@ Every event also records whether it was captured on the main thread (`unity.is_m The SDK records Unity log messages, scene changes, and app lifecycle events as breadcrumbs, and sends them with events. Log messages can contain PII, depending on what your game logs. Learn more in [Breadcrumbs](../../enriching-events/breadcrumbs/). +## Logs + +Unity log messages that the SDK forwards to Sentry Logs can contain PII, depending on what your game logs. Each log carries the user from the scope as attributes. If `SendDefaultPii` is set to `true`, each log also carries the machine name as `server.address`. Learn more in [Logs](/platforms/unity/logs/). + ## Screenshots and View Hierarchy Screenshots and the view hierarchy are opt-in. Both can contain PII, such as names shown on screen or in the names of GameObjects. Learn more in [Screenshots](../../enriching-events/screenshots/) and [View Hierarchy](../../enriching-events/view-hierarchy/). diff --git a/docs/platforms/unity/enriching-events/context/index.mdx b/docs/platforms/unity/enriching-events/context/index.mdx index 4202c3d4270d9..fbd718923e062 100644 --- a/docs/platforms/unity/enriching-events/context/index.mdx +++ b/docs/platforms/unity/enriching-events/context/index.mdx @@ -31,7 +31,7 @@ Custom contexts are only added to C# events. Native crashes don't include them. There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. -The SDK sets five contexts itself: `app`, `os`, `device`, `gpu`, and `unity`. Don't use these names for your own contexts. For example, setting your own `device` context replaces the one the SDK collects. See the [list of data in these contexts](../../data-management/data-collected/#general-device-information). +The SDK sets its own contexts, such as `app`, `os`, `device`, `gpu`, `runtime`, and `unity`. Don't use these names for your own contexts. Setting your own context under one of them breaks the SDK's enrichment of every event. See the [list of data in these contexts](../../data-management/data-collected/#general-device-information). Learn more about conventions for common contexts in the [contexts interface developer documentation](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/contexts/). diff --git a/docs/platforms/unity/enriching-events/scopes/index.mdx b/docs/platforms/unity/enriching-events/scopes/index.mdx index f7c930371a534..5cdcab5fd46c3 100644 --- a/docs/platforms/unity/enriching-events/scopes/index.mdx +++ b/docs/platforms/unity/enriching-events/scopes/index.mdx @@ -23,13 +23,8 @@ You can also apply this configuration when unsetting a user at logout: -To learn what useful information can be associated with scopes see -[the context documentation](../context/). - ## Attaching Data to a Single Event -To attach data to one event only, use the scope callback of the capture methods. - ### Using Scope Callback Parameter In the following example we use the scope callback parameter that is available for all `capture` methods to attach a `level` and a `tag` to only one specific error: diff --git a/docs/platforms/unity/enriching-events/view-hierarchy/index.mdx b/docs/platforms/unity/enriching-events/view-hierarchy/index.mdx index aeedf2f0c404d..65e020b3d24b4 100644 --- a/docs/platforms/unity/enriching-events/view-hierarchy/index.mdx +++ b/docs/platforms/unity/enriching-events/view-hierarchy/index.mdx @@ -23,7 +23,7 @@ Or, like so, if you're [configuring things programmatically](/platforms/unity/co options.AttachViewHierarchy = true; ``` -### Customize View Hierarchy Capturing +## Customize View Hierarchy Capturing Because capturing view hierarchy can be a resource-intensive operation as the SDK traverses the scene at the time of an error, there are several controls available to you. @@ -53,8 +53,6 @@ options.MaxViewHierarchyRootObjects = 100; options.MaxViewHierarchyObjectChildCount = 20; ``` -## Modifying or Discarding the View Hierarchy - To decide whether an event gets a view hierarchy, use . Return `false` to skip it: ```csharp @@ -65,6 +63,8 @@ options.SetBeforeCaptureViewHierarchy(sentryEvent => }); ``` +## Modifying or Discarding the View Hierarchy + To edit the view hierarchy before it's sent, or to discard it, use . Return `null` to discard it: ```csharp diff --git a/platform-includes/set-fingerprint/basic/unity.mdx b/platform-includes/set-fingerprint/basic/unity.mdx index dbf633a92bc8f..90231258145cb 100644 --- a/platform-includes/set-fingerprint/basic/unity.mdx +++ b/platform-includes/set-fingerprint/basic/unity.mdx @@ -1,5 +1,5 @@ ```csharp -// Add this to your SentryOptionsConfiguration.Configure method +// Add this to the SDK initialization callback options.SetBeforeSend(@event => { // SaveFileCorruptedException is an exception defined by your game diff --git a/platform-includes/set-fingerprint/database-connection/unity.mdx b/platform-includes/set-fingerprint/database-connection/unity.mdx index 2ce86ca3a70d2..efe513da58045 100644 --- a/platform-includes/set-fingerprint/database-connection/unity.mdx +++ b/platform-includes/set-fingerprint/database-connection/unity.mdx @@ -1,5 +1,5 @@ ```csharp -// Add this to your SentryOptionsConfiguration.Configure method +// Add this to the SDK initialization callback options.SetBeforeSend(@event => { // BackendConnectionException is an exception defined by your game diff --git a/platform-includes/set-fingerprint/rpc/unity.mdx b/platform-includes/set-fingerprint/rpc/unity.mdx index c99b484c884ed..628d077c2d0b7 100644 --- a/platform-includes/set-fingerprint/rpc/unity.mdx +++ b/platform-includes/set-fingerprint/rpc/unity.mdx @@ -11,7 +11,7 @@ public class MyRpcException : Exception public HttpStatusCode Code { get; set; } } -// Add this to your SentryOptionsConfiguration.Configure method +// Add this to the SDK initialization callback options.SetBeforeSend(@event => { if (@event.Exception is MyRpcException ex) From a268e3bbf5861e7e7f2341abebb224c6a0fd7eff Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 15:49:09 +0100 Subject: [PATCH 3/5] docs(unity): Don't call the installation ID anonymous --- docs/platforms/unity/data-management/data-collected.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/unity/data-management/data-collected.mdx b/docs/platforms/unity/data-management/data-collected.mdx index 6f7b1854776ae..c05f887fe7bd0 100644 --- a/docs/platforms/unity/data-management/data-collected.mdx +++ b/docs/platforms/unity/data-management/data-collected.mdx @@ -10,7 +10,7 @@ The data the Sentry Unity SDK collects depends on the options and integrations y ## Information About the User -The SDK always sends an anonymous installation ID as `user.id`. It's a random ID that the SDK stores in a file on the device. On platforms where the SDK can't write files, such as UWP and visionOS, it uses the MAC address of the network adapter or a hash of the machine name instead. On iOS, Android, Nintendo Switch, and macOS with the Cocoa backend, it's the native SDK's installation ID, so C# events and native crashes share the same user. +The SDK always sends an installation ID as `user.id`. By default, it's a random ID that the SDK stores in a file on the device. On platforms where the SDK can't write files, such as UWP and visionOS, it uses the MAC address of the network adapter or a hash of the machine name instead. On iOS, Android, Nintendo Switch, and macOS with the Cocoa backend, it's the native SDK's installation ID, so C# events and native crashes share the same user. With Unity as a Library, the game's events carry the user that the host app sets. From 1fa2a3fc335a6a261f02c32d4ab29e068bb81b10 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 15:49:34 +0100 Subject: [PATCH 4/5] docs(unity): Say which reused context names break enrichment --- docs/platforms/unity/enriching-events/context/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/unity/enriching-events/context/index.mdx b/docs/platforms/unity/enriching-events/context/index.mdx index fbd718923e062..34146673896c4 100644 --- a/docs/platforms/unity/enriching-events/context/index.mdx +++ b/docs/platforms/unity/enriching-events/context/index.mdx @@ -31,7 +31,7 @@ Custom contexts are only added to C# events. Native crashes don't include them. There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. -The SDK sets its own contexts, such as `app`, `os`, `device`, `gpu`, `runtime`, and `unity`. Don't use these names for your own contexts. Setting your own context under one of them breaks the SDK's enrichment of every event. See the [list of data in these contexts](../../data-management/data-collected/#general-device-information). +The SDK sets its own contexts, such as `app`, `os`, `device`, `gpu`, `runtime`, and `unity`. Don't use these names for your own contexts. Setting your own context under one of them replaces the SDK's context. For `app`, `device`, and `unity`, it also stops the SDK from adding its main-thread data, the active scene, and default tags to events. See the [list of data in these contexts](../../data-management/data-collected/#general-device-information). Learn more about conventions for common contexts in the [contexts interface developer documentation](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/contexts/). From 2752adeb08206a31001bc82cfb739e9099e80440 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Fri, 13 Nov 2026 13:10:07 +0100 Subject: [PATCH 5/5] docs(unity): Update data privacy for sentry-unity 4.13.0 --- docs/platforms/unity/data-management/data-collected.mdx | 2 +- docs/platforms/unity/data-management/sensitive-data/index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/unity/data-management/data-collected.mdx b/docs/platforms/unity/data-management/data-collected.mdx index c05f887fe7bd0..6dec5530aa7a5 100644 --- a/docs/platforms/unity/data-management/data-collected.mdx +++ b/docs/platforms/unity/data-management/data-collected.mdx @@ -22,7 +22,7 @@ If `SendDefaultPii` is set to `true`, the SDK also sends: - The user's IP address. The SDK sets it to `{{auto}}`, and Sentry fills in the IP address the event came from. - The device unique identifier (`SystemInfo.deviceUniqueIdentifier`). -- The device's name as `device.name`. On desktop, this is the computer name. +- The device's name as `device.name`. On desktop, this is the computer name. Native crashes on Windows, Linux, macOS with the Native backend, and game consoles include it only with this option too. Native crashes on Android, iOS, and macOS with the Cocoa backend don't include a device name. - The operating system's user name as `user.username`, if **Auto Set UserName** (`IsEnvironmentUser`) is also enabled. Learn more in [Options](/platforms/unity/configuration/options/#IsEnvironmentUser). Error events don't include a server name. diff --git a/docs/platforms/unity/data-management/sensitive-data/index.mdx b/docs/platforms/unity/data-management/sensitive-data/index.mdx index 3644a81c2fe6a..e9574447d29a6 100644 --- a/docs/platforms/unity/data-management/sensitive-data/index.mdx +++ b/docs/platforms/unity/data-management/sensitive-data/index.mdx @@ -36,7 +36,7 @@ To remove sensitive data before it leaves the device, use these callbacks: -These callbacks run in C# only. Native crashes, from C and C++, Java and Kotlin, or Objective-C and Swift code, are captured by the native SDKs and don't run them. Breadcrumbs reach the native SDKs after `SetBeforeBreadcrumb` runs, so breadcrumbs you edit or drop there stay that way in native crashes. To remove other data from native crashes, use [server-side scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). +These callbacks run in C# only. Native crashes, from C and C++, Java and Kotlin, or Objective-C and Swift code, are captured by the native SDKs and don't run them. Breadcrumbs reach the native SDKs after `SetBeforeBreadcrumb` runs, so breadcrumbs you edit or drop there stay that way in native crashes. To remove other data from native crashes, use [server-side scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). On iOS, setting `SetBeforeCaptureScreenshot` or `SetBeforeSendScreenshot` turns off screenshots for native crashes. On Windows, native crashes get a screenshot whenever `AttachScreenshot` is on. Learn more in [Screenshots](/platforms/unity/enriching-events/screenshots/#native-errors).