From a4e7199a60e95fcf7e75cf12f1ceb7db57f47951 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 14:49:22 +0100 Subject: [PATCH 1/6] docs(unity): Fix native support and platform docs Add a supported platforms table and a scope sync section to the Native Support page, and describe the Android, iOS, Windows and macOS native options and backends. Native crashes on consoles are supported, so drop the "work in progress" note. Document the Xbox PersistentLocalStorage requirement and the Nintendo Switch limits on the Game Consoles page. Fix the minidump platform list, the iOS main.mm and SentryObjC names, and the WebGL line number note. --- .../store-minidumps-as-attachments/index.mdx | 5 +- .../enriching-events/attachments/index.mdx | 7 +- .../unity/enriching-events/context/index.mdx | 2 + docs/platforms/unity/game-consoles/index.mdx | 16 ++++ docs/platforms/unity/native-support/index.mdx | 75 +++++++++++++++++-- .../platforms/unity/troubleshooting/index.mdx | 6 +- .../troubleshooting/known-limitations.mdx | 2 +- 7 files changed, 100 insertions(+), 13 deletions(-) diff --git a/docs/platforms/unity/data-management/store-minidumps-as-attachments/index.mdx b/docs/platforms/unity/data-management/store-minidumps-as-attachments/index.mdx index 05a0db81eb930..04363fdd710a1 100644 --- a/docs/platforms/unity/data-management/store-minidumps-as-attachments/index.mdx +++ b/docs/platforms/unity/data-management/store-minidumps-as-attachments/index.mdx @@ -6,6 +6,9 @@ sidebar_order: 90 -☝ This feature is supported on Windows, Linux, and Android. + + ☝ This feature is supported on Windows, Linux, and macOS with the Native + backend. + diff --git a/docs/platforms/unity/enriching-events/attachments/index.mdx b/docs/platforms/unity/enriching-events/attachments/index.mdx index 005d7d0ac990d..4c015b0557b28 100644 --- a/docs/platforms/unity/enriching-events/attachments/index.mdx +++ b/docs/platforms/unity/enriching-events/attachments/index.mdx @@ -45,6 +45,8 @@ The type of content stored in this attachment. Any [MIME type](https://www.iana. Unity features a global scope to which you add an attachment that will be sent with every event. +The SDK also syncs these attachments to the native SDK, so native crashes include them, except on iOS and on macOS with the default Cocoa backend. Learn more in Scope Sync. + @@ -61,7 +63,10 @@ Learn more about how attachments impact your [quota](/pricing/quotas/). -☝ This feature is supported on Windows, Linux, and Android. + + ☝ This feature is supported on Windows, Linux, and macOS with the Native + backend. + diff --git a/docs/platforms/unity/enriching-events/context/index.mdx b/docs/platforms/unity/enriching-events/context/index.mdx index 69625e24f4f53..fa54f28d3fe42 100644 --- a/docs/platforms/unity/enriching-events/context/index.mdx +++ b/docs/platforms/unity/enriching-events/context/index.mdx @@ -27,6 +27,8 @@ The class must be serializable and only properties are included; fields are not. +Custom contexts are only added to C# events. Native crashes don't include them. Learn more in Scope Sync. + There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. 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/game-consoles/index.mdx b/docs/platforms/unity/game-consoles/index.mdx index be9474806d23a..ce8effbe97fa4 100644 --- a/docs/platforms/unity/game-consoles/index.mdx +++ b/docs/platforms/unity/game-consoles/index.mdx @@ -34,6 +34,22 @@ Each console has a different crash capture model: Sentry supports [PlayStation](/platforms/playstation/), [Xbox](/platforms/xbox/) and [Nintendo Switch](/platforms/nintendo-switch/) via the Unity SDK. Once you submit the middleware verification process, we'll reach out and send you an invite to our private GitHub repositories with console-specific code. This allows your configuration and custom data set via C# to show up in C# exceptions as well as crash dumps on these console platforms. +The automated debug symbol upload covers console builds, too. + +## Unity Requirements + +### Xbox + +The SDK stores its data in Xbox Persistent Local Storage. Configure `PersistentLocalStorage` in your game's `MicrosoftGame.config`. Without it, the SDK runs without offline caching, session persistence, or native crash reporting. + +### Nintendo Switch + +On Nintendo Switch and Nintendo Switch 2, the SDK: + +- Sets `DisableFileWrite`, because file access is limited, so there's no offline caching +- Turns off automatic session tracking, for the same reason +- Turns off IL2CPP line numbers, which aren't available on Switch + ## Nintendo Switch diff --git a/docs/platforms/unity/native-support/index.mdx b/docs/platforms/unity/native-support/index.mdx index 45a591b25df30..d31513a2109f6 100644 --- a/docs/platforms/unity/native-support/index.mdx +++ b/docs/platforms/unity/native-support/index.mdx @@ -5,8 +5,46 @@ sidebar_order: 100 sidebar_section: features --- -The Sentry SDK supports C# and Native crashes on Android, iOS, Windows, macOS and Linux. The support is set to `enabled` by default. -For Game Consoles, the SDK supports C# errors. While Sentry supports native crashes on consoles, support for that through the Unity SDK is a work in progress. Reach out via GitHub for the platform you're interested in: [PlayStation](https://github.com/getsentry/sentry-unity/issues/2050), [Switch](https://github.com/getsentry/sentry-unity/issues/2052) and [Xbox](https://github.com/getsentry/sentry-unity/issues/2051) +The Unity SDK captures C# errors on every platform it supports. On most platforms, it also includes a native SDK that captures native crashes, such as crashes in the Unity engine or in native plugins. Native support is on by default. + +## Supported Platforms + +| Platform | C# errors | Native crashes | Native SDK | Requirements | +| ---------------------------------- | --------- | -------------- | ------------------------------------------------------------------- | ----------------------- | +| Android | Yes | Yes | sentry-java with the NDK integration | IL2CPP | +| iOS | Yes | Yes | sentry-cocoa | | +| Windows (x64, x86) | Yes | Yes | sentry-native with Crashpad, or the experimental Native backend | | +| macOS | Yes | Yes | sentry-cocoa, or sentry-native with the experimental Native backend | IL2CPP for sentry-cocoa | +| Linux (x86_64, ARM64) | Yes | Yes | sentry-native with Breakpad, or the experimental Native backend | | +| Xbox, PlayStation, Nintendo Switch | Yes | Yes | See Game Consoles | | +| WebGL | Yes | No | | | +| visionOS, UWP | Yes | No | | | + +The SDK supports Unity 2021.3 and later. Dedicated server builds for Windows, macOS, and Linux get the same native support as players. On consoles, the SDK supports Xbox with the GDK, PlayStation 5, Nintendo Switch, and Nintendo Switch 2. The SDK doesn't support PlayStation 4, Xbox One without the GDK, tvOS, Embedded Linux, or Cloud Rendering. + +Some native SDKs need the IL2CPP scripting backend: + +- **Android**: With Mono, native support is off and the SDK captures C# errors only. +- **macOS**: The default Cocoa backend needs IL2CPP. The experimental Native backend works with both IL2CPP and Mono. + +iOS and WebGL always build with IL2CPP. On WebGL, setting exception support to `None` fails the build. + +## Scope Sync + +The SDK syncs the scope you set in C# to the native SDK, so native crashes include it. It syncs: + +- Breadcrumbs +- Tags +- Extras +- User +- Environment +- Trace +- Attachments + +Two things don't reach native crashes: + +- Custom contexts you set through `scope.Contexts`. The SDK only syncs the contexts it collects itself, such as device and app data. +- Attachments on iOS, and on macOS with the default Cocoa backend. ## Mobile @@ -33,7 +71,7 @@ At build time, the SDK modifies the generated Gradle project to include the Andr #### iOS -At built time, the SDK modifies the generated Xcode project to include the iOS SDK but will not modify the `main.m` file or write the options to file. The Unity SDK will then initialize the iOS SDK when it initializes itself. +At built time, the SDK modifies the generated Xcode project to include the iOS SDK but will not modify the `main.mm` file or write the options to file. The Unity SDK will then initialize the iOS SDK when it initializes itself. ### Build Time Initialization @@ -45,7 +83,7 @@ The SDK modifies the generated Gradle project to include the Android SDK. At bui #### iOS -The SDK modifies the generated Xcode project to include the iOS SDK. It adds the initialization code to the `main.m` and generates the options provided by the editor configuration window as `SentryOptions.m`. The SDK also copies the `SentryNativeBridge` that enables the C# layer to communicate with the iOS SDK. This means that there's no need to use the Unity [built-in crash reporting](https://docs.unity3d.com/ScriptReference/CrashReport.html) functionality. +The SDK modifies the generated Xcode project to include the iOS SDK. It adds the initialization code to the `main.mm` and generates the options provided by the editor configuration window as `SentryOptions.m`. The SDK also copies the `SentryNativeBridge` that enables the C# layer to communicate with the iOS SDK. This means that there's no need to use the Unity [built-in crash reporting](https://docs.unity3d.com/ScriptReference/CrashReport.html) functionality. The [iOS SDK](/platforms/apple/guides/ios/) supports capturing Objective-C exceptions which are disabled in the generated Xcode project by default. Consider enabling them in the "Build Settings" tab by setting `GCC_ENABLE_OBJC_EXCEPTIONS` to true. @@ -53,17 +91,37 @@ The [iOS SDK](/platforms/apple/guides/ios/) supports capturing Objective-C excep When your game runs inside an iOS or Android app with Unity as a Library, the app owns the native SDK. The Unity SDK doesn't bundle it and attaches to the one the app initialized. On Android, a game running in a separate process initializes it there. Learn more in Unity as a Library. +### Android Options + +Android native support needs IL2CPP. With Mono, the SDK captures C# errors only. + +- `NdkIntegrationEnabled` turns the NDK integration on or off. It's on by default. +- `NdkScopeSyncEnabled` syncs the scope to the NDK, so native crashes include it. It's on by default. +- `AndroidTombstoneEnabled` reports native crashes that Android records as tombstones, through the `ApplicationExitInfo` API. `AndroidReportHistoricalTombstones` also reports tombstones from earlier runs. Both are off by default. + +### iOS Options + +`IosWatchdogTerminationIntegrationEnabled` reports watchdog terminations, when the operating system kills the app, for example because it uses too much memory. It's off by default. + ## Desktop The native support is configured and enabled as early as possible by the C# layer, right after the Unity engine starts. This is slightly different from on mobile where we inject native initialization code that runs before the Unity engine runs. +Native support on Windows, Linux, and macOS with the Native backend writes files to disk. If you set `DisableFileWrite`, the SDK turns native support off on these platforms. + +Crashpad on Windows and the Native backend on every desktop platform use an out-of-process crash handler. The SDK looks for the handler executable next to the player. If you ship it somewhere else, set `NativeHandlerPath` to its path. + ### Windows -On Windows, the Unity SDK includes the [Native SDK](/platforms/native/) with the crashpad backend. Windows native crashes are automatically captured through minidumps. To upload these to Sentry, the SDK copies the `crashpad_handler.exe` to the build output directory at the end of the build process. This executable must be included when shipping your game. +On Windows, the Unity SDK includes the [Native SDK](/platforms/native/) with the Crashpad backend, for both 64-bit (x64) and 32-bit (x86) players. Windows native crashes are captured through minidumps. At the end of the build, the SDK copies `crashpad_handler.exe`, `crashpad_wer.dll`, and `sentry-native.dll` next to the player. Include all three files when you ship your game. + +With the experimental Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe` and `sentry-native.dll` next to the player instead. ### macOS -The Native Support on macOS relies on the [macOS SDK](/platforms/apple/guides/macos/). Stackwalking happens in process. +By default, native support on macOS relies on the [macOS SDK](/platforms/apple/guides/macos/). Stackwalking happens in process. This Cocoa backend needs IL2CPP. With Mono, the SDK captures C# errors only. + +With the experimental Native backend, which you can select with `options.Experimental.MacosBackend = MacosBackend.Native`, the SDK uses the [Native SDK](/platforms/native/) instead. It uploads crashes right away through the out-of-process `sentry-crash` handler, which the build copies next to the player, and it works with both IL2CPP and Mono. ### Linux @@ -102,6 +160,9 @@ sentry-cli --auth-token ___ORG_AUTH_TOKEN___ debug-files upload --org ___ORG_SLU -☝ This feature is supported on Windows, Linux, and Android. + + ☝ This feature is supported on Windows, Linux, and macOS with the Native + backend. + diff --git a/docs/platforms/unity/troubleshooting/index.mdx b/docs/platforms/unity/troubleshooting/index.mdx index 0ac4d537926a2..c68177da2f4d0 100644 --- a/docs/platforms/unity/troubleshooting/index.mdx +++ b/docs/platforms/unity/troubleshooting/index.mdx @@ -64,17 +64,17 @@ public class GameInitializer : MonoBehaviour Since this way the options are embedded in code, the reliance on the `/Resources` being available at the time of initialization falls away. Unlike regular [manual initialization](/platforms/unity/configuration/options/programmatic-configuration/#manual-initialization), keep **Enable Sentry** checked in the editor window: the SDK can't load its options from the OBB, so your `SentrySdk.Init` call is the only one, and the build still sets up native support. -### Library not loaded: @rpath/Sentry.framework/Sentry +### Library not loaded: @rpath/SentryObjC.framework/SentryObjC If you encounter the following error: ``` -2021-10-29 15:21:40.011452-0400 MyApp[2180:186329] Error loading /var/containers/Bundle/Application/88CC4619-7C5D-4BB1-9F4B-5AAD7EC4BF9C/MyApp.app/Frameworks/UnityFramework.framework/UnityFramework: dlopen(/var/containers/Bundle/Application/88CC4619-7C5D-4BB1-9F4B-5AAD7EC4BF9C/MyApp.app/Frameworks/UnityFramework.framework/UnityFramework, 265): Library not loaded: @rpath/Sentry.framework/Sentry +2021-10-29 15:21:40.011452-0400 MyApp[2180:186329] Error loading /var/containers/Bundle/Application/88CC4619-7C5D-4BB1-9F4B-5AAD7EC4BF9C/MyApp.app/Frameworks/UnityFramework.framework/UnityFramework: dlopen(/var/containers/Bundle/Application/88CC4619-7C5D-4BB1-9F4B-5AAD7EC4BF9C/MyApp.app/Frameworks/UnityFramework.framework/UnityFramework, 265): Library not loaded: @rpath/SentryObjC.framework/SentryObjC Referenced from: /private/var/containers/Bundle/Application/88CC4619-7C5D-4BB1-9F4B-5AAD7EC4BF9C/MyApp.app/Frameworks/UnityFramework.framework/UnityFramework Reason: image not found ``` -This can happen if you've copied some of the SDK files directly to the Assets folder and the `Sentry.Unity.Editor.iOS.dll` which runs when you build an iOS player wasn't able to copy the `Sentry.framework` to the final app. Enabling debug mode in the Sentry editor window would display more information in the Unity console. +This can happen if you've copied some of the SDK files directly to the Assets folder and the `Sentry.Unity.Editor.iOS.dll` which runs when you build an iOS player wasn't able to copy the `SentryObjC.xcframework` to the final app. Enabling debug mode in the Sentry editor window would display more information in the Unity console. You can resolve this issue by installing the SDK with UPM. diff --git a/docs/platforms/unity/troubleshooting/known-limitations.mdx b/docs/platforms/unity/troubleshooting/known-limitations.mdx index d7670df9a3110..9ca48672c0c36 100644 --- a/docs/platforms/unity/troubleshooting/known-limitations.mdx +++ b/docs/platforms/unity/troubleshooting/known-limitations.mdx @@ -125,7 +125,7 @@ When targeting WebGL, you have the option of setting the `PlayerSettings.WebGL.e - Setting it to `WebGLExceptionSupport.None` is not supported by the SDK. - For the SDK to be able provide stack traces, the support needs to be set to `WebGLExceptionSupport.FullWithStacktrace`. -- The SDK is currently not able to provide line numbers due to the IL2CPP backend not being available. +- The SDK turns off IL2CPP line numbers on WebGL, because Unity's WebGL build doesn't provide the API it needs. - **Native crash detection is not available on WebGL.** The SDK cannot determine if the browser or tab crashed, which affects session tracking: - Sessions with captured exceptions are marked as `Unhandled` - Sessions where the tab/browser closes without a clean shutdown are marked as `Abnormal` From a3bdbe084245c03bc2f3b9bcdb9a98afbde01d60 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 14:55:20 +0100 Subject: [PATCH 2/6] docs(unity): Address review of native support docs --- docs/platforms/unity/game-consoles/index.mdx | 14 ++--- docs/platforms/unity/native-support/index.mdx | 51 +++++++------------ 2 files changed, 23 insertions(+), 42 deletions(-) diff --git a/docs/platforms/unity/game-consoles/index.mdx b/docs/platforms/unity/game-consoles/index.mdx index ce8effbe97fa4..f31a56bd5cec9 100644 --- a/docs/platforms/unity/game-consoles/index.mdx +++ b/docs/platforms/unity/game-consoles/index.mdx @@ -36,13 +36,9 @@ This allows your configuration and custom data set via C# to show up in C# excep The automated debug symbol upload covers console builds, too. -## Unity Requirements - -### Xbox - -The SDK stores its data in Xbox Persistent Local Storage. Configure `PersistentLocalStorage` in your game's `MicrosoftGame.config`. Without it, the SDK runs without offline caching, session persistence, or native crash reporting. +## Nintendo Switch -### Nintendo Switch + On Nintendo Switch and Nintendo Switch 2, the SDK: @@ -50,14 +46,14 @@ On Nintendo Switch and Nintendo Switch 2, the SDK: - Turns off automatic session tracking, for the same reason - Turns off IL2CPP line numbers, which aren't available on Switch -## Nintendo Switch - - +Set `TemporaryStorageSize` in your game's `.nmeta` file. The SDK needs temporary storage to start the native SDK. Without it, the SDK skips native initialization, and native crashes don't include the scope you set in C#. ## Xbox +The SDK stores its data in Xbox Persistent Local Storage. Configure `PersistentLocalStorage` in your game's `MicrosoftGame.config`. Without it, the SDK runs without offline caching, session persistence, or native crash reporting. + ## PlayStation diff --git a/docs/platforms/unity/native-support/index.mdx b/docs/platforms/unity/native-support/index.mdx index d31513a2109f6..1d141fbef34cb 100644 --- a/docs/platforms/unity/native-support/index.mdx +++ b/docs/platforms/unity/native-support/index.mdx @@ -9,26 +9,19 @@ The Unity SDK captures C# errors on every platform it supports. On most platform ## Supported Platforms -| Platform | C# errors | Native crashes | Native SDK | Requirements | -| ---------------------------------- | --------- | -------------- | ------------------------------------------------------------------- | ----------------------- | -| Android | Yes | Yes | sentry-java with the NDK integration | IL2CPP | -| iOS | Yes | Yes | sentry-cocoa | | -| Windows (x64, x86) | Yes | Yes | sentry-native with Crashpad, or the experimental Native backend | | -| macOS | Yes | Yes | sentry-cocoa, or sentry-native with the experimental Native backend | IL2CPP for sentry-cocoa | -| Linux (x86_64, ARM64) | Yes | Yes | sentry-native with Breakpad, or the experimental Native backend | | -| Xbox, PlayStation, Nintendo Switch | Yes | Yes | See Game Consoles | | -| WebGL | Yes | No | | | -| visionOS, UWP | Yes | No | | | +| Platform | Native crashes | Native SDK | Requirements | +| ---------------------------------- | -------------- | ------------------------------------------------------------------- | --------------------------------------------------- | +| Android | Yes | sentry-java with the NDK integration | IL2CPP | +| iOS | Yes | sentry-cocoa | | +| Windows (x64, x86) | Yes | sentry-native with Crashpad, or the experimental Native backend | | +| macOS | Yes | sentry-cocoa, or sentry-native with the experimental Native backend | IL2CPP for sentry-cocoa | +| Linux (x86_64, ARM64) | Yes | sentry-native with Breakpad, or the experimental Native backend | | +| Xbox, PlayStation, Nintendo Switch | Yes | See Game Consoles | | +| WebGL | No | | | +| visionOS, UWP | No | | Best effort: no offline caching or session tracking | The SDK supports Unity 2021.3 and later. Dedicated server builds for Windows, macOS, and Linux get the same native support as players. On consoles, the SDK supports Xbox with the GDK, PlayStation 5, Nintendo Switch, and Nintendo Switch 2. The SDK doesn't support PlayStation 4, Xbox One without the GDK, tvOS, Embedded Linux, or Cloud Rendering. -Some native SDKs need the IL2CPP scripting backend: - -- **Android**: With Mono, native support is off and the SDK captures C# errors only. -- **macOS**: The default Cocoa backend needs IL2CPP. The experimental Native backend works with both IL2CPP and Mono. - -iOS and WebGL always build with IL2CPP. On WebGL, setting exception support to `None` fails the build. - ## Scope Sync The SDK syncs the scope you set in C# to the native SDK, so native crashes include it. It syncs: @@ -41,15 +34,19 @@ The SDK syncs the scope you set in C# to the native SDK, so native crashes inclu - Trace - Attachments -Two things don't reach native crashes: +Some scope data doesn't reach native crashes: - Custom contexts you set through `scope.Contexts`. The SDK only syncs the contexts it collects itself, such as device and app data. - Attachments on iOS, and on macOS with the default Cocoa backend. +- With Unity as a Library, the app's own SDK owns part of the scope. On iOS, that's the user, environment, and trace. On Android, it's the trace, and the user when the game runs in the app's process. +- On Android, setting `NdkScopeSyncEnabled` to `false` turns off scope sync for NDK crashes. ## Mobile The native crash support for Android and iOS is provided by adding platform-specific SDKs to the generated Xcode and Gradle projects at build time. +On Android, `NdkIntegrationEnabled`, `NdkScopeSyncEnabled`, `AndroidTombstoneEnabled`, and `AndroidReportHistoricalTombstones` control the NDK integration and tombstone reporting. On iOS, `IosWatchdogTerminationIntegrationEnabled` controls watchdog termination reporting. Learn more in Options. + ### Initialization of the Native SDKs The [iOS SDK](/platforms/apple/guides/ios/) and [Android SDK](/platforms/android/) are capable of self-initializing before the Unity engine itself is started. This allows us to capture bugs/crashes happening within the engine itself. @@ -71,7 +68,7 @@ At build time, the SDK modifies the generated Gradle project to include the Andr #### iOS -At built time, the SDK modifies the generated Xcode project to include the iOS SDK but will not modify the `main.mm` file or write the options to file. The Unity SDK will then initialize the iOS SDK when it initializes itself. +At build time, the SDK modifies the generated Xcode project to include the iOS SDK but will not modify the `main.mm` file or write the options to file. The Unity SDK will then initialize the iOS SDK when it initializes itself. ### Build Time Initialization @@ -91,31 +88,19 @@ The [iOS SDK](/platforms/apple/guides/ios/) supports capturing Objective-C excep When your game runs inside an iOS or Android app with Unity as a Library, the app owns the native SDK. The Unity SDK doesn't bundle it and attaches to the one the app initialized. On Android, a game running in a separate process initializes it there. Learn more in Unity as a Library. -### Android Options - -Android native support needs IL2CPP. With Mono, the SDK captures C# errors only. - -- `NdkIntegrationEnabled` turns the NDK integration on or off. It's on by default. -- `NdkScopeSyncEnabled` syncs the scope to the NDK, so native crashes include it. It's on by default. -- `AndroidTombstoneEnabled` reports native crashes that Android records as tombstones, through the `ApplicationExitInfo` API. `AndroidReportHistoricalTombstones` also reports tombstones from earlier runs. Both are off by default. - -### iOS Options - -`IosWatchdogTerminationIntegrationEnabled` reports watchdog terminations, when the operating system kills the app, for example because it uses too much memory. It's off by default. - ## Desktop The native support is configured and enabled as early as possible by the C# layer, right after the Unity engine starts. This is slightly different from on mobile where we inject native initialization code that runs before the Unity engine runs. Native support on Windows, Linux, and macOS with the Native backend writes files to disk. If you set `DisableFileWrite`, the SDK turns native support off on these platforms. -Crashpad on Windows and the Native backend on every desktop platform use an out-of-process crash handler. The SDK looks for the handler executable next to the player. If you ship it somewhere else, set `NativeHandlerPath` to its path. +On Windows, Linux, and macOS, `NativeHandlerPath` sets where the SDK looks for the crash handler executable. Learn more in Options. ### Windows On Windows, the Unity SDK includes the [Native SDK](/platforms/native/) with the Crashpad backend, for both 64-bit (x64) and 32-bit (x86) players. Windows native crashes are captured through minidumps. At the end of the build, the SDK copies `crashpad_handler.exe`, `crashpad_wer.dll`, and `sentry-native.dll` next to the player. Include all three files when you ship your game. -With the experimental Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe` and `sentry-native.dll` next to the player instead. +With the experimental Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe`, `sentry-wer.dll`, and `sentry-native.dll` next to the player instead. Include all three files when you ship your game. ### macOS From 1dee80915c2cb8a12826361d130235e6a225a391 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 14:55:47 +0100 Subject: [PATCH 3/6] docs(unity): State the IL2CPP requirement for Android native support --- docs/platforms/unity/native-support/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/platforms/unity/native-support/index.mdx b/docs/platforms/unity/native-support/index.mdx index 1d141fbef34cb..608c438739c5d 100644 --- a/docs/platforms/unity/native-support/index.mdx +++ b/docs/platforms/unity/native-support/index.mdx @@ -45,6 +45,8 @@ Some scope data doesn't reach native crashes: The native crash support for Android and iOS is provided by adding platform-specific SDKs to the generated Xcode and Gradle projects at build time. +Android native support requires the IL2CPP scripting backend. With Mono, the SDK captures C# errors only. + On Android, `NdkIntegrationEnabled`, `NdkScopeSyncEnabled`, `AndroidTombstoneEnabled`, and `AndroidReportHistoricalTombstones` control the NDK integration and tombstone reporting. On iOS, `IosWatchdogTerminationIntegrationEnabled` controls watchdog termination reporting. Learn more in Options. ### Initialization of the Native SDKs From e9989e5c76fe2c07a4ccd9f179b93c2a6f0d19b2 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 14:56:28 +0100 Subject: [PATCH 4/6] docs(unity): Move the visionOS and UWP note out of the table --- docs/platforms/unity/native-support/index.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/platforms/unity/native-support/index.mdx b/docs/platforms/unity/native-support/index.mdx index 608c438739c5d..5de5ade283413 100644 --- a/docs/platforms/unity/native-support/index.mdx +++ b/docs/platforms/unity/native-support/index.mdx @@ -9,18 +9,18 @@ The Unity SDK captures C# errors on every platform it supports. On most platform ## Supported Platforms -| Platform | Native crashes | Native SDK | Requirements | -| ---------------------------------- | -------------- | ------------------------------------------------------------------- | --------------------------------------------------- | -| Android | Yes | sentry-java with the NDK integration | IL2CPP | -| iOS | Yes | sentry-cocoa | | -| Windows (x64, x86) | Yes | sentry-native with Crashpad, or the experimental Native backend | | -| macOS | Yes | sentry-cocoa, or sentry-native with the experimental Native backend | IL2CPP for sentry-cocoa | -| Linux (x86_64, ARM64) | Yes | sentry-native with Breakpad, or the experimental Native backend | | -| Xbox, PlayStation, Nintendo Switch | Yes | See Game Consoles | | -| WebGL | No | | | -| visionOS, UWP | No | | Best effort: no offline caching or session tracking | - -The SDK supports Unity 2021.3 and later. Dedicated server builds for Windows, macOS, and Linux get the same native support as players. On consoles, the SDK supports Xbox with the GDK, PlayStation 5, Nintendo Switch, and Nintendo Switch 2. The SDK doesn't support PlayStation 4, Xbox One without the GDK, tvOS, Embedded Linux, or Cloud Rendering. +| Platform | Native crashes | Native SDK | Requirements | +| ---------------------------------- | -------------- | ------------------------------------------------------------------- | ----------------------- | +| Android | Yes | sentry-java with the NDK integration | IL2CPP | +| iOS | Yes | sentry-cocoa | | +| Windows (x64, x86) | Yes | sentry-native with Crashpad, or the experimental Native backend | | +| macOS | Yes | sentry-cocoa, or sentry-native with the experimental Native backend | IL2CPP for sentry-cocoa | +| Linux (x86_64, ARM64) | Yes | sentry-native with Breakpad, or the experimental Native backend | | +| Xbox, PlayStation, Nintendo Switch | Yes | See Game Consoles | | +| WebGL | No | | | +| visionOS, UWP | No | | | + +On visionOS and UWP, the SDK runs on a best-effort basis, without offline caching or session tracking. The SDK supports Unity 2021.3 and later. Dedicated server builds for Windows, macOS, and Linux get the same native support as players. On consoles, the SDK supports Xbox with the GDK, PlayStation 5, Nintendo Switch, and Nintendo Switch 2. The SDK doesn't support PlayStation 4, Xbox One without the GDK, tvOS, Embedded Linux, or Cloud Rendering. ## Scope Sync From 4628b2c3b359a5c38bbf2f33718cca8ad897ad6e Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 3 Nov 2026 14:56:51 +0100 Subject: [PATCH 5/6] docs(unity): Scope NativeHandlerPath to out-of-process handlers --- docs/platforms/unity/native-support/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/unity/native-support/index.mdx b/docs/platforms/unity/native-support/index.mdx index 5de5ade283413..405ec84aec312 100644 --- a/docs/platforms/unity/native-support/index.mdx +++ b/docs/platforms/unity/native-support/index.mdx @@ -96,7 +96,7 @@ The native support is configured and enabled as early as possible by the C# laye Native support on Windows, Linux, and macOS with the Native backend writes files to disk. If you set `DisableFileWrite`, the SDK turns native support off on these platforms. -On Windows, Linux, and macOS, `NativeHandlerPath` sets where the SDK looks for the crash handler executable. Learn more in Options. +With an out-of-process crash handler (Crashpad on Windows, or the experimental Native backend), `NativeHandlerPath` sets where the SDK looks for the handler executable. By default, it's next to the player executable. Learn more in Options. ### Windows From 17d7c94acb9023d82a23626765b842f15bc41fed Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Fri, 13 Nov 2026 17:41:19 +0100 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> --- docs/platforms/unity/native-support/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/unity/native-support/index.mdx b/docs/platforms/unity/native-support/index.mdx index 405ec84aec312..0f93d10c645b9 100644 --- a/docs/platforms/unity/native-support/index.mdx +++ b/docs/platforms/unity/native-support/index.mdx @@ -96,19 +96,19 @@ The native support is configured and enabled as early as possible by the C# laye Native support on Windows, Linux, and macOS with the Native backend writes files to disk. If you set `DisableFileWrite`, the SDK turns native support off on these platforms. -With an out-of-process crash handler (Crashpad on Windows, or the experimental Native backend), `NativeHandlerPath` sets where the SDK looks for the handler executable. By default, it's next to the player executable. Learn more in Options. +With an out-of-process crash handler (Crashpad on Windows, or the Native backend), `NativeHandlerPath` sets where the SDK looks for the handler executable. By default, it's next to the player executable. Learn more in Options. ### Windows On Windows, the Unity SDK includes the [Native SDK](/platforms/native/) with the Crashpad backend, for both 64-bit (x64) and 32-bit (x86) players. Windows native crashes are captured through minidumps. At the end of the build, the SDK copies `crashpad_handler.exe`, `crashpad_wer.dll`, and `sentry-native.dll` next to the player. Include all three files when you ship your game. -With the experimental Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe`, `sentry-wer.dll`, and `sentry-native.dll` next to the player instead. Include all three files when you ship your game. +With the Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe`, `sentry-wer.dll`, and `sentry-native.dll` next to the player instead. Include all three files when you ship your game. ### macOS By default, native support on macOS relies on the [macOS SDK](/platforms/apple/guides/macos/). Stackwalking happens in process. This Cocoa backend needs IL2CPP. With Mono, the SDK captures C# errors only. -With the experimental Native backend, which you can select with `options.Experimental.MacosBackend = MacosBackend.Native`, the SDK uses the [Native SDK](/platforms/native/) instead. It uploads crashes right away through the out-of-process `sentry-crash` handler, which the build copies next to the player, and it works with both IL2CPP and Mono. +With the Native backend, which you can select with `options.Experimental.MacosBackend = MacosBackend.Native`, the SDK uses the [Native SDK](/platforms/native/) instead. It uploads crashes right away through the out-of-process `sentry-crash` handler, which the build copies next to the player, and it works with both IL2CPP and Mono. ### Linux