[Unity] 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.
  • We will have to rely on the already built Xcode setup functionality to copy the framework and bridge. Unty does not recognize .xcframework on versions 2020 and older.
• 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?

[bitsandfoxes]

Update after giving the implementation a try:

The Issue

We need to handle three distinct scenarios for native support:

1. Runtime: (Default) The native SDK will be set up in the Xcode/Gradle project but gets initialized by the C# layer
2. Native Standalone: The native SDK will be configured at build-time and auto-initializes
3. Disabled: This helps unblock users in case of UaaL or similar usecases where we cannot modify the generated project

Currently, this would require multiple boolean flags that are confusing and can create invalid combinations i.e.

• IosNativeSupportEnabled: Checked at runtime whether the C# layer should initialize the native SDK
• IosNativeStandaloneInit: Checked at build time whether the options should get baked into the Xcode project
• IosDontModifyXcode?: To disable all native support?

Proposed Solution

Replace multiple flags with a single enum:

// If false, do not modify the Xcode/Gradle project. If set to `false` at build time but `true` at runtime 
// we can check whether we can find the native SDK and log a configuration error.
public bool IsNativeSupportEnabled = true;

// Default: Runtime
public enum NativeInitializationType
{
    Runtime, // Copy the native SDK, allow runtime configuration, initialize through the C# layer
    BuildTime, // Copy the native SDK, bake options into the project, set up auto-init outside of Unity
    // UaaL, // (For the future) Don't copy the SDK but attempt to sync scope with the surrounding native SDK
}

This:

• Makes the available options explicit and mutually exclusive
  • We'd need to put some checks in place to not attempt to init if there is no native SDK. I.e. the NoOp bridge should get a method to validate the setup.
• I think this separates build-time from runtime behavior. Users have to opt-in the advanced behaviour. And we stay forward compatible with additional usecases (UaaL).
• Eliminates invalid configuration combinations. I.e. DontModifyProject = true and at runtime the NativeSupport = true.?

[bruno-garcia]

This is available on version: 3.0.0-beta.0
To close this we're figuring out testing as it creates a whole new branch for the device tests on mobile

[bruno-garcia]

@bitsandfoxes this has been shipped right?

[bitsandfoxes]

@bitsandfoxes this has been shipped right?

Correct! And we've got CI coverage for it as well.