diff --git a/src/includes/getting-started-primer/unity.mdx b/src/includes/getting-started-primer/unity.mdx index d05e3bb69f42a..d65de9a45f633 100644 --- a/src/includes/getting-started-primer/unity.mdx +++ b/src/includes/getting-started-primer/unity.mdx @@ -5,7 +5,8 @@ Our Unity SDK builds on top of the [.NET SDK](/platforms/dotnet/) and extends it - [Native support](/platforms/unity/native-support/) for automatic crash error tracking for - Android by using the [Android SDK](/platforms/android/) to support Java, Kotlin, C and C++ - iOS by using the [iOS SDK](/platforms/apple/guides/ios/) to support Objective-C, Swift, C and C++ - - Windows by using the [Native SDK](/platforms/native/) to support C and C++ with minidumps. + - Windows and Linux by using the [Native SDK](/platforms/native/) to support C and C++ with minidumps + - macOS by using the [macOS SDK](/platforms/apple/guides/macos/) to support Objective-C, Swift, C and C++ - [Offline caching](/platforms/unity/configuration/options/#cache-directory-path) stores event data to disk in case the device is not online - [Release health](/platforms/unity/configuration/releases/) to keep track of crash free users and sessions - [Breadcrumbs automatically](/platforms/unity/enriching-events/breadcrumbs/#automatic-breadcrumbs) captured for diff --git a/src/platforms/unity/native-support/index.mdx b/src/platforms/unity/native-support/index.mdx index d50dd6a560c14..6f3e639235ffa 100644 --- a/src/platforms/unity/native-support/index.mdx +++ b/src/platforms/unity/native-support/index.mdx @@ -14,25 +14,41 @@ The setup for the iOS and Android native SDKs happens during build time, with th -## Android +## Mobile + +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. + +### Android When chosing Android as a build target, Unity creates a Gradle project. During the Unity build process, the SDK embeds the [Android SDK](/platforms/android/), as well as the provided options, by adding it to the generated project's Android Manifest. -## iOS +### iOS When building your game for iOS, Unity exports it as an Xcode project. By modifying that generated project, the SDK adds the [iOS SDK](/platforms/apple/guides/ios/) 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](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. -## Windows +## 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. + +### 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. + +### macOS + +The Native Support on macOS relies on the [macOS SDK](/platforms/apple/guides/macos/). Stackwalking happens in process. + +### Linux -Windows native crashes are automatically captured through minidumps. 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 than the Android and iOS support where we inject native initialization code that runs before Unity engine runs. +On Linux the Unity SDK includes the [Native SDK](/platforms/native/) with the breakpad backend. A minidump is created in process and no handler executable is required. ## Debug Symbols -Sentry requires [debug information files](/platforms/android/data-management/debug-files/) to symbolicate your crash logs. The Unity SDK provides an automated upload functionality for those symbol files that rely on the [sentry-cli](/product/cli/). We've included the executables for Windows, macOS, and Linux inside the Unity SDK package. +Sentry requires [debug information files](/platforms/unity/data-management/debug-files/) to symbolicate your crashes. The Unity SDK provides an automated upload functionality for those symbol files that rely on the [sentry-cli](/product/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](https://sentry.io/api/), Org 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. +The automated debug symbols upload is enabled by default but requires configuration. Go to **Tools > Sentry > Editor** to enter the [Auth Token](https://sentry.io/api/), 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 @@ -42,13 +58,13 @@ For Sentry to symbolicate your crash logs and with `bitcode` enabled, we need tw 1. `dSYM` files available only **after** App Store Connect finishes processing the build 2. `BCSymbolMap` files 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 [App Store Connect Integration](/platforms/apple/guides/ios/dsym/#bitcode-appstore) so Sentry can fetch them for you or download and then upload them [manually using sentry-cli](/platforms/apple/guides/ios/dsym/#bitcode-sentrycli). +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](/platforms/apple/guides/ios/dsym/#bitcode-appstore) so Sentry can fetch them for you, or download them from Apple and then upload them [manually using sentry-cli](/platforms/apple/guides/ios/dsym/#bitcode-sentrycli). With `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 -You can either use the provided executables from within the package or follow the [sentry-cli documentation](/product/cli/installation/) to make it available globally. To upload debug symbols, run it with: +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](/product/cli/installation/) to make it available globally. To upload debug symbols, run it with: ```bash sentry-cli --auth-token YOUR_AUTH_TOKEN upload-dif --org ___ORG_SLUG___ --project ___PROJECT_SLUG___ PATH_TO_SYMBOLS