feat: Managed layer initializes native SDK on iOS

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### API Changes
+
+- The native layer on iOS no longer self-initializes before the Unity game starts. Instead, it accepts the options at the end of the configure call. To restore the old behavior, users can opt-in to initializing native first via `IosInitializeNativeFirst`. Note that using this option comes with the limitation of baking the options into the generated Xcode project at build-time. ([#1915](https://github.com/getsentry/sentry-unity/pull/1915))
+
 ### Dependencies
 
 - Bump CLI from v2.39.0 to v2.39.1 ([#1922](https://github.com/getsentry/sentry-unity/pull/1922))

package-dev/Plugins/iOS/SentryNativeBridge.m

@@ -4,11 +4,41 @@
 NS_ASSUME_NONNULL_BEGIN
 
 // macOS only
-int SentryNativeBridgeLoadLibrary() { return 0; }
-void *_Nullable SentryNativeBridgeOptionsNew() { return nil; }
-void SentryNativeBridgeOptionsSetString(void *options, const char *name, const char *value) { }
-void SentryNativeBridgeOptionsSetInt(void *options, const char *name, int32_t value) { }
-void SentryNativeBridgeStartWithOptions(void *options) { }
+// On iOS, the SDK is linked statically so we don't need to dlopen() it.
+int SentryNativeBridgeLoadLibrary() { return 1; }
+
+int SentryNativeBridgeIsEnabled() { return [SentrySDK isEnabled] ? 1 : 0; }
+
+const void *SentryNativeBridgeOptionsNew()
+{
+    NSMutableDictionary *dictOptions = [[NSMutableDictionary alloc] init];
+    dictOptions[@"sdk"] = @ { @"name" : @"sentry.cocoa.unity" };
+    dictOptions[@"enableAutoSessionTracking"] = @NO;
+    dictOptions[@"enableAppHangTracking"] = @NO;
+    return CFBridgingRetain(dictOptions);
+}
+
+void SentryNativeBridgeOptionsSetString(const void *options, const char *name, const char *value)
+{
+    NSMutableDictionary *dictOptions = (__bridge NSMutableDictionary *)options;
+    dictOptions[[NSString stringWithUTF8String:name]] = [NSString stringWithUTF8String:value];
+}
+
+void SentryNativeBridgeOptionsSetInt(const void *options, const char *name, int32_t value)
+{
+    NSMutableDictionary *dictOptions = (__bridge NSMutableDictionary *)options;
+    dictOptions[[NSString stringWithUTF8String:name]] = [NSNumber numberWithInt:value];
+}
+
+void SentryNativeBridgeStartWithOptions(const void *options)
+{
+    NSMutableDictionary *dictOptions = (__bridge_transfer NSMutableDictionary *)options;
+    id sentryOptions = [[SentryOptions alloc]
+        performSelector:@selector(initWithDict:didFailWithError:)
+        withObject:dictOptions withObject:nil];
+
+    [SentrySDK performSelector:@selector(startWithOptions:) withObject:sentryOptions];
+}
 
 int SentryNativeBridgeCrashedLastRun() { return [SentrySDK crashedLastRun] ? 1 : 0; }
 

package-dev/Plugins/iOS/SentryNativeBridgeNoOp.m

@@ -64,4 +64,4 @@ void SentryNativeBridgeWriteScope( // clang-format off
 ) // clang-format on
 { }
 
-NS_ASSUME_NONNULL_END
+NS_ASSUME_NONNULL_END

package-dev/Plugins/macOS/SentryNativeBridge.m

@@ -49,6 +49,8 @@ int SentryNativeBridgeLoadLibrary()
     return loadStatus;
 }
 
+int SentryNativeBridgeIsEnabled() { return [SentrySDK isEnabled] ? 1 : 0; }
+
 const void *SentryNativeBridgeOptionsNew()
 {
     NSMutableDictionary *dictOptions = [[NSMutableDictionary alloc] init];

samples/unity-of-bugs/Assets/Resources/Sentry/SentryOptions.asset

@@ -71,5 +71,5 @@ MonoBehaviour:
   <OptionsConfiguration>k__BackingField: {fileID: 11400000, guid: cea63afb7c75f429799422326f926abe,
     type: 2}
   <Debug>k__BackingField: 1
-  <DebugOnlyInEditor>k__BackingField: 1
-  <DiagnosticLevel>k__BackingField: 2
+  <DebugOnlyInEditor>k__BackingField: 0
+  <DiagnosticLevel>k__BackingField: 0

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

@@ -83,6 +83,8 @@ public override void Configure(SentryUnityOptions options)
             return sentryEvent;
         });
 
+        options.IosNativeInitializationType = NativeInitializationType.BuildTime;
+
         Debug.Log("OptionConfigure finished.");
     }
 }

