|
| 1 | +--- |
| 2 | +title: Programmatic Configuration |
| 3 | +description: "Learn more about how to configure the Unity SDK programmatically." |
| 4 | +sidebar_order: 20 |
| 5 | +--- |
| 6 | + |
| 7 | +We've added `Sentry Options Configuration` to the `Options Config` tab in the Sentry editor window to provide a way to modify options programmatically. |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +## Programmatic Configuration |
| 12 | + |
| 13 | +The Sentry SDK for Unity includes [platform-specific (that is, Native)](/platforms/unity/native-support/) SDKs, such as [Android](/platforms/android/), [Apple](/platforms/apple/guides/ios/), and [Native](/platforms/native/) to provide native crash suppport. These SDKs share the options with which they get initialized. |
| 14 | + |
| 15 | +The C# layer self-initializes through the use of the [SubsystemRegistration RuntimeInitializeOnLoadMethodAttribute](https://docs.unity3d.com/ScriptReference/RuntimeInitializeLoadType.SubsystemRegistration.html). |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +If provided, the `Option Configuration Script` is executed on each app startup. The options are first used to initialize the native SDKs, then the managed (C#) SDK. This means that the options you set in your `Configure` callback will also apply on the native layer. For example: |
| 20 | + |
| 21 | +```csharp |
| 22 | +public override void Configure(SentryUnityOptions options) |
| 23 | +{ |
| 24 | + // BeforeSend is currently limited to C# code. Native errors - such as crashes in C/C++ code - are getting |
| 25 | + // captured by the native SDKs, but the native SDKs won't invoke this callback. |
| 26 | + options.SetBeforeSend((sentryEvent, _) => |
| 27 | + { |
| 28 | + if (sentryEvent.Tags.ContainsKey("SomeTag")) |
| 29 | + { |
| 30 | + // Don't send events with a tag "SomeTag" to Sentry |
| 31 | + return null; |
| 32 | + } |
| 33 | + |
| 34 | + return sentryEvent; |
| 35 | + }); |
| 36 | + |
| 37 | + // Native SDK initialization timing options: |
| 38 | + // Build-time initialization: |
| 39 | + // + Can capture Unity engine errors |
| 40 | + // - Options are fixed at build time |
| 41 | + // Runtime initialization: |
| 42 | + // + Allows dynamic configuration |
| 43 | + // - May miss some early errors |
| 44 | +#if UNITY_ANDROID |
| 45 | + options.AndroidNativeInitializationType = NativeInitializationType.Runtime; |
| 46 | +#elif UNITY_IOS |
| 47 | + options.IosNativeInitializationType = NativeInitializationType.Runtime; |
| 48 | +#endif |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +### Initialize Native SDKs first when targeting iOS or Android |
| 53 | + |
| 54 | +On mobile, the Unity SDK automatically modifies the generated Xcode and Gradle project to also contain the Cocoa and Java SDK respectively. These SDKs are capable of self-initializing before the Unity engine itself is started. This allows us to capture bugs/crashes happening within the engine itself. |
| 55 | +There are two initialization types: |
| 56 | + |
| 57 | +- `NativeInitializationType.Runtime`: Native SDKs initialize during runtime alongside the C# SDK |
| 58 | +- `NativeInitializationType.BuildTime`: Native SDKs initialize before Unity engine starts |
| 59 | + |
| 60 | +### Runtime Initialization (Default) |
| 61 | +With runtime initialization, the native SDKs are initialized at runtime alongside the C# SDK. This allows all options to be dynamically configured through C# code during execution. |
| 62 | + |
| 63 | +### Build Time Initialization |
| 64 | +When using build time initialization, the native SDKs are configured during build time and initialize before the Unity engine starts. This means the options are baked into the outputted projects and cannot be modified at runtime via C# code. Changes to properties like `Release` and `Environment` will not apply to events generated by the native SDKs. |
0 commit comments