fix(Unity): Updated native initialization (#12912)

Author: bitsandfoxes

docs/platforms/unity/native-support/index.mdx

@@ -4,31 +4,40 @@ description: "Learn how the Unity SDK handles native support."
 sidebar_order: 100
 ---
 
-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 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)
 
-<Alert>
+## Mobile
 
-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](/platforms/unity/configuration/options/) will not affect events from the native layer.
+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.
 
-</Alert>
+### Initialization of the Native SDKs
 
-<Alert>
+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.
+There are two initialization types:
 
-The Unity SDK captures C# exceptions and does not break any builds targeting Nintendo Switch.
+- `NativeInitializationType.Runtime`: Native SDKs initialize during runtime alongside the C# SDK
+- `NativeInitializationType.BuildTime`: Native SDKs initialize before Unity engine starts
 
-</Alert>
+### Runtime Initialization (Default)
 
-## Mobile
+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.
+
+#### Android
+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.
 
-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.
+#### 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.
 
-### Android
+### Build Time Initialization
 
-When choosing 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.
+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.
 
-### iOS
+#### Android
+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.
 
-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.
+#### 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 [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.