Currently, the Unity SDK offers native support for Android, iOS, and Windows. The support is set to
enabled by default and you can opt out for each platform individually in the configuration window.
The setup for the iOS and Android native SDKs happens during build time, with the options defined in the Sentry editor configuration window. Changes to the options object done through ScriptableOptionsConfiguration will not affect events from the native layer.
The native crash support for Android and iOS is achieved by modifying the generated platform-specific projects during build time. That way, the Sentry native crash support gets initialized before Unity, making it possible to capture errors of the Unity engine itself.
When chosing Android as a build target, Unity creates a Gradle project. During the Unity build process, the SDK embeds the Android SDK, as well as the provided options, by adding it to the generated project's Android Manifest.
When building your game for iOS, Unity exports it as an Xcode project. By modifying that generated project, the SDK adds the iOS SDK to provide native support. 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.
iOS - dSYM and Bitcode
Debug information files on the iOS platform are called dSYM, and the way to obtain them differs depending on whether
Enable Bitcode is set to
true in your Xcode project.
For Sentry to symbolicate your crash logs and with
bitcode enabled, we need two types of files:
dSYMfiles available only after App Store Connect finishes processing the build
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. To provide the dSYM files to Sentry, you can either set up the Sentry App Store Connect Integration so Sentry can fetch them for you, or download them from Apple and then upload them manually using sentry-cli.
bitcode disabled, the automated symbols upload will pick up the
dSYM files at the end of the build process without further action required.
Manual Upload Using sentry-cli
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 YOUR_AUTH_TOKEN debug-files upload --org example-org --project example-project PATH_TO_SYMBOLS
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").