src/Sentry.Unity.Editor.iOS/BuildPostProcess.cs

@@ -52,11 +52,29 @@ internal static void AddSentryToXcodeProject(SentryUnityOptions? options,
             logger.LogWarning("iOS native support disabled because Sentry has not been configured. " +
                               "You can do that through the editor: {0}", SentryWindow.EditorMenuPath);
 
+            // Even with native support disabled the P/Invoke declarations from `SentryCocoaBridgeProxy` must exist.
             SetupNoOpBridge(logger, pathToProject);
             return;
         }
 
-        if (!IsNativeSupportEnabled(options, logger))
+        if (IsNativeSupportEnabled(options, logger))
+        {
+            SetupSentry(options, cliOptions, logger, pathToProject);
+        }
+        else
+        {
+            logger.LogInfo("iOS native support has been disabled through the options. " +
+                           "Native support will not be available at runtime.");
+
+            // Even with native support disabled the P/Invoke declarations from `SentryCocoaBridgeProxy` must exist.
+            SetupNoOpBridge(logger, pathToProject);
+        }
+
+        // We want to avoid users getting stuck on a cached built output.
+        // This can happen if the user appends builds
+        //   - and toggles the `IosNativeSupportEnabled` from `true` to `false`
+        //   - and toggles the `IosNativeInitializationType` from `Standalone` to `Runtime`
+        if (options.IosNativeInitializationType is NativeInitializationType.Runtime)
         {
             var mainPath = Path.Combine(pathToProject, SentryXcodeProject.MainPath);
             if (File.Exists(mainPath))
@@ -69,12 +87,7 @@ internal static void AddSentryToXcodeProject(SentryUnityOptions? options,
                         "during a previous build. Select 'Replace' when exporting the project to create a clean project.");
                 }
             }
-
-            SetupNoOpBridge(logger, pathToProject);
-            return;
         }
-
-        SetupSentry(options, cliOptions, logger, pathToProject);
     }
 
     internal static void SetupNoOpBridge(IDiagnosticLogger logger, string pathToProject)
