Rework Initialization

CHANGELOG.md

@@ -4,7 +4,18 @@
 
 ### Breaking Changes
 
-- Dropped support for Unity 2019. It reached End of Life in 2022 ([#2231](https://github.com/getsentry/sentry-unity/pull/2231))
+- Removed Unity 2019 support, which reached End of Life in 2022. Minimum supported version now is 2020 ([#2231](https://github.com/getsentry/sentry-unity/pull/2231))
+
+- **Breaking Change**: The Unity SDK's static API has been simplified moved from `Sentry.Unity.SentryUnity` and `Sentry.SentrySdk`
+  to `Sentry.Unity.SentrySdk`. 
+  This change enables [manual/programatic SDK initialization](https://docs.sentry.io/platforms/unity/configuration/options/programmatic-configuration/) with full functionality, previously only available through auto-initialization.
+  The underlying .NET SDK's `SentrySdk` class is now internal, and several previously public classes like `SentryInitialization` 
+  and `SentryIntegrations` are now internal.
+
+  **Migration**: Update your `using` directives from `using Sentry;` to `using Sentry.Unity;`. IDEs like Rider can automatically 
+  import the missing references. In some cases, you may need both `using Sentry.Unity;` (for the static API) and `using Sentry;` 
+  (for types like `SentryId`). No changes are required to your actual SDK method calls (e.g., `SentrySdk.CaptureException()` 
+  remains the same). ([#2227](https://github.com/getsentry/sentry-unity/pull/2227))
 
 ### Features
 

package-dev/Runtime/SentryInitialization.cs

@@ -15,7 +15,9 @@
 #endif
 
 using System;
+using Sentry.Unity;
 using Sentry.Extensibility;
+using Sentry.Unity.NativeUtils;
 #if UNITY_2020_3_OR_NEWER
 using System.Buffers;
 using System.Runtime.InteropServices;
@@ -39,61 +41,57 @@
 
 namespace Sentry.Unity
 {
-    public static class SentryInitialization
+    internal static class SentryInitialization
     {
+        /// <summary>
+        /// This is intended for internal use only.
+        /// The SDK relies on <c>SetupPlatformServices</c> getting called as the very first thing during the game's
+        /// startup. This ensures that features like line number and native support are set up and configured properly.
+        /// This is also the case when initializing manually from code.
+        /// </summary>
 #if SENTRY_WEBGL
         // On WebGL SubsystemRegistration is too early for the UnityWebRequestTransport and errors with 'URI empty'
         [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
 #else
         [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
 #endif
-        public static void Init()
+        private static void Init()
         {
-            var unityInfo = new SentryUnityInfo();
+            // We're setting up `UnityInfo` and the platform specific configure callbacks as the very first thing.
+            // These are required to be available during initialization.
+            SetupPlatformServices();
+
             // Loading the options invokes the ScriptableOption`Configure` callback. Users can disable the SDK via code.
-            var options = ScriptableSentryUnityOptions.LoadSentryUnityOptions(unityInfo);
+            var options = ScriptableSentryUnityOptions.LoadSentryUnityOptions();
             if (options != null && options.ShouldInitializeSdk())
             {
-                // Configures scope sync and (by default) initializes the native SDK.
-                SetupNativeSdk(options, unityInfo);
-                SentryUnity.Init(options);
+                SentrySdk.Init(options);
             }
             else
             {
                 // If the SDK is not `enabled` we're closing down the native layer as well. This is especially relevant
                 // in a `built-time-initialization` scenario where the native SDKs self-initialize.
 #if SENTRY_NATIVE_COCOA
-                SentryNativeCocoa.Close(options, unityInfo);
+                SentryNativeCocoa.Close(options);
 #elif SENTRY_NATIVE_ANDROID
-                SentryNativeAndroid.Close(options, unityInfo);
+                SentryNativeAndroid.Close(options);
 #endif
             }
         }
 
-        private static void SetupNativeSdk(SentryUnityOptions options, SentryUnityInfo unityInfo)
+        private static void SetupPlatformServices()
         {
-            try
-            {
+            SentryPlatformServices.UnityInfo = new SentryUnityInfo();
+
 #if SENTRY_NATIVE_COCOA
-                SentryNativeCocoa.Configure(options, unityInfo);
+            SentryPlatformServices.PlatformConfiguration = SentryNativeCocoa.Configure;
 #elif SENTRY_NATIVE_ANDROID
-                SentryNativeAndroid.Configure(options, unityInfo);
+            SentryPlatformServices.PlatformConfiguration = SentryNativeAndroid.Configure;
 #elif SENTRY_NATIVE
-                SentryNative.Configure(options, unityInfo);
+            SentryPlatformServices.PlatformConfiguration = SentryNative.Configure;
 #elif SENTRY_WEBGL
-              	SentryWebGL.Configure(options);
+            SentryPlatformServices.PlatformConfiguration = SentryWebGL.Configure;
 #endif
-            }
-            catch (DllNotFoundException e)
-            {
-                options.DiagnosticLogger?.LogError(e,
-                    "Sentry native-error capture configuration failed to load a native library. This usually " +
-                    "means the library is missing from the application bundle or the installation directory.");
-            }
-            catch (Exception e)
-            {
-                options.DiagnosticLogger?.LogError(e, "Sentry native error capture configuration failed.");
-            }
         }
     }
 

package-dev/Runtime/SentryUserFeedback.cs

@@ -86,7 +86,7 @@ public void SendFeedback()
             else
             {
                 // Since there is no screenshot added we can capture the feedback right away
-                SentryUnity.CaptureFeedback(_description.text, _email.text, _name.text, addScreenshot: false);
+                SentrySdk.CaptureFeedback(_description.text, _email.text, _name.text, addScreenshot: false);
             }
         }
 
@@ -99,7 +99,7 @@ private IEnumerator HideFormAndCaptureFeedback()
             // We're waiting for the EndOfFrame so the FeedbackForm gets updated before capturing the screenshot
             yield return new WaitForEndOfFrame();
 
-            SentryUnity.CaptureFeedback(_description.text, _email.text, _name.text, addScreenshot: true);
+            SentrySdk.CaptureFeedback(_description.text, _email.text, _name.text, addScreenshot: true);
 
             ResetUserFeedback();
         }

samples/unity-of-bugs/Assets/Scripts/AdditionalButtons.cs

@@ -1,7 +1,7 @@
 using System.Collections;
 using System.Threading;
-using System.Threading.Tasks;
 using Sentry;
+using Sentry.Unity;
 using UnityEngine;
 
 public class AdditionalButtons : MonoBehaviour

samples/unity-of-bugs/Assets/Scripts/BugFarmButtons.cs

@@ -1,7 +1,7 @@
 using System;
-using System.Globalization;
 using System.Runtime.CompilerServices;
 using Sentry;
+using Sentry.Unity;
 using UnityEngine;
 using UnityEngine.Assertions;
 

samples/unity-of-bugs/Assets/Scripts/NativeSupport/NativeButtons.cs

@@ -1,7 +1,7 @@
-using Sentry;
-using System;
+using System;
 using System.Collections.Generic;
 using System.Runtime.InteropServices;
+using Sentry.Unity;
 using UnityEngine;
 using UnityEngine.Diagnostics;
 using UnityEngine.UI;

samples/unity-of-bugs/Assets/Scripts/ThreadingSamples.cs

@@ -3,7 +3,7 @@
 using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
-using Sentry;
+using Sentry.Unity;
 using UnityEngine;
 using UnityEngine.Assertions;
 

src/Sentry.Unity.Android/SentryNativeAndroid.cs

@@ -1,6 +1,7 @@
 using System;
 using Sentry.Extensibility;
 using Sentry.Unity.Integrations;
+using Sentry.Unity.NativeUtils;
 using UnityEngine;
 using UnityEngine.Analytics;
 
@@ -19,7 +20,7 @@ public static class SentryNativeAndroid
     /// Configures the native Android support.
     /// </summary>
     /// <param name="options">The Sentry Unity options to use.</param>
-    public static void Configure(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo)
+    public static void Configure(SentryUnityOptions options)
     {
         MainThreadData.CollectData();
 
@@ -105,7 +106,7 @@ public static void Configure(SentryUnityOptions options, ISentryUnityInfo sentry
                 e, "Failed to reinstall backend. Captured native crashes will miss scope data and tag.");
         }
 
-        options.NativeSupportCloseCallback = () => Close(options, sentryUnityInfo);
+        options.NativeSupportCloseCallback = () => Close(options);
 
         options.DiagnosticLogger?.LogDebug("Fetching installation ID");
 
@@ -136,14 +137,11 @@ public static void Configure(SentryUnityOptions options, ISentryUnityInfo sentry
     /// <summary>
     /// Closes the native Android support.
     /// </summary>
-    public static void Close(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo) =>
-        Close(options, sentryUnityInfo, ApplicationAdapter.Instance.Platform);
-
-    internal static void Close(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo, RuntimePlatform platform)
+    public static void Close(SentryUnityOptions options)
     {
         options.DiagnosticLogger?.LogInfo("Attempting to close the Android SDK");
 
-        if (!sentryUnityInfo.IsNativeSupportEnabled(options, platform))
+        if (!options.UnityInfo.IsNativeSupportEnabled(options, ApplicationAdapter.Instance.Platform))
         {
             options.DiagnosticLogger?.LogDebug("Android Native Support is not enabled. Skipping closing the Android SDK");
             return;

src/Sentry.Unity.Editor/SentryScriptableObject.cs

@@ -36,7 +36,7 @@ internal static (SentryUnityOptions?, SentryCliOptions?) ConfiguredBuildTimeOpti
         SentryUnityOptions? options = null;
         if (scriptableOptions is not null)
         {
-            options = scriptableOptions.ToSentryUnityOptions(isBuilding: true, unityInfo: null);
+            options = scriptableOptions.ToSentryUnityOptions(isBuilding: true);
 
             // TODO: Move this into `Load` once we remove Runtime- and BuildTimeConfig
             // We're calling `Configure` here and not in `Load` so the new Config does not overwrite the BuildTimeConfig

src/Sentry.Unity.Native/SentryNative.cs

@@ -2,6 +2,7 @@
 using Sentry.Extensibility;
 using Sentry.Unity.Integrations;
 using System.Collections.Generic;
+using Sentry.Unity.NativeUtils;
 using UnityEngine;
 using UnityEngine.Analytics;
 
@@ -22,21 +23,21 @@ public static class SentryNative
     /// </summary>
     /// <param name="options">The Sentry Unity options to use.</param>
     /// <param name="sentryUnityInfo">Infos about the current Unity environment</param>
-    public static void Configure(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo)
+    public static void Configure(SentryUnityOptions options)
     {
         Logger = options.DiagnosticLogger;
 
         Logger?.LogInfo("Attempting to configure native support via the Native SDK");
 
-        if (!sentryUnityInfo.IsNativeSupportEnabled(options, ApplicationAdapter.Instance.Platform))
+        if (!options.UnityInfo.IsNativeSupportEnabled(options, ApplicationAdapter.Instance.Platform))
         {
             Logger?.LogDebug("Native support is disabled for '{0}'.", ApplicationAdapter.Instance.Platform);
             return;
         }
 
         try
         {
-            if (!SentryNativeBridge.Init(options, sentryUnityInfo))
+            if (!SentryNativeBridge.Init(options))
             {
                 Logger?.LogWarning("Sentry native initialization failed - native crashes are not captured.");
                 return;

src/Sentry.Unity.Native/SentryNativeBridge.cs

@@ -12,13 +12,11 @@ namespace Sentry.Unity.Native;
 /// P/Invoke to `sentry-native` functions.
 /// </summary>
 /// <see href="https://github.com/getsentry/sentry-native"/>
-public static class SentryNativeBridge
+internal static class SentryNativeBridge
 {
-    public static bool CrashedLastRun;
-
-    public static bool Init(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo)
+    public static bool Init(SentryUnityOptions options)
     {
-        _isLinux = sentryUnityInfo.IsLinux();
+        _isLinux = options.UnityInfo.IsLinux();
 
         var cOptions = sentry_options_new();
 

src/Sentry.Unity.iOS/SentryNativeCocoa.cs

@@ -14,15 +14,15 @@ public static class SentryNativeCocoa
     /// Configures the native support.
     /// </summary>
     /// <param name="options">The Sentry Unity options to use.</param>
-    /// <param name="sentryUnityInfo">Infos about the current Unity environment</param>
-    public static void Configure(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo) =>
-        Configure(options, sentryUnityInfo, ApplicationAdapter.Instance.Platform);
+    public static void Configure(SentryUnityOptions options) =>
+        Configure(options, ApplicationAdapter.Instance.Platform);
 
-    internal static void Configure(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo, RuntimePlatform platform)
+    // For testing
+    internal static void Configure(SentryUnityOptions options, RuntimePlatform platform)
     {
         options.DiagnosticLogger?.LogInfo("Attempting to configure native support via the Cocoa SDK");
 
-        if (!sentryUnityInfo.IsNativeSupportEnabled(options, platform))
+        if (!options.UnityInfo.IsNativeSupportEnabled(options, platform))
         {
             options.DiagnosticLogger?.LogDebug("Native support is disabled for: '{0}'", platform);
             return;
@@ -66,8 +66,8 @@ internal static void Configure(SentryUnityOptions options, ISentryUnityInfo sent
             return crashedLastRun;
         };
 
-        options.NativeSupportCloseCallback += () => Close(options, sentryUnityInfo, platform);
-        if (sentryUnityInfo.IL2CPP)
+        options.NativeSupportCloseCallback += () => Close(options);
+        if (options.UnityInfo.IL2CPP)
         {
             options.DefaultUserId = SentryCocoaBridgeProxy.GetInstallationId();
             if (string.IsNullOrEmpty(options.DefaultUserId))
@@ -96,14 +96,11 @@ internal static void Configure(SentryUnityOptions options, ISentryUnityInfo sent
     /// <summary>
     /// Closes the native Cocoa support.
     /// </summary>
-    public static void Close(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo) =>
-        Close(options, sentryUnityInfo, ApplicationAdapter.Instance.Platform);
-
-    internal static void Close(SentryUnityOptions options, ISentryUnityInfo sentryUnityInfo, RuntimePlatform platform)
+    public static void Close(SentryUnityOptions options)
     {
         options.DiagnosticLogger?.LogInfo("Attempting to close the Cocoa SDK");
 
-        if (!sentryUnityInfo.IsNativeSupportEnabled(options, platform))
+        if (!options.UnityInfo.IsNativeSupportEnabled(options, ApplicationAdapter.Instance.Platform))
         {
             options.DiagnosticLogger?.LogDebug("Cocoa Native Support is not enable. Skipping closing the Cocoa SDK");
             return;

src/Sentry.Unity/Il2CppEventProcessor.cs

@@ -17,11 +17,11 @@ internal class UnityIl2CppEventExceptionProcessor : ISentryEventExceptionProcess
     private static ISentryUnityInfo UnityInfo = null!; // private static will be initialized in the constructor
     private readonly Il2CppMethods _il2CppMethods;
 
-    public UnityIl2CppEventExceptionProcessor(SentryUnityOptions options, ISentryUnityInfo unityInfo)
+    public UnityIl2CppEventExceptionProcessor(SentryUnityOptions options)
     {
         Options = options;
-        UnityInfo = unityInfo;
-        _il2CppMethods = unityInfo.Il2CppMethods ?? throw new ArgumentNullException(nameof(unityInfo.Il2CppMethods),
+        UnityInfo = options.UnityInfo;
+        _il2CppMethods = UnityInfo.Il2CppMethods ?? throw new ArgumentNullException(nameof(UnityInfo.Il2CppMethods),
             "Unity IL2CPP methods are not available.");
 
         Options.SdkIntegrationNames.Add("IL2CPPLineNumbers");

src/Sentry.Unity/NativeUtils/SentryPlatformServices.cs

@@ -0,0 +1,36 @@
+using System;
+
+namespace Sentry.Unity.NativeUtils;
+
+/// <summary>
+/// These are SDK's services that are only available at runtime and cannot be baked into the SDK. The
+/// <c>SentryInitialization.cs</c> is provided as <c>.cs</c> and gets compiled with the game. It sets <c>IUnityInfo</c>
+/// and the <c>PlatformConfiguration</c> callback during the game's startup so that they are available during initializtion.
+/// </summary>
+/// <remarks>Consider this <c>internal</c>.</remarks>
+public static class SentryPlatformServices
+{
+    private static ISentryUnityInfo? _unityInfo;
+
+    /// <summary>
+    /// The UnityInfo holds methods that rely on conditionally compilation, i.e. IL2CPP backend.
+    /// </summary>
+    public static ISentryUnityInfo UnityInfo
+    {
+        get => _unityInfo ?? throw new InvalidOperationException("UnityInfo is null.");
+        set
+        {
+            if (_unityInfo != null)
+            {
+                throw new InvalidOperationException("Should not set twice. lol.");
+            }
+
+            _unityInfo = value;
+        }
+    }
+
+    /// <summary>
+    /// The PlatformConfiguration callback is responsible for configuring the native SDK and setting up scope sync.
+    /// </summary>
+    public static Action<SentryUnityOptions>? PlatformConfiguration { get; set; }
+}