Migration Guide
Learn more about migrating to the current version.
The native layer on mobile platforms (iOS and Android) no longer self-initializes before the Unity game engine starts. Previously, the SDK would use the options at build-time and bake them into the native layer. Instead, the SDK will now take the options passed into the Configure callback and use those to initialize the native SDKs. This allows users to modify the native SDK's options at runtime programmatically. The initialization behaviour is controlled by IosNativeInitializationType and AndroidNativeInitializationType options.
To restore the previous behaviour, you can set the IosNativeInitializationType and AndroidNativeInitializationType options to BuildTime.
The Runtime- and BuildTime-Configuration have been merged into a single OptionsConfiguration script. This allows for programmatic configuration of the SDK in one place using precompile directives instead of having to duplicate setting options in two different files.
You can still use the old configuration classes, but they have been deprecated and will be removed in a future version. Going forward, you should use the new OptionsConfiguration script and make use of the precompile directives when setting options for different platforms.
The base classes for the Scriptable Objects used for programmatic configuration have been updated:
Sentry.Unity.ScriptableOptionsConfigurationhas been changed toSentryRuntimeOptionsConfigurationSentry.Unity.Editor.ScriptableOptionsConfigurationhas been changed toSentryBuildtimeOptionsConfiguration
If you make use of the programmatic configuration, you'll need to update your implementation with these base classes.
You no longer need to to call SentryUnity.Init. Instead, you can let the SDK self-initialize and modify the options taken from the Sentry Unity editor configuration window by providing a ScriptableOptionsConfiguration object.
- Open the Sentry Unity editor configuration window.
- Go to the
Options Configtab. - Click
Create options configuration.- This will prompt you to pick a location for your version of the scriptable options configuration script.
- It will also create an instance of the ScriptableOptionsConfiguration and set in it the configuration window.
- Add your code to the newly created script.
Learn more in our options documentation.
Starting from version 0.7.0, the SDK is aliasing its dependencies. We do this to avoid creating conflicts with other packages. This also means that if you were relying on our dependencies for certain types like System.Text.Json, then you'll have to import them into your project yourself going forward.
The Sentry SDK deprecated the use of JSON files to store options and now uses scriptable objects instead. If you're migrating from version 0.3.0 or older, make sure to upgrade to version 0.15.0 first. It's the last version that supports options stored in JSON format. When you open the Sentry configuration editor window in version 0.15.0, your JSON file will be automatically converted into a scriptable object. This support will be dropped in version 0.16.0 and later.
The Sentry Unity Lite SDK is deprecated for mobile, desktop, WebGL, and console players. Customers using Unity 5.x can still use the Sentry Unity Lite as it continues to be compatible with sentry.io.
The updated Sentry Unity SDK requires Unity version 2019.4 or higher with .NET Standard 2.0 scripting profile.
- Remove the old
Sentry.csandSentrySdk.csfiles from your project. - Remove the old initialization code
gameObject.AddComponent<SentrySdk>().Dsn = "___PUBLIC_DSN___";. - Install the new Sentry Unity SDK.
- Calls to the API such as
SentrySdk.CaptureMessage("Test event");will continue to work and don't require any change. - Browse the documentation to learn more about the new capabilities of the SDK such as enriching events, tracing and configuration.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").