Upgrading Guide

Upgrade from 5.x to 6.x

This version contains several breaking changes.

Key points

redactedKeys and discardClasses are now matched as a Pattern instead of String
ThreadType has been removed in favour of ErrorType
Thread.id is now a String instead of an int
Configuration.launchCrashThresholdMs has been renamed Configuration.launchDurationMillis
The legacy bugsnag-android-ndk module has been removed in favor of bugsnag-plugin-android-ndk
Change to make foreground tracking based on Activity tracking, to match the ProcessLifecycleOwner, potentially affecting Application Stability scores (see below)
Configuration.persistUser now defaults to true
Generation of a deterministic build ID from .dex files to avoid the need for UUID generation
API key validation has moved to Bugsnag.start, instead of when the Configuration is created

More detail on these changes is described below:

`redactedKeys` & `discardClasses`

The properties / accessors for redacted keys and discard classes remain the same, but the type has been changed from String to Pattern to allow for more flexible matches (matching is done with Pattern.matches).

To retain the same behavior as v5.X replace:

configuration.redactedKeys = setOf("password", "secret")

with

configuration.redactedKeys = setOf(
    Pattern.compile(".*password.*"),
    Pattern.compile(".*secret.*"),
)

`ThreadType` removal

The ThreadType enum has been removed in favour of the existing ErrorType enum (this follows the same pattern as our other SDKs). Simply replace any references to ThreadType with ErrorType, the constant values remain the same:

Bugsnag.addOnError { event ->
    event.threads.first().type = ErrorType.UNKNOWN
    return@addOnError true
}

Thread ID change in type

The ID of a thread is now reported as a string, rather than an integer, for consistency with our other SDKs. If it is referenced in any error callback, it should be amended accordingly:

Bugsnag.addOnError { event ->
    if (event.threads.first().id == "0")
    ...
}

Rename of the `launchCrashThresholdMs` configuration option

Configuration.launchCrashThresholdMs (and equivalent manifest entry LAUNCH_CRASH_THRESHOLD_MS) has been renamed for consistency with other SDKs and was marked as deprecated in v5.x. Use Configuration.launchDurationMillis (LAUNCH_DURATION_MILLIS) as a direct equivalent in v6.x – see our online docs.

Rename of `bugsnag-android-ndk`

The legacy bugsnag-android-ndk module has been removed in favor of bugsnag-plugin-android-ndk. This won't affect most build setups but if your project references this library explicitly it will need to be updated to the new name.

Change in app foreground detection

Before v6.x, the app.inForeground flag was set to true whenever the app process has an importance of "foreground service" or greater (note: lower importance = higher priority). This will include any apps that are actively running in the background but include a foreground notification – known as Foreground Services. For example, fitness apps that are actively tracking; or music players when their controls are visible to the user.

As of v6.x, the Activity tracking has changed to exclude these scenarios. In other words, if app.inForeground on an event is true then the user has the app itself open and is engaged with it either in full screen or split-screen. This better aligns with the behavior of the ProcessLifecycleOwner and the BugSnag Performance SDK.

Foreground tracking is also used to determine when there's an active session, for the purposes of calculating a Stability score. Apps that run as a Foreground Service may therefore see fewer sessions created and also, if crashes occur when the app is in this state, they won't count towards a score. This means that your Stability score may change after migrating to v6.x.

Change of `persistUser` configuration option default value

The persistUser configuration option now defaults to true meaning that any stored user information will be persisted to file between launches of the app and used in future events until it is explicitly cleared. If you don't want this information to be stored, set the configuration option to false.

Deterministic build UUID

The SDK can now generate a unique identifier for your build, derived from your .dex files, in order to match your bytecode to the appropriate mapping.txt file during symbolication of a crash event on the BugSnag dashboard, if there are more than one build for a given version code (e.g. development and staging builds).

The BUILD_UUID from the manifest is still used if provided – usually by the BugSnag Android Gradle Plugin – therefore no changes are necessary for most build setups. However if you are an On Premise customer using versions before v3.2307.0 (single machine) and v5.2307.0 (clustered) and do not use our Gradle plugin for your builds, you may need opt-out of this behavior by setting BUILD_UUID to a blank (empty) string value:

<meta-data android:name="com.bugsnag.android.BUILD_UUID" android:value="" />

Alternatively ensure that this value is populated with a unique value and is included in your mapping upload API call as buildUUID.

API key validation on start

The presence and format of your API key has moved to Bugsnag.start, instead of when the Configuration is created. This means that Bugsnag.start will now fail with an exception if no valid-looking API key is provided.

