Configuration options

The BugSnag client object has many configuration options that can be set to customize the content of events and sessions and how they are sent.

This documentation is for version 5 of the BugSnag Unity notifier. We recommend upgrading to the latest release using our Upgrade guide. Documentation for the current release can be found here.

Setting configuration options

Setting configuration in the Unity Inspector

Some BugSnag settings can be configured from the Unity Inspector. This is recommended if you want to make small tweaks to BugSnag’s default behaviour:

BugSnag Unity Inspector configuration options

Setting configuration in code

Alternatively, BugSnag’s default behaviour can also be specified in code by creating a Configuration object and passing it into Bugsnag.Start:

Configuration config = new Configuration("your-api-key-here");
// alter default behaviour here
Bugsnag.Start(config);

Configuration properties must be altered before Bugsnag.Start() is called to have any effect.

AppType

If your app’s codebase contains different entry-points/processes, but reports to a single BugSnag project, you might want to add information denoting the type of process the error came from.

This information can be used in the dashboard to filter errors and to determine whether an error is limited to a subset of appTypes.

Configuration config = new Configuration("your-api-key-here");
config.AppType = "lite";
Bugsnag.Start(config);

AppVersion

If you want to manually track in which versions of your application each exception happens, you can set AppVersion.

Configuration config = new Configuration("your-api-key-here");
config.AppVersion = "1.2.3-alpha";
Bugsnag.Start(config);

AppHangThresholdMillis

This only applies to iOS App Hangs.

By default this is set to the constant BugsnagAppHangThresholdFatalOnly, meaning that an error will be sent to BugSnag if your app is terminated by the user or the iOS watchdog while the main thread has been hung for 2 seconds or longer.

To additionally enable reporting of non-fatal hangs from which your app recovered, configure the threshold to the desired hang duration:

Configuration config = new Configuration("your-api-key-here");
config.AppHangThresholdMillis = 5000;
Bugsnag.Start(config);

AutoCaptureSessions

This configuration option is deprecated and will be removed in a future release. Use AutoTrackSessions instead.

Set to false to disable automatic session tracking.

Configuration config = new Configuration("your-api-key-here");
config.AutoCaptureSessions = false;
Bugsnag.Start(config);

If you want control over what is deemed a session, you can manage the session lifecycle using StartSession(), PauseSession() and ResumeSession().

AutoDetectAnrs

When the main thread of an Android app is blocked for too long, it appears unresponsive and the Android OS creates an Application Not Responding (ANR) error, presenting the user with a dialog option to force quit the app.

By default ANR detection is enabled. Set it to false if you do not want to capture these events

Configuration config = new Configuration("your-api-key-here");
config.AutoDetectAnrs = false;
Bugsnag.Start(config);

Changing the value of AutoDetectAnrs in Configuration after BugSnag has started will not affect functionality. If you wish to stop or start ANR detection after startup, you can use the following method on the Bugsnag client directly: Bugsnag.SetAutoDetectAnrs(false);

AutoDetectErrors

By default, we will automatically notify BugSnag of any fatal exceptions (crashes) in your game. If you want to stop this from happening, you can set the AutoDetectErrors property when initializing BugSnag:

Configuration config = new Configuration("your-api-key-here");
config.AutoDetectErrors = false;
Bugsnag.Start(config);

Changing the value of AutoDetectErrors in Configuration after BugSnag has started will not affect functionality. If you wish to stop or start error detection after startup, you can use the following method on the Bugsnag client directly: Bugsnag.SetAutoDetectErrors(false);

AutoNotify

This configuration option is deprecated and will be removed in a future release. Use AutoDetectErrors instead.

By default, we will automatically notify BugSnag of any fatal exceptions (crashes) in your game. If you want to stop this from happening, you can set the AutoNotify property when initializing BugSnag:

Configuration config = new Configuration("your-api-key-here");
config.AutoNotify = false;
Bugsnag.Start(config);

Changing the value of AutoNotify in Configuration after BugSnag has started will not affect functionality. If you wish to stop or start error detection after startup, you can use the following method on the Bugsnag client directly: Bugsnag.SetAutoNotify(false);

AutoTrackSessions

Set to false to disable automatic session tracking.

Configuration config = new Configuration("your-api-key-here");
config.AutoTrackSessions = false;
Bugsnag.Start(config);

If you want control over what is deemed a session, you can manage the session lifecycle using StartSession(), PauseSession() and ResumeSession().

Messages sent to the Debug logger will be recorded as breadcrumbs. By default BugSnag will record Log messages or greater (more severe), you can change this behavior by setting the BreadcrumbLogLevel in your scripts:

Configuration config = new Configuration("your-api-key-here");
config.BreadcrumbLogLevel = LogType.Warning;
Bugsnag.Start(config);

BundleVersion

Manually set the Native Cocoa Config Value

Configuration config = new Configuration("your-api-key-here");
config.BundleVersion = "1.22.333";
Bugsnag.Start(config);

