feat: support for unity as a library on iOS

CHANGELOG.md

@@ -13,6 +13,7 @@
 
 ### Features
 
+- Added experimental support for Unity as a Library on iOS. With `IosNativeInitializationType` set to `NativeInitializationType.External`, the game attaches to the sentry-cocoa SDK that the app already started instead of bundling and starting its own. Native crashes carry the game's context and breadcrumbs, C# events and logs use the app's release, environment, user, and trace, the game's transactions join the app's trace, and the game's debug symbols are still uploaded automatically. ([#2885](https://github.com/getsentry/sentry-unity/pull/2885))
 - The SDK now supports Linux ARM64 dedicated servers (Unity 6000.3 and newer, IL2CPP). The native SDK for both backends ships for `x86_64` and `ARM64`, and the build picks the one matching the player. ([#2894](https://github.com/getsentry/sentry-unity/pull/2894))
 
 ### Dependencies

docs/agent-guides/platform-apple.md

@@ -19,12 +19,15 @@
 - App-hang tracking disables the C# ANR watchdog on iOS and macOS when the Cocoa backend is active.
 - macOS Cocoa screenshots are disabled because UIKit is unavailable.
 - Cocoa attachment synchronization is not implemented.
+- iOS external initialization (experimental): C# never initializes or closes Cocoa, attaches only if the host app already initialized it, keeps the host's SDK name, and disables the C# ANR watchdog. It doesn't sync user, environment, or trace to the host's scope, turns off C# session tracking, uses the host's release and environment unless set, puts the host's user on C# events (per event) and logs (at start and on resume) unless the game sets its own (`NativeAppUser`), continues the host's trace (`NativePropagationContext`, read through the bridge on every use) unless a sampled C# span is active. Transactions started through `Sentry.Unity.SentrySdk.StartTransaction(name, operation)` join the host's trace: as a child of the host's active span, inheriting its sampling decision and DSC, otherwise as a root with sampling deferred to the game.
 
 ## iOS Export
 
 - iOS editor code is in `src/Sentry.Unity.Editor.iOS/`.
 - It copies `Sentry.xcframework~` and bridge source, mutates the PBX project through reflection, embeds/links the framework, adds `-ObjC`, and can write build-time options into `main.mm`.
 - Reflection avoids requiring iOS editor modules on Windows or Linux.
+- External exports copy `SentryNativeBridgeExternal.m` as the bridge instead: it looks up the core classes of the app's own SDK (`SentrySDKInternal`, `SentryScope`, `SentryBreadcrumb`) at runtime and checks every selector with `respondsToSelector:`, as Unity builds without Objective-C exceptions. Keep its entry points in sync with the other bridges.
+- External exports copy no framework and add the symbol upload build phase to `UnityFramework`, which an embedding app builds.
 - Disabled/unconfigured iOS still installs a no-op bridge so P/Invoke symbols resolve.
 - Changing an append build from build-time to runtime/disabled requires a Replace export; postprocessing fails rather than preserve stale `main.mm` initialization.
 

package-dev/Plugins/iOS/SentryNativeBridge.m

@@ -241,6 +241,15 @@ void SentryNativeBridgeUnsetUser()
     return cString;
 }
 
+// Only the app's own SDK provides these, see SentryNativeBridgeExternal.m.
+char *_Nullable SentryNativeBridgeGetOption(const char *name) { return NULL; }
+
+char *_Nullable SentryNativeBridgeGetTraceHeader() { return NULL; }
+
+char *_Nullable SentryNativeBridgeGetBaggageHeader() { return NULL; }
+
+char *_Nullable SentryNativeBridgeGetUser() { return NULL; }
+
 void SentryNativeBridgeSetTrace(const char *traceId, const char *spanId)
 {
     if (traceId == NULL || spanId == NULL) {