Upgrade from 4.x to 5.x

This version contains many breaking changes. It is part of an effort to unify our notifier libraries across platforms, making the user interface more consistent, and implementations better on multi-layered environments where multiple Bugsnag libraries need to work together (such as React Native).

Key points

Bugsnag.init has been renamed to Bugsnag.start.
The configuration options available in the AndroidManifest.xml have been expanded and some have been renamed
ANR and NDK crash detection have now been enabled by default. The types of error that Bugsnag detects can be configured using the enabledErrorTypes configuration option.
The BeforeNotify and BeforeSend callbacks have been simplified to an OnErrorCallback that provides access to the data being sent to your dashboard.

More details of these changes can be found below and full documentation is available online at: https://docs.bugsnag.com/platforms/android.

Bugsnag client

Bugsnag.init has been renamed to Bugsnag.start.

You should use the static Bugsnag interface rather than instantiating Client directly.

Many of the previous methods on Bugsnag should now be called on Configuration (or added to the AndroidManifest.xml) instead.

The full list of altered methods and their intended replacements can be found below:

v4.x API	v5.x API
`Client#Client(Context, String, boolean)`	`Bugsnag#start(Context, Configuration)`
`Client#addToTab` or `Bugsnag#addToTab`	`Configuration#addMetadata` or `Bugsnag#addMetadata(String, String, Object)`
`Client#beforeNotify` or `Bugsnag#beforeNotify`	`Configuration#addOnError` or `Bugsnag#addOnError`
`Client#beforeRecordBreadcrumb` or `Bugsnag#beforeRecordBreadcrumb`	`Configuration#addOnBreadcrumb` or `Bugsnag#addOnBreadcrumb`
`Client#clearBreadcrumbs` or `Bugsnag#clearBreadcrumbs`	`Configuration#setMaxBreadcrumbs` or `Bugsnag#addOnBreadcrumb`
`Client#clearTab` or `Bugsnag#clearTab`	`Configuration#clearMetadata` or `Bugsnag#clearMetadata(String)`
`Client#clearUser` or `Bugsnag#clearUser`	`Configuration#setUser` or `Bugsnag#setUser`
`Client#disableExceptionHandler` or `Bugsnag#disableExceptionHandler`	`Configuration#setAutoDetectErrors` or `Configuration#setEnabledErrorTypes`
`Client#enableExceptionHandler` or `Bugsnag#enableExceptionHandler`	`Configuration#setAutoDetectErrors` or `Configuration#setEnabledErrorTypes`
`Client#getConfig`	Method removed as `Configuration` is now considered immutable after starting `Bugsnag`.
`Client#getMetaData` or `Bugsnag#getMetaData`	`Configuration#getMetadata` or `Bugsnag#getMetadata`
`Client#init(Context)` or `Bugsnag#init(Context)`	`Bugsnag#start(Context)`
`Client#init(Context, Configuration)` or `Bugsnag#init(Context, Configuration)`	`Bugsnag#start(Context, Configuration)`
`Client#init(Context, String)` or `Bugsnag#init(Context, String)`	`Bugsnag#start(Context, String)`
`Client#init(Context, String, boolean)` or `Bugsnag#init(Context, String, boolean)`	`Bugsnag#start(Context, Configuration)`
`Client#leaveBreadcrumb(String, BreadcrumbType, Map<String,String>)` or `Bugsnag#leaveBreadcrumb(String, BreadcrumbType, Map<String,String>)`	`Bugsnag#leaveBreadcrumb(String, BreadcrumbType, Map<String,Object>)`
`Client#notify(String, String, StackTraceElement[], Callback)` or `Bugsnag#notify(String, String, StackTraceElement[], Callback)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notify(String, String, StackTraceElement[], Severity, MetaData)` or `Bugsnag#notify(String, String, StackTraceElement[], Severity, MetaData)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notify(String, String, String, StackTraceElement[], Severity, MetaData)` or `Bugsnag#notify(String, String, String, StackTraceElement[], Severity, MetaData)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notify(Throwable, Callback)` or `Bugsnag#notify(Throwable, Callback)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notify(Throwable, MetaData)` or `Bugsnag#notify(Throwable, MetaData)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notify(Throwable, Severity)` or `Bugsnag#notify(Throwable, Severity)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notify(Throwable, Severity, MetaData)` or `Bugsnag#notify(Throwable, Severity, MetaData)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notifyBlocking(String, String, StackTraceElement[], Callback)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notifyBlocking(String, String, StackTraceElement[], Severity, MetaData)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notifyBlocking(String, String, String, StackTraceElement[], Severity, MetaData)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notifyBlocking(Throwable)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notifyBlocking(Throwable, Callback)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notifyBlocking(Throwable, MetaData)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notifyBlocking(Throwable, Severity)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#notifyBlocking(Throwable, Severity, MetaData)`	`Bugsnag#notify(Throwable, OnErrorCallback)`
`Client#setAppVersion` or `Bugsnag#setAppVersion`	`Configuration#setAppVersion`
`Client#setAutoCaptureSessions` or `Bugsnag#setAutoCaptureSessions`	`Configuration#setAutoTrackSessions`
`Client#setBuildUUID` or `Bugsnag#setBuildUUID`	Method removed. Set as an AndroidManifest element instead using `com.bugsnag.android.BUILD_UUID` as the key
`Client#setEndpoint` or `Bugsnag#setEndpoint`	`Configuration#setEndpoints`
`Client#setErrorReportApiClient` or `Bugsnag#setErrorReportApiClient`	`Configuration#setDelivery`
`Client#setFilters` or `Bugsnag#setFilters`	`Configuration#setRedactedKeys`
`Client#setIgnoreClasses` or `Bugsnag#setIgnoreClasses`	`Configuration#setDiscardClasses`
`Client#setLoggingEnabled` or `Bugsnag#setLoggingEnabled`	`Configuration#setLogger`
`Client#setMaxBreadcrumbs` or `Bugsnag#setMaxBreadcrumbs`	`Configuration#setMaxBreadcrumbs`
`Client#setMetaData` or `Bugsnag#setMetaData`	`Configuration#addMetadata` or `Bugsnag#addMetadata(String, String, Object)`
`Client#setNotifyReleaseStages` or `Bugsnag#setNotifyReleaseStages`	`Configuration#setEnabledReleaseStages`
`Client#setProjectPackages` or `Bugsnag#setProjectPackages`	`Configuration#setProjectPackages`
`Client#setReleaseStage` or `Bugsnag#setReleaseStage`	`Configuration#setReleaseStage`
`Client#setSendThreads` or `Bugsnag#setSendThreads`	`Configuration#setSendThreads`
`Client#setSessionTrackingApiClient` or `Bugsnag#setSessionTrackingApiClient`	`Configuration#setDelivery`
`Client#setUserEmail` or `Bugsnag#setUserEmail`	`Configuration#setUser` or `Bugsnag#setUser`
`Client#setUserId` or `Bugsnag#setUserId`	`Configuration#setUser` or `Bugsnag#setUser`
`Client#setUserName` or `Bugsnag#setUserName`	`Configuration#setUser` or `Bugsnag#setUser`
`Client#stopSession` or `Bugsnag#stopSession`	`Bugsnag#pauseSession`