Context

BugSnag uses the concept of contexts to help display and group your errors. Contexts represent what was happening in your game at the time an error occurs. By default, this will be set to be your currently active Unity Scene.

If you would like to set the BugSnag context manually, you can set the Context property in your scripts:

Bugsnag.Context = "Space Port";

DiscardClasses

Allows you to specify which events should be automatically discarded based on their errorClass.

Configuration config = new Configuration("your-api-key-here");
config.DiscardClasses = new [] { "NullReferenceException" };
Bugsnag.Start(config);

EnabledBreadcrumbTypes

By default BugSnag will automatically add breadcrumbs for common application events whilst your application is running. Set this option to configure which of these are enabled and sent to BugSnag.

Configuration config = new Configuration("your-api-key-here");
config.EnabledBreadcrumbTypes = new [] { BreadcrumbType.Log , BreadcrumbType.Navigation };
Bugsnag.Start(config);

EnabledErrorTypes

BugSnag will automatically detect different types of error in your application. Set this option if you wish to control exactly which types are enabled.

Configuration config = new Configuration("your-api-key-here");
config.EnabledErrorTypes = new [] { ErrorTypes.NativeCrashes, ErrorTypes.UnityWarningLogs };
Bugsnag.Start(config);

EnabledReleaseStages

By default, BugSnag will be notified of events that happen in any releaseStage. Set this option if you would like to change which release stages notify BugSnag.

Configuration config = new Configuration("your-api-key-here");
config.EnabledReleaseStages = new [] { "staging", "production" };
Bugsnag.Start(config);

Endpoint

This configuration option is deprecated and will be removed in a future release. Use Endpoints instead.

Configuration config = new Configuration("your-api-key-here");
config.Endpoint = new Uri("http://bugsnag.internal.example.com");
Bugsnag.Start(config);

Endpoints

By default we will send error reports to notify.bugsnag.com and sessions to sessions.bugsnag.com.

If you are using BugSnag On-premise you’ll need to set these to your Event Server and Session Server endpoints. If the notify endpoint is set but the sessions endpoint is not, session tracking will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.

Configuration config = new Configuration("your-api-key-here");
config.Endpoints = new EndpointConfiguration("https://notify.example.com", "https://sessions.example.com");
Bugsnag.Start(config);

LaunchDurationMillis

The amount of time (in milliseconds) after starting BugSnag that should be considered part of the app’s launch.

By default this value is 5000 milliseconds.

Configuration config = new Configuration("your-api-key-here");
config.LaunchDurationMillis = 10000;
Bugsnag.Start(config);

Events that occur during app launch will have their App.IsLaunching property set to true.

Setting this to 0 will cause BugSnag to consider the app to be launching until Bugsnag.MarkLaunchCompleted() has been called.

MaxBreadcrumbs

Sets the maximum number of breadcrumbs which will be stored. Once the threshold is reached, the oldest breadcrumbs will be deleted.

By default, 25 breadcrumbs are stored; this can be amended up to a maximum of 100.

Configuration config = new Configuration("your-api-key-here");
config.MaxBreadcrumbs = 50;
Bugsnag.Start(config);

MaxPersistedEvents

Sets the Native Android Config Value and the Native Cocoa Config Value

Configuration config = new Configuration("your-api-key-here");
config.MaxPersistedEvents = 50;
Bugsnag.Start(config);

NotifyLevel

This configuration option is deprecated and will be removed in a future release. Use NotifyLogLevel instead.

By default, BugSnag will be notified about any Exception logged to Debug.LogException. You can send additional log information to BugSnag (eg. all Debug.LogError messages) by changing the Notify Level property in the Unity Inspector.

You can also change this setting in your scripts as follows:

Configuration config = new Configuration("your-api-key-here");
config.NotifyLevel = LogType.Error;
Bugsnag.Start(config);

NotifyLogLevel

By default, BugSnag will be notified about any Exception logged to Debug.LogException. You can send additional log information to BugSnag (eg. all Debug.LogError messages) by changing the Notify Log Level property in the Unity Inspector.

You can also change this setting in your scripts as follows:

Configuration config = new Configuration("your-api-key-here");
config.NotifyLogLevel = LogType.Error;
Bugsnag.Start(config);

NotifyReleaseStages

This configuration option is deprecated and will be removed in a future release. Use EnabledReleaseStages instead.

Configuration config = new Configuration("your-api-key-here");
config.NotifyReleaseStages = new [] { "staging", "production" };
Bugsnag.Start(config);

PauseSession

Pause tracking a session. You should disable automatic session tracking via AutoTrackSessions if you call this method.

You should call this at the appropriate time in your application when you wish to pause a session. Any subsequent errors which occur in your application will still be reported to BugSnag but will not count towards your application’s stability score. This can be advantageous if, for example, you do not wish the stability score to include crashes reported in a particular part of your application.

Bugsnag.PauseSession();

Also see ResumeSession and StartSession.

PersistenceDirectory

