Skip to content

Rework Initialization #2227

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 52 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
52 commits
Select commit Hold shift + click to select a range
14427b6
initial working implementation
bitsandfoxes Jul 3, 2025
bb4dbc0
fixed using in smoketester
bitsandfoxes Jul 4, 2025
0f97f0b
we actually need both. idk if that's great. doesn't look great
bitsandfoxes Jul 4, 2025
a76e957
bumped .NET to have the comment
bitsandfoxes Jul 7, 2025
e494279
Updated CHANGELOG.md
bitsandfoxes Jul 7, 2025
df211a3
bumped to cleaned up version of .NET
bitsandfoxes Jul 7, 2025
19c4e78
added services logging to init
bitsandfoxes Jul 7, 2025
00e788a
added summary to platformservices
bitsandfoxes Jul 7, 2025
bfcd0f1
fixed namespaces
bitsandfoxes Jul 7, 2025
4448334
cleaned up bugfarmbuttons
bitsandfoxes Jul 7, 2025
232833c
namespace clean followup
bitsandfoxes Jul 7, 2025
bcbb551
fixed qualification
bitsandfoxes Jul 7, 2025
deb6aa7
moved scenetracing integration into the SDK
bitsandfoxes Jul 8, 2025
a66a5a6
updated CI to 2020
bitsandfoxes Jul 8, 2025
857e492
env bump
bitsandfoxes Jul 8, 2025
eefad70
removed now redundant test
bitsandfoxes Jul 8, 2025
16c9fcf
bumped uniy-of-bugs to 2020
bitsandfoxes Jul 8, 2025
6542706
updated the package
bitsandfoxes Jul 8, 2025
b48e60d
removed now redundant asmdef
bitsandfoxes Jul 8, 2025
76e05b2
Updated CHANGELOG.md
bitsandfoxes Jul 8, 2025
3fa372c
missing option field?
bitsandfoxes Jul 8, 2025
1f5e5cc
merged unity 2019 drop
bitsandfoxes Jul 8, 2025
83deeec
finished fixing the startup tracing
bitsandfoxes Jul 8, 2025
011ba1d
merged main
bitsandfoxes Jul 9, 2025
2a46b5f
bump android API level to 21 for 2020
bitsandfoxes Jul 9, 2025
7ac68be
Merge branch 'fix/android-2020-ci' into fix/initialization
bitsandfoxes Jul 9, 2025
43f5ae9
updated test to ignore harmless warning
bitsandfoxes Jul 9, 2025
ad0ae02
move startup tracing into the SDK
bitsandfoxes Jul 9, 2025
bb6f80a
.
bitsandfoxes Jul 9, 2025
c53ccb5
fix naming
bitsandfoxes Jul 9, 2025
d100d4f
Format code
getsentry-bot Jul 9, 2025
7faafb9
added tests
bitsandfoxes Jul 9, 2025
490e033
merged
bitsandfoxes Jul 9, 2025
2f42440
Format code
getsentry-bot Jul 9, 2025
d2709d1
updated snapshot
bitsandfoxes Jul 9, 2025
326dc32
Merge branch 'chore/cleanup-init' of https://github.com/getsentry/sen…
bitsandfoxes Jul 9, 2025
1183370
.
bitsandfoxes Jul 9, 2025
f1388b4
merged the init cleanup
bitsandfoxes Jul 10, 2025
594dc4a
fixed test
bitsandfoxes Jul 10, 2025
3bfc5fa
use platform services where applicable
bitsandfoxes Jul 10, 2025
0843ba5
forgot webgl
bitsandfoxes Jul 10, 2025
a4cbc59
rename setup platform services
bitsandfoxes Jul 10, 2025
32876ac
public close cutback
bitsandfoxes Jul 10, 2025
c6cbb0c
review
bitsandfoxes Jul 10, 2025
3a2328b
Format code
getsentry-bot Jul 10, 2025
2e4b3db
Merge branch 'main' into chore/cleanup-init
bitsandfoxes Jul 10, 2025
99bbb4d
Merge branch 'chore/cleanup-init' into fix/initialization
bitsandfoxes Jul 10, 2025
d67b2b9
Merge branch 'fix/initialization' of https://github.com/getsentry/sen…
bitsandfoxes Jul 10, 2025
ac366e7
Update CHANGELOG.md
bitsandfoxes Jul 11, 2025
76868b8
merged main
bitsandfoxes Jul 11, 2025
1f520ee
hold platformservices in options and handle tests
bitsandfoxes Jul 11, 2025
a47872d
Format code
getsentry-bot Jul 11, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
52 changes: 25 additions & 27 deletions package-dev/Runtime/SentryInitialization.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -39,61 +41,57 @@

namespace Sentry.Unity
{
public static class SentryInitialization
internal static class SentryInitialization
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can safely make this internal. The SDK ships with it's own .asmdef that allows us to hide internal types from the user.

{
/// <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.");
}
}
}

Expand Down
4 changes: 2 additions & 2 deletions package-dev/Runtime/SentryUserFeedback.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the desired effect. All things reside within SentrySdk.

}
}

Expand All @@ -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();
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion samples/unity-of-bugs/Assets/Scripts/BugFarmButtons.cs
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
using System;
using System.Globalization;
using System.Runtime.CompilerServices;
using Sentry;
using Sentry.Unity;
using UnityEngine;
using UnityEngine.Assertions;

Expand Down
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
2 changes: 1 addition & 1 deletion samples/unity-of-bugs/Assets/Scripts/ThreadingSamples.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
12 changes: 5 additions & 7 deletions src/Sentry.Unity.Android/SentryNativeAndroid.cs
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
using System;
using Sentry.Extensibility;
using Sentry.Unity.Integrations;
using Sentry.Unity.NativeUtils;
using UnityEngine;
using UnityEngine.Analytics;

Expand All @@ -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();

Expand Down Expand Up @@ -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");

Expand Down Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion src/Sentry.Unity.Editor/SentryScriptableObject.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 4 additions & 3 deletions src/Sentry.Unity.Native/SentryNative.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
using Sentry.Extensibility;
using Sentry.Unity.Integrations;
using System.Collections.Generic;
using Sentry.Unity.NativeUtils;
using UnityEngine;
using UnityEngine.Analytics;

Expand All @@ -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;
Expand Down
8 changes: 3 additions & 5 deletions src/Sentry.Unity.Native/SentryNativeBridge.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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();

Expand Down
21 changes: 9 additions & 12 deletions src/Sentry.Unity.iOS/SentryNativeCocoa.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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) =>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a public method, and we only need to pass options.
But if the static SentryPlatformServices.UnityInfo wasn't set properly before hand, we'll just pass that through below and it'll be hard to trace back why that was.

I think we could validate here (if we expect SentryPlatformServices.UnityInfo not to be null here) that it is indeed not null. And deal with it (log and continue, throw?)

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;
Expand Down Expand Up @@ -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))
Expand Down Expand Up @@ -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;
Expand Down
6 changes: 3 additions & 3 deletions src/Sentry.Unity/Il2CppEventProcessor.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand Down
36 changes: 36 additions & 0 deletions src/Sentry.Unity/NativeUtils/SentryPlatformServices.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
using System;

namespace Sentry.Unity.NativeUtils;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Putting the services into a very distinctive namespace to "discourage" usage.


/// <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; }
}
Loading