See the online documentation for more information.

Configuration

Many more configuration options can be set via your AndroidManifest.xml, for example:

<meta-data
  android:name="com.bugsnag.android.MAX_BREADCRUMBS"
  android:value="35" />

Bugsnag can then be initialized by simply calling Bugsnag.start.

You can also create a Configuration object yourself using Configuration.load to read the app manifest and then provide further configuration in code:

val config = Configuration.load(this)
config.maxBreadcrumbs = 35
Bugsnag.start(this, config)

Altering values on Configuration after calling Bugsnag.start now has no effect. You should specify any non-default behavior up-front before Bugsnag is started.

Several methods on Configuration have been renamed for greater API consistency. A full list is shown below:

v4.x API	v5.x API
`Configuration#beforeSend`	`Configuration#addOnError`
`Configuration#getErrorApiHeaders`	`Configuration#setDelivery`
`Configuration#getSessionApiHeaders`	`Configuration#setDelivery`
`Configuration#setAutomaticallyCollectBreadcrumbs`	`Configuration#setEnabledBreadcrumbTypes`
`Configuration#setAnrThresholdMs`	Method no longer required.
`Configuration#setAutoCaptureSessions`	`Configuration#setAutoTrackSessions`
`Configuration#setBuildUUID`	Method removed. Set as an AndroidManifest element instead using `com.bugsnag.android.BUILD_UUID` as the key
`Configuration#setDetectAnrs`	`Configuration#setAutoDetectErrors` or `Configuration#setEnabledErrorTypes`
`Configuration#setDetectNdkCrashes`	`Configuration#setAutoDetectErrors` or `Configuration#setEnabledErrorTypes`
`Configuration#setEnableExceptionHandler`	`Configuration#setAutoDetectErrors` or `Configuration#setEnabledErrorTypes`
`Configuration#setEndpoint`	`Configuration#setEndpoints`
`Configuration#setFilters`	`Configuration#setRedactedKeys`
`Configuration#setMetaData`	`Configuration#addMetadata(String, String, Object)`
`Configuration#setNotifierType`	Method removed as end-users should not alter this value.
`Configuration#setNotifyReleaseStages`	`Configuration#setEnabledReleaseStages`
`Configuration#setPersistUserBetweenSessions`	`Configuration#setPersistUser`
`Configuration#setSessionEndpoint`	`Configuration#setEndpoints`

