Native Support
Learn how the Unity SDK handles native support.
Currently, the Unity SDK offers native support for Android, iOS, Windows, macOS and Linux. The support is set to enabled by default, and you can opt out for each platform individually in the configuration window.
The Unity SDK captures C# exceptions and does not break any builds targeting Nintendo Switch.
The native crash support for Android and iOS is achieved by adding platform-specific SDKs to the generated Xcode and Gradle projects at build time.
The iOS SDK and Android SDK are capable of self-initializing before the Unity engine itself is started. This allows us to capture bugs/crashes happening within the engine itself. There are two initialization types:
NativeInitializationType.Runtime: Native SDKs initialize during runtime alongside the C# SDKNativeInitializationType.BuildTime: Native SDKs initialize before Unity engine starts
With runtime initialization, the native SDKs are initialized at runtime alongside the C# SDK. This allows all options to be dynamically configured through C# code during execution.
At build time, the SDK modifies the generated Gradle project to include the Android SDK but sets io.sentry.auto-init in the AndroidManifest.xml to false. The Unity SDK will then initialize the Android 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.m file or write the options to file. The Unity SDK will then initialize the iOS SDK when it initializes itself.
When using build time initialization, the native SDKs are configured during build time and initialize before the Unity engine starts. This means the options are baked into the outputted projects and cannot be modified at runtime via C# code. Changes to properties like Release and Environment will not apply to events generated by the native SDKs.
The SDK modifies the generated Gradle project to include the Android SDK. At build time, it will also write the options to the AndroidManifest.xml. These options cannot be changed at runtime. Changes to the options in the configuration callback will not affect the Android SDK.
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 functionality.
The iOS SDK 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.
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.
On Windows, the Unity SDK includes the Native SDK 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.
The Native Support on macOS relies on the macOS SDK. Stackwalking happens in process.
On Linux the Unity SDK includes the Native SDK with the breakpad backend. A minidump is created in process and no handler executable is required.
Sentry requires debug information files to symbolicate your crashes. The Unity SDK provides an automated upload functionality for those symbol files that rely on the sentry-cli. This is done transparently so you're not required to run sentry-cli manually. The symbol upload happens during Unity build in the editor. We've included the executables for Windows, macOS, and Linux as part of the Unity SDK package.
The automated debug symbols upload is enabled by default but requires configuration. Go to Tools > Sentry > Editor to enter the Auth Token, Organization Slug, and the Project Name. Note that the Unity SDK creates a file at Assets/Plugins/Sentry/SentryCliOptions.asset to store the configuration, that should not be made publicly available.
Debug information files on the iOS platform are called dSYM.
For Sentry to symbolicate your crash logs we need two types of files:
dSYMthat the automated symbols upload will pick up at the end of the build process without further action required.BCSymbolMapfiles that are created during the archiving process
The automated symbol upload will take care of the BCSymbolMap files by processing them during the archiving process.
If you don't want to rely on the automated symbol upload, you can run sentry-cli through the commandline. For that, you can use the provided executables from within the package or follow the sentry-cli documentation to make it available globally. To upload debug symbols, run it with:
sentry-cli --auth-token sntrys_YOUR_TOKEN_HERE debug-files upload --org example-org --project example-project PATH_TO_SYMBOLS
Minidumps may contain sensitive information about the target system, such as environment variables, local pathnames, or in-memory representations of input fields, including passwords. By default, Sentry only uses minidump files to create events and immediately drops them. All sensitive information is stripped from the resulting events.
All other types of attachments, such as log files or screenshots, are stored for 30 days when sent to Sentry. Note that Sentry does not apply data scrubbing to attachments.
You can enable Store Minidumps As Attachments in your organization or project settings under Security & Privacy. By default, this setting is disabled. Determine the maximum number of crash reports that will be stored per issue; disabled, unlimited, or maximum per issue:
If you set a limit per issue, as in the example above, a limit of 5, Sentry will store the first 5 attachments associated with this issue, but drop any that follow. To make room for additional attachments, delete them. Sentry will then accept attachments until the limit is reached again.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").