Configuration options

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

Setting configuration options

Setting configuration in the Unity Editor

Most configuration options can be configured through the Unity Editor, in the BugSnag Configuration window:

The “Start Automatically” option is enabled by default and will start BugSnag recording events and sessions just before the first scene is loaded, provided your API key has also been set.

Setting configuration in code

To set configuration options in code, first ensure the “Start Automatically” project setting is disabled in the BugSnag Configuration window. Then create a Configuration object, initialized from the Unity Editor, which can then be overridden in code:

var config = BugsnagSettingsObject.LoadConfiguration();
config.AppVersion = "1.2.3-alpha";
Bugsnag.Start(config);

If you do not wish to use the Unity Editor configuration at all, simply create a Configuration object using the object constructor, passing in your API key.

Available options

API Key

The API key used for events sent to BugSnag.

var config = BugsnagSettingsObject.LoadConfiguration();
config.ApiKey = "your-api-key-here";
Bugsnag.Start(config);

You can find your API key in Project Settings from your BugSnag dashboard.

App Hang Threshold

Enables reporting of non-fatal app hangs from which your app recovered before being terminated by the user or the iOS watchdog.

By default this is set to 0, meaning that an error will only be sent to BugSnag if the app hang is fatal.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AppHangThresholdMillis = 5000;
Bugsnag.Start(config);

App Type

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.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AppType = "lite";
Bugsnag.Start(config);

App Version

The version of the application. This is really useful for finding out when errors are introduced and fixed. Additionally BugSnag can re-open closed errors if a later version of the app has a regression.

BugSnag will automatically set the version from your build settings. If you’d like to override this you can set the App Version configuration option:

var config = BugsnagSettingsObject.LoadConfiguration();
config.AppVersion = "1.2.3-alpha";
Bugsnag.Start(config);

Auto Detect Errors

By default, we will automatically notify BugSnag of any uncaught errors that we capture. Use this flag to disable all automatic detection.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AutoDetectErrors = false;
Bugsnag.Start(config);

Auto Track Sessions

By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AutoTrackSessions = false;
Bugsnag.Start(config);

If you want control over what is deemed a session, you can switch off the automatic session tracking option and manage the session manually. See Capturing sessions for more information.

Breadcrumb Log Level

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 Breadcrumb Log Level configuration options:

var config = BugsnagSettingsObject.LoadConfiguration();
config.BreadcrumbLogLevel = LogType.Warning;
Bugsnag.Start(config);

Bundle Version

The bundle version of the application.

We’ll automatically set this from the CFBundleVersion value in your Info.plist file. If you’d like to override this you can set the Bundle Version configuration option:

var config = BugsnagSettingsObject.LoadConfiguration();
config.BundleVersion = "1.22.333";
Bugsnag.Start(config);

Context

The “context” is a string that indicates what the user was doing when an error occurs and is given high visual prominence in the dashboard. Set an initial context that you want to send with events – see Setting context for more information.

Bugsnag.Context = "Space Port";

Discard Classes

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

var config = BugsnagSettingsObject.LoadConfiguration();
config.DiscardClasses = new List<Regex> { new Regex("NullReferenceException") };
Bugsnag.Start(config);

Enabled Breadcrumb Types

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.

var config = BugsnagSettingsObject.LoadConfiguration();
config.EnabledBreadcrumbTypes = new [] { BreadcrumbType.Log , BreadcrumbType.Navigation };
Bugsnag.Start(config);

Automatically captured breadcrumbs can be disabled as follows:

var config = BugsnagSettingsObject.LoadConfiguration();
config.EnabledBreadcrumbTypes = new BreadcrumbType[0];
Bugsnag.Start(config);

Captured errors

Error breadcrumbs (BreadcrumbType.Error) are left when an error event is sent to the BugSnag API.

Navigation changes

Navigation breadcrumbs (BreadcrumbType.Navigation) are left for navigation-related notifications to track the user’s journey in the app.

State changes

State breadcrumbs (BreadcrumbType.State) are left for system broadcast events. For example: network connectivity changes, orientation changes, etc. See Automatically captured data for more information.

User interaction

User breadcrumbs (BreadcrumbType.User) are left when the user performs certain system operations. See Automatically captured data for more information.

Enabled Error Types

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

var config = BugsnagSettingsObject.LoadConfiguration();
config.EnabledErrorTypes.ANRs = false;         // applies to Android only
config.EnabledErrorTypes.AppHangs = false;     // applies to iOS and macOS only
config.EnabledErrorTypes.Crashes = false;      // detect and report native crashes; applies to iOS, macOS and Android only
config.EnabledErrorTypes.OOMs = false;         // applies to iOS only
config.EnabledErrorTypes.ThermalKills = false; // applies to iOS only
config.EnabledErrorTypes.UnityLog = false;
Bugsnag.Start(config);