See the online documentation for more information.

BeforeNotify/BeforeSend/Callback

These three callbacks have been superseded and replaced by OnError, a single callback which runs immediately after an Event has been captured. This can run globally on all events, or on an individual event.

val config = Configuration.load(this)
config.addOnError { event ->
    event.context = "Some Custom context"
    true
})
Bugsnag.start(this, config)

// run on handled error
Bugsnag.notify(myThrowable) { event ->
    event.context = "My Unique context"
    true
}

If you use the NDK, implement the native on_error callback which will be run for fatal C/C++ errors only. See below

See the online documentation for more information.

Error -> Event

Error has been replaced by Event, which represents the payload that will be sent to Bugsnag's API. A large number of new accessors have been added to the Event class to allow for greater customization of error reports in callbacks.

Several existing methods have been renamed, a full list of which is shown below:

v4.x API	v5.x API
`Error#addToTab`	`Event#addMetadata(String, String, Object)`
`Error#clearTab`	`Event#clearMetadata(String)`
`Error#getDeviceData`	`Event#getDevice`
`Error#getException`	`Event#getOriginalError`
`Error#getHandledState`	`Event#isUnhandled`
`Error#getMetaData`	`Event#getMetadata(String)`
`Error#setDeviceId`	`Event#getDevice`
`Error#setExceptionMessage`	`Event#setErrors`
`Error#setExceptionName`	`Event#setErrors`
`Error#setMetaData`	`Event#addMetadata(String, String, Object)`
`Error#setUserEmail`	`Event#setUser(String, String, String)`
`Error#setUserId`	`Event#setUser(String, String, String)`
`Error#setUserName`	`Event#setUser(String, String, String)`

See the online documentation for more information.

Breadcrumbs

Breadcrumbs now contain a message rather than a name and the callback has been renamed for consistency:

v4.x API	v5.x API
`Breadcrumb#getName`	`Breadcrumb#getMessage`
`BeforeRecordBreadcrumb#shouldRecord`	`OnBreadcrumbCallback#onBreadcrumb`

See the online documentation for more information.

Session payload & callbacks

SessionTrackingPayload is now called SessionPayload. It is now possible to redact the app and device information captured on sessions via an OnSessionCallback.

See the online documentation for more information.

Delivery

The signature for providing a custom delivery mechanism has changed:

v4.x API	v5.x API
`Delivery#deliver(Report, Configuration)`	`Delivery#deliver(SessionPayload, DeliveryParams)`
`Delivery#deliver(SessionTrackingPayload, Configuration)`	`Delivery#deliver(Report, DeliveryParams)`

See the online documentation for more information.

Removed from public API

v4.x API	v5.x API
`MetaData`	No longer publicly accessible, and should be added via the `Bugsnag` interface or via an `OnError` callback.
`Report`	This class is no longer publicly accessible as end-users should not need to set its values. The `Event` class should now be used to alter the details of an error report.
`ErrorReportApiClient`	Previously deprecated, use `Delivery` interface instead.
`SessionTrackingApiClient`	Previously deprecated, use `Delivery` interface instead.
`BadResponseException`	Previously deprecated, use `Delivery` interface instead.
`DeliveryFailureException`	Previously deprecated, use `Delivery` interface instead.
`NetworkException`	Previously deprecated, use `Delivery` interface instead.
`Notifier`	This class is no longer publicly accessible as end-users should not need to set its values.
`EventReceiver`	This class is no longer publicly accessible as end-users should not need to set its values.
`BugsnagException`	This class is no longer required - you should use your own `Throwable` instead.

NDK changes

Breaking changes

The report.h header has been renamed to event.h
bugsnag_init() has been renamed to bugsnag_start()
bsg_severity_t has been renamed to bugsnag_severity
bsg_breadcrumb_t has been renamed to bugsnag_breadcrumb_type

