Update initialization behaviour on mobile

[bitsandfoxes]

Programmatic Configuration and Native Support on Mobile

Background

The SDKs current approach let's the native SDKs self-initialize when targeting mobile. This approach guarantees the SDK to capture all errors (even Unity engine crashes) but it also creates a lot of friction for users during onboarding and setup.
Having to explain the different layers is a non-trivial task.

Example:

• A user wants to set the environment:
  For that they have to implement both, the Runtime and the BuildTime configuration. Even with the unified approach of having only one configure callback, they are still limited to setting a static string and are not able to compute the value at runtime. That limitation has to somehow be explained again.

Current State

The Unity SDK currently handles native support differently across platforms:

Mobile Platforms (Android, iOS)

• Current Implementation: Native SDKs self-initialize outside Unity runtime
• Mechanism: Configured through Gradle (Android) and Xcode (iOS) project modifications
• Advantages:
  • Can capture Unity crashes
• Challenges:
  • Configuration gets "baked" into the project at build time
  • Complex configuration layers confuse users.
  • Inconsistent runtime/build time configuration patterns even with the unified configure callback

Desktop Platforms (Windows/Linux/macOS)

• Current Implementation: Native SDKs initialize within Unity runtime
• Behavior: Uses Configure callback consistently across C# Unity SDK and native layers. The options at the end of Configure are the ones that initialize the native layer

Proposed Solution

1. Unified Configuration API (mostly done already)

• Replace separate Runtime/BuildTime configuration with single Configure method
  • Issue feat: Created programmatic configuration for CLI options #1887: Separate CLI options from build time configure
  • Issue feat: Add OptionConfiguration to replace Runtime/BuildTime  #1888: Implement unified scriptable object for configuration callback
  • Deprecate existing Runtime/BuildTime configuration callbacks

2. Unified SDK Initialization

iOS Implementation

• Framework handling:
  • Instead of handling filecopy ourselves we can mark .framework for targeting iOS.
  • Unity will handle that for us since we'll never know whether we'll need it. The SDK can and will be initialized during runtime.
• Initialization:
  • Use native bridge for SDK initialization. We've already got a working example for macOS.
  • We can rely on the Cocoa SDK's isEnabled property to avoid reinitialization.

Android Implementation

• Package handling:
  • Instead of handling filecopy ourselves we can mark the .jar and `.aar for targeting Android.
  • Unity handles file copying automatically. We can drop parts of the Gradle modifications.
• Initialization:
  • Leverage Unity Java wrapper
  • We'll have to check on the scope sync to extend this to the Init call
  • We can rely on the Android SDK's isEnabled property to avoid reinitialization.

3. Mobile Platform Auto-Initialization

Convert current auto-initialization to opt-in feature. This way we maintain crash capture capabilities for users who need it.

4. Future Enhancement

Implement native callback support. I.e. enable code/snippet injection for native SDK events (e.g., BeforeSend)

Benefits

1. Simplified Configuration

   • Single, consistent configuration pattern
   • Eliminates confusion around runtime/build time configuration

2. Improved Initialization Flow

   • Consistent initialization across all platforms
   • Predictable option handling

3. Enhanced Flexibility

   • Optional auto-initialization for mobile platforms. So those users that need it can make the educated decision to work with/around the limitations
   • Better UaaL (Unity as a Library) support

Migration Path

We're going to have to make sure to let users know about the behavioural change. I.e. a popup notice during package update?