Sets the Native Android Config Value

Configuration config = new Configuration("your-api-key-here");
config.PersistenceDirectory = "/my_absolute_path";

  Bugsnag.Start(config);

PersistUser

Set whether or not BugSnag should persist user information between application launches.

Configuration config = new Configuration("your-api-key-here");
config.PersistUser = false;

By default PersistUser is set to true.

ProjectPackages

Sets which package names BugSnag should consider as a part of the running application. We mark stacktrace lines as in-project if they originate from any of these packages and this allows us to improve the visual display of the stacktrace on the dashboard.

Configuration config = new Configuration("your-api-key-here");
config.ProjectPackages = new [] { "com.example.package" };
Bugsnag.Start(config);

RedactedKeys

Sets which values should be removed from any metadata before sending them to BugSnag. Use this if you want to ensure you don’t transmit sensitive data such as passwords and credit card numbers.

Any property whose key matches a redacted key will be filtered and replaced with [REDACTED]. By default, any key that contains “password” will be redacted. Be aware that if you set this configuration option, it will replace the default, so you may want to replace “password” in your own set if you want to filter that.

Configuration config = new Configuration("your-api-key-here");
config.RedactedKeys = new string[] {"credit_card_number"};

ReleaseStage

If you would like to distinguish between errors that happen in different stages of your game’s release process (development, qa, production, etc) you can set the ReleaseStage in your scripts:

Configuration config = new Configuration("your-api-key-here");
config.ReleaseStage = "development";
Bugsnag.Start(config);

By default this is set to be production if the build is a release build, and development for a debug build.

You can control whether events are sent for specific release stages using the EnabledReleaseStages option.

ReportUncaughtExceptionsAsHandled

The “unhandled” property of a report indicates that a crash may have occurred in a given session and reduces the stability score of the project. By default, only crashes from iOS and Android native crash handlers are reported as unhandled. To report both Exception-level log events from Unity and native crashes from iOS and Android as unhandled events, set this property to false:

Configuration config = new Configuration("your-api-key-here");
config.ReportUncaughtExceptionsAsHandled = false;
Bugsnag.Start(config);

ResumeSession

Resumes a session which has previously been stopped, or starts a new session if none exists. If a session has already been resumed or started and has not been stopped, calling this method will have no effect. You should disable automatic session tracking via AutoCaptureSessions if you call this method.

It’s important to note that sessions are stored in memory for the lifetime of the application process and are not persisted on disk. Therefore calling this method on app startup would start a new session, rather than continuing any previous session.

You should call this at the appropriate time in your application when you wish to resume a previously started session. Any subsequent errors which occur in your application will be reported to BugSnag and will count towards your application’s stability score.

Bugsnag.ResumeSession();

Also see StartSession and PauseSession.

SessionEndpoint

This configuration option is deprecated and will be removed in a future release. Use Endpoints instead.

Configuration config = new Configuration("your-api-key-here");
config.SessionEndpoint = new Uri("http://bugsnag.internal.example.com");
Bugsnag.Start(config);

SendThreads

Sets the Native Android Config Value and the Native Cocoa Config Value

By default SendThreads is set to ThreadSendPolicy.UNHANDLED_ONLY.

Configuration config = new Configuration("your-api-key-here");
config.SendThreads = ThreadSendPolicy.UNHANDLED_ONLY;
//config.SendThreads = ThreadSendPolicy.NEVER;
//config.SendThreads = ThreadSendPolicy.ALWAYS;
Bugsnag.Start(config);

StartSession

Starts tracking a new session. You should disable automatic session tracking via AutoCaptureSessions if you call this method.

You should call this at the appropriate time in your application when you wish to start a session. Any subsequent errors which occur in your application will be reported to BugSnag and will count towards your application’s stability score. This will start a new session even if there is already an existing session; you should call ResumeSession if you only want to start a session when one doesn’t already exist.

Bugsnag.StartSession();

Also see ResumeSession and PauseSession.

StopSession

This configuration option is deprecated and will be removed in a future release. Use PauseSession instead.

Bugsnag.StopSession();

Also see ResumeSession and StartSession.

User

BugSnag helps you understand how many of your users are affected by each error. In order to do this, we send along a userId with every exception. By default we will generate a unique ID and send this ID along with every exception from an individual device.

If you would like to override this User Id, for example to set it to be a username of your currently logged in user, you can set the User Id property:

Bugsnag.User.Id = "userId";
Bugsnag.User.Name = "User Name";
Bugsnag.User.Email = "user@email.com";

You can also set the email and name of the user and these will be searchable in the dashboard.

VersionCode

Manually set the Android application Version Code that is reported in events

Configuration config = new Configuration("your-api-key-here");
config.VersionCode = 123;
Bugsnag.Start(config);

Displaying the file for non-debug Unity builds

Filenames for Stacktraces may not be available in production builds, due to optimizations in Unity which remove this information. Currently we display ‘unknown file’ in this scenario.