Enabled Release Stages

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.

var config = BugsnagSettingsObject.LoadConfiguration();
config.EnabledReleaseStages = new [] { "staging", "production" };
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.

var config = BugsnagSettingsObject.LoadConfiguration();
config.Endpoints = new EndpointConfiguration("https://notify.example.com", "https://sessions.example.com");
Bugsnag.Start(config);

Feature Flags

AddFeatureFlag

Declare a single feature flag or experiment with variant as an optional second parameter.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddFeatureFlag("Checkout button color", "Blue");
config.AddFeatureFlag("New checkout flow");
Bugsnag.Start(config);

AddFeatureFlags

Declare multiple feature flags or experiments.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddFeatureFlags(new FeatureFlag[] {
    new FeatureFlag("Checkout button color","Blue"),
    new FeatureFlag("Special offer","Free Coffee"),
    new FeatureFlag("New checkout flow")
});
Bugsnag.Start(config);

If AddFeatureFlags is called again, the new data will be merged with any existing feature flags with the newer variant values taking precedence.

ClearFeatureFlag

Remove a single feature flag or experiment.

var config = BugsnagSettingsObject.LoadConfiguration();
config.ClearFeatureFlag("Checkout button color");
Bugsnag.Start(config);

ClearFeatureFlags

Remove all feature flags and experiments.

var config = BugsnagSettingsObject.LoadConfiguration();
config.ClearFeatureFlags();
Bugsnag.Start(config);

See the Feature flags & experiments guide for more information.

Generate Anonymous ID

An anonymous ID is generated and persisted in local storage so that the user stability score can be calculated. Use this option to disable generation and storage of this ID and the user stability feature.

var config = BugsnagSettingsObject.LoadConfiguration();
config.GenerateAnonymousId = false;
Bugsnag.Start(config);

Launch Duration

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.

var config = BugsnagSettingsObject.LoadConfiguration();
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. See Identifying crashes at launch for further information.

Max Breadcrumbs

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

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

var config = BugsnagSettingsObject.LoadConfiguration();
config.MaxBreadcrumbs = 75;
Bugsnag.Start(config);

For Android NDK crashes, the maximum number of breadcrumbs is fixed at 50.

Max Persisted Events

Sets the maximum number of events which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest events will be deleted.

By default, 32 events are stored.

var config = BugsnagSettingsObject.LoadConfiguration();
config.MaxPersistedEvents = 50;
Bugsnag.Start(config);

Max Persisted Sessions

Sets the maximum number of sessions which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest sessions will be deleted.

By default, 128 sessions are stored.

var config = BugsnagSettingsObject.LoadConfiguration();
config.MaxPersistedSessions = 50;
Bugsnag.Start(config);

Max Reported Threads

Sets the maximum number of threads that will be captured and sent with an error event.

var config = BugsnagSettingsObject.LoadConfiguration();
config.MaxReportedThreads = 100;
Bugsnag.Start(config);

The default maximum number of threads that will be captured is 200.

Max String Value Length

The maximum length of a string in metadata. To help avoid excessive event payload sizes, any strings exceeding this length will be truncated.

This limit defaults to 10,000 characters.

var config = BugsnagSettingsObject.LoadConfiguration();
config.MaxStringValueLength = 10000;
Bugsnag.Start(config);

Metadata

Set diagnostic metadata that you want to send with all captured events – see Customizing error reports for more information.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddMetadata("account", "name", "Acme Co.");
config.AddMetadata("basket", new Dictionary<string, object> {
    { "delivery", "express" },
    { "sale", "spring" }
});
Bugsnag.Start(config);

You can also clear previously set metadata as follows:

var config = BugsnagSettingsObject.LoadConfiguration();
config.ClearMetadata("account")
// or
config.ClearMetadata("account", "name")
Bugsnag.Start(config);

Notify Log Level

By default, BugSnag will be notified about any Exception logged to Debug.LogException. You can send additional log information to BugSnag (e.g. all Debug.LogError messages) by changing the Notify Log Level configuration option.

var config = BugsnagSettingsObject.LoadConfiguration();
config.NotifyLogLevel = LogType.Error;
// Also available: LogType.Exception
//                 LogType.Assert
//                 LogType.Warning
//                 LogType.Log
Bugsnag.Start(config);

On Error Callbacks

Add callbacks to modify or discard error events before they are sent to BugSnag — see Customizing error reports for more information.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddOnError(@event => {
    @event.AddMetadata("game", "current_score", 13);
    return true;
});
Bugsnag.Start(config);

On Send Error Callbacks

Add callbacks to modify or discard error events before they are sent to BugSnag — see Customizing error reports for more information.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddOnSendError(@event => {
    @event.AddMetadata("account", "name", "Acme Co.");
    @event.AddMetadata("account", "paying_customer", true);

    // Return `false` if you'd like to stop this error being reported
    return true;
});
Bugsnag.Start(config);