New functionality

Native events can now be customized by adding an on_error callback. This allows you to amend the data that will be sent to your Bugsnag dashboard for fatal NDK crashes.

bool custom_on_error_callback(void *event) {
    bugsnag_event_set_severity(event, BSG_SEVERITY_WARN);
    // ...
}
bugsnag_add_on_error(&custom_on_error_callback);

Most of the fields in the Event class in the JVM are available in this callback using a set of functions (see event.h) that take the event pointer argument and either return data from the event or allow you to set it. Full examples are given in the Event class documentation.

Care must be taken to ensure that the callback function provided is async-signal safe. The code will be executed in an asynchronous signal handler and so must not call any functions that are not Async-Signal-Safe. Further information can be found here.

Metadata changes

Removed packageName from the app metadata tab, as the field is duplicated by app.id
Removed versionName from the app metadata tab, as the field is duplicated by app.version and this has been known to cause confusion amongst users in the past

Upgrade bugsnag-android-ndk from 1.x to 4.x

This is a backwards-compatible release. Update the version number to 4.+ to upgrade:

dependencies {
  implementation 'com.bugsnag:bugsnag-android-ndk:4.+'
}

Upgrade from 3.X to 4.X

Increase the minSdkVersion to 14 or higher in your app's build.gradle file.
The default method for identifying devices and users is now captured and persisted through a per-install generated UUID, replacing use of Settings.Secure.ANDROID_ID. As a result, existing errors on your Bugsnag dashboard may see doubled user counts if they continue to occur after upgrading the library. If this is an issue, a workaround would be to assign the user identifier using the previous value.
```
String androidId = Settings.Secure.getString(cr, Settings.Secure.ANDROID_ID);
Bugsnag.setUserId(androidId)
```
For more information and discussion see #83

Upgrade from 2.0 to 3.0

Change any Bugsnag.register calls to Bugsnag.init:

// Old
Bugsnag.register(Context, "api-key");

// New
Bugsnag.init(Context, "api-key");

Severity is now an Enum, so please update any references to severity in your app:

// Old
Bugsnag.notify(new RuntimeException("oops"), "error");

// New
import com.bugsnag.android.Severity;
Bugsnag.notify(new RuntimeException("oops"), Severity.ERROR);

"Top Activity" tracking is now automatically handled when you add the GET_TASKS permission to your AndroidManifest.xml, so you should no longer have your app's Activitys inherit from BugsnagActivity:
```
// Old
class MyActivity extends BugsnagActivity {}

// New
class MyActivity extends Activity {}
```

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Upgrading Guide

Upgrade from 5.x to 6.x

Key points

`redactedKeys` & `discardClasses`

`ThreadType` removal

Thread ID change in type

Rename of the `launchCrashThresholdMs` configuration option

Rename of `bugsnag-android-ndk`

Change in app foreground detection

Change of `persistUser` configuration option default value

Deterministic build UUID

API key validation on start

Upgrade from 4.x to 5.x

Key points

Bugsnag client

Configuration

BeforeNotify/BeforeSend/Callback

Error -> Event

Breadcrumbs

Session payload & callbacks

Delivery

Removed from public API

NDK changes

Breaking changes

New functionality

Metadata changes

Upgrade bugsnag-android-ndk from 1.x to 4.x

Upgrade from 3.X to 4.X

Upgrade from 2.0 to 3.0

FilesExpand file tree

UPGRADING.md

Latest commit

History

UPGRADING.md

File metadata and controls

Upgrading Guide

Upgrade from 5.x to 6.x

Key points

redactedKeys & discardClasses

ThreadType removal

Thread ID change in type

Rename of the launchCrashThresholdMs configuration option

Rename of bugsnag-android-ndk

Change in app foreground detection

Change of persistUser configuration option default value

Deterministic build UUID

API key validation on start

Upgrade from 4.x to 5.x

Key points

Bugsnag client

Configuration

BeforeNotify/BeforeSend/Callback

Error -> Event

Breadcrumbs

Session payload & callbacks

Delivery

Removed from public API

NDK changes

Breaking changes

New functionality

Metadata changes

Upgrade bugsnag-android-ndk from 1.x to 4.x

Upgrade from 3.X to 4.X

Upgrade from 2.0 to 3.0

`redactedKeys` & `discardClasses`

`ThreadType` removal

Rename of the `launchCrashThresholdMs` configuration option

Rename of `bugsnag-android-ndk`

Change of `persistUser` configuration option default value