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..f31a56bd5cec9 100644 --- a/docs/platforms/unity/game-consoles/index.mdx +++ b/docs/platforms/unity/game-consoles/index.mdx @@ -34,14 +34,26 @@ 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. + ## 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 + +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 45a591b25df30..0f93d10c645b9 100644 --- a/docs/platforms/unity/native-support/index.mdx +++ b/docs/platforms/unity/native-support/index.mdx @@ -5,13 +5,50 @@ 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 | 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 + +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 + +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. +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 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. @@ -33,7 +70,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 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 @@ -45,7 +82,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. @@ -57,13 +94,21 @@ When your game runs inside an iOS or Android app with Unity as a Library, the ap 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. + +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. 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 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 -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 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 +147,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`