On Session Callbacks

Add callbacks to modify or discard sessions before they are sent to BugSnag — see Capturing sessions for more information.

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddOnSession(session => {
    var userId = getMyUserIdentifier(); // a custom user resolver
    session.setUser(userId, null, null);
    return true; // Return false to discard
});
Bugsnag.Start(config);

Persistence Directory

Sets the directory where BugSnag data, such as event and session payloads, are cached on disk. User information is also persisted here if the Persist User configuration option is true.

var config = BugsnagSettingsObject.LoadConfiguration();
config.PersistenceDirectory = "/my_absolute_path";
Bugsnag.Start(config);

The default directory for this property is Android’s cache directory.

Persist User

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

var config = BugsnagSettingsObject.LoadConfiguration();
config.PersistUser = false;
Bugsnag.Start(config);

By default PersistUser is set to true.

If enabled then any user information set will be re-used until the user information is removed manually by calling Bugsnag.SetUser with null arguments.

Project Packages

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.

var config = BugsnagSettingsObject.LoadConfiguration();
config.ProjectPackages = new [] { "com.example.package" };
Bugsnag.Start(config);

By default this is set to the package you called initialized BugSnag from.

Redacted Keys

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.

var config = BugsnagSettingsObject.LoadConfiguration();
config.RedactedKeys = new List<Regex> 
{ 
  new Regex("credit_card_number"),
  new Regex(@".*_token", RegexOptions.IgnoreCase)
};
Bugsnag.Start(config);

Release Stage

Allows you to distinguish between errors that happen in different stages of the application release process (development, production, etc).

var config = BugsnagSettingsObject.LoadConfiguration();
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 Enabled Release Stages configuration option.

Report Exception Logs As Handled

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, macOS and Android native crash handlers are reported as unhandled. To report both Exception-level log events from Unity and native crashes from iOS, macOS and Android as unhandled events, set this property to false:

var config = BugsnagSettingsObject.LoadConfiguration();
config.ReportExceptionLogsAsHandled = false;
Bugsnag.Start(config);

Seconds Per Unique Log

Prevents frequent duplicate events being sent from Unity Logger messages.

var config = BugsnagSettingsObject.LoadConfiguration();
config.SecondsPerUniqueLog = 10;
Bugsnag.Start(config);

This defaults to 5, meaning that if the same message is received within 5 seconds it is not sent to your BugSnag dashboard.

Send Launch Crashes Synchronously

Determines whether launch crashes should be sent synchronously whilst BugSnag starts.

If this option is enabled and the previous run terminated due to a crash during app launch, BugSnag will block the calling thread when it starts for up to 2 seconds while the crash report is sent.

This behavior is enabled by default.

var config = BugsnagSettingsObject.LoadConfiguration();
config.SendLaunchCrashesSynchronously = false;
Bugsnag.Start(config);

Send Threads

Controls whether we should capture and serialize the state of all threads at the time of an exception.

var config = BugsnagSettingsObject.LoadConfiguration();
config.SendThreads = ThreadSendPolicy.UNHANDLED_ONLY;
Bugsnag.Start(config);

By default this option is set to ThreadSendPolicy.ALWAYS. This can be set to ThreadSendPolicy.NEVER to disable or ThreadSendPolicy.UNHANDLED_ONLY to only do so for unhandled errors.

Start Automatically

Automatically start BugSnag recording events and sessions when the game is launched, provided an API key is specified in the BugSnag Configuration window in the Unity Editor. This setting is enabled by default.

User

Set global user data that you want to send with all captured events – see Adding user data for more information.

var config = BugsnagSettingsObject.LoadConfiguration();
config.SetUser("3", "bugs.nag@bugsnag.com", "Bugs Nag");
Bugsnag.Start(config);

Telemetry

Internal Errors

Internal errors are sent when an error is detected within BugSnag, for example when a crash report cannot be processed.

To prevent these from being sent:

var config = BugsnagSettingsObject.LoadConfiguration();
config.Telemetry.Remove(TelemetryType.InternalErrors);
Bugsnag.Start(config);

Usage

Usage telemetry helps us improve BugSnag by providing information on how you are configuring the SDK. We record:

• when your config differs from the defaults
• BugSnag functionality utilized

We collect only bools, ints and enums. We do not collect any information personal to you or your users. The information is sent as part of error events; there is no additional network call made.

To prevent this from being sent:

var config = BugsnagSettingsObject.LoadConfiguration();
config.Telemetry.Remove(TelemetryType.Usage);
Bugsnag.Start(config);

Version Code

We’ll automatically pull the versionCode field from your app manifest file. If you’d like to override this you can set this option manually.

var config = BugsnagSettingsObject.LoadConfiguration();
config.VersionCode = 123;
Bugsnag.Start(config);