@@ -83,7 +96,6 @@ internal static void SetupNoOpBridge(IDiagnosticLogger logger, string pathToProj
         {
             logger.LogDebug("Copying the NoOp bride to the output project.");
 
-            // The Unity SDK expects the bridge to be there. The Xcode build will break during linking otherwise.
             var nativeBridgePath = Path.GetFullPath(Path.Combine("Packages", SentryPackageInfo.GetName(), "Plugins", "iOS", SentryXcodeProject.NoOpBridgeName));
             CopyFile(nativeBridgePath, Path.Combine(pathToProject, "Libraries", SentryPackageInfo.GetName(), SentryXcodeProject.BridgeName), logger);
 
@@ -105,7 +117,11 @@ internal static void SetupSentry(SentryUnityOptions options,
 
         try
         {
-            // The Sentry.xcframework ends in '~' to hide it from Unity. Otherwise, Unity tries to export it with the XCode build.
+            // The Sentry.xcframework ends in '~' to hide it from Unity. This prevents Unity from exporting it with the XCode build.
+            // Ideally, we would let Unity copy this over but:
+            // - Detection of `.xcframework` as datatype and non-folder happened in Unity 2021
+            // - Without a `.meta` file we cannot opt-in embedding the framework
+            // - Even if Unity copies it, the framework still requires to be 'linked with binary' for it to work
             var frameworkPath = Path.GetFullPath(Path.Combine("Packages", SentryPackageInfo.GetName(), "Plugins", "iOS", SentryXcodeProject.FrameworkName + "~"));
             CopyFramework(frameworkPath, Path.Combine(pathToProject, "Frameworks", SentryXcodeProject.FrameworkName), logger);
 
@@ -115,8 +131,12 @@ internal static void SetupSentry(SentryUnityOptions options,
             using var sentryXcodeProject = SentryXcodeProject.Open(pathToProject, logger);
             sentryXcodeProject.AddSentryFramework();
             sentryXcodeProject.AddSentryNativeBridge();
-            sentryXcodeProject.AddNativeOptions(options, NativeOptions.CreateFile);
-            sentryXcodeProject.AddSentryToMain(options);
+
+            if (options.IosNativeInitializationType is NativeInitializationType.BuildTime)
+            {
+                sentryXcodeProject.AddNativeOptions(options, NativeOptions.CreateFile);
+                sentryXcodeProject.AddSentryToMain(options);
+            }
 
             if (cliOptions != null && cliOptions.IsValid(logger, EditorUserBuildSettings.development))
             {

src/Sentry.Unity.iOS/SentryCocoaBridgeProxy.cs

@@ -13,7 +13,8 @@ namespace Sentry.Unity.iOS;
 /// <see href="https://github.com/getsentry/sentry-cocoa"/>
 internal static class SentryCocoaBridgeProxy
 {
-    // Note: used on macOS only
+    public static bool IsEnabled() => SentryNativeBridgeIsEnabled() == 1;
+
     public static bool Init(SentryUnityOptions options)
     {
         if (LoadLibrary() != 1)
@@ -66,6 +67,9 @@ public static bool Init(SentryUnityOptions options)
     [DllImport("__Internal", EntryPoint = "SentryNativeBridgeLoadLibrary")]
     private static extern int LoadLibrary();
 
+    [DllImport("__Internal", EntryPoint = "SentryNativeBridgeIsEnabled")]
+    private static extern int SentryNativeBridgeIsEnabled();
+
     [DllImport("__Internal", EntryPoint = "SentryNativeBridgeOptionsNew")]
     private static extern IntPtr OptionsNew();
 

src/Sentry.Unity.iOS/SentryNativeCocoa.cs

@@ -30,6 +30,16 @@ internal static void Configure(SentryUnityOptions options, ISentryUnityInfo sent
 
         if (platform == RuntimePlatform.IPhonePlayer)
         {
+            if (SentryCocoaBridgeProxy.IsEnabled())
+            {
+                options.DiagnosticLogger?.LogDebug("The native SDK is already initialized");
+            }
+            else if (!SentryCocoaBridgeProxy.Init(options))
+            {
+                options.DiagnosticLogger?.LogWarning("Failed to initialize the native SDK");
+                return;
+            }
+
             options.ScopeObserver = new NativeScopeObserver("iOS", options);
         }
         else
@@ -76,6 +86,8 @@ internal static void Configure(SentryUnityOptions options, ISentryUnityInfo sent
                 }
             }
         }
+
+        options.DiagnosticLogger?.LogInfo("Successfully initialized the native SDK");
     }
 
     /// <summary>

src/Sentry.Unity/SentryUnityOptions.cs

@@ -149,6 +149,12 @@ public sealed class SentryUnityOptions : SentryOptions
     /// </summary>
     public bool IosNativeSupportEnabled { get; set; } = true;
 
+    /// <summary>
+    /// Whether the SDK should initialize the native SDK before the Unity game. This bakes the options at build-time into
+    /// the generated Xcode project
+    /// </summary>
+    public NativeInitializationType IosNativeInitializationType { get; set; } = NativeInitializationType.Runtime;
+
     /// <summary>
     /// Whether the SDK should add native support for Android
     /// </summary>
@@ -356,3 +362,17 @@ public enum ScreenshotQuality
     /// </summary>
     Low
 }
+
+public enum NativeInitializationType
+{
+    /// <summary>
+    /// The native SDK will be initialized at runtime through the C# layer. Options that you set programmatically
+    /// will apply to the native SDK as well.
+    /// </summary>
+    Runtime,
+    /// <summary>
+    /// The SDK will bake the options available at build time. The native SDK will auto-initialize outside the of the
+    /// game. Options that you modify programmatically will not apply to the native SDK.
+    /// </summary>
+    BuildTime,
+}