Configuration options

The Bugsnag client object has several properties which can be set to customize the content of error reports and how the reports are sent.

Specifying options

Most configuration options can be specified in two ways; By initialising Bugsnag and then calling the relevant set method

Bugsnag.init(this)
Bugsnag.setAppVersion("1.0.0-alpha")

or by setting up a configuration object and passing it into Bugsnag init

val config = Configuration("your-api-key-here")
config.setAppVersion("1.0.0-alpha")
Bugsnag.init(this, config)

Some of the options must be passed in using a configuration object because they affect the way that Bugsnag is initialized.

Build Variants

Bugsnag can be set up to use different configuration values for different build variants, by using the following manifest placeholders in your app’s build.gradle script.

android {
    defaultConfig {
        manifestPlaceholders = [
            // omit any of the following placeholders to use the default values
            bugsnagApiKey: "<api-key>",
            bugsnagBuildUUID: "<build-uuid>",
            bugsnagAppVersion: "1.0.0",
            bugsnagEndpoint: "https://notify.bugsnag.com",
            bugsnagReleaseStage: "<release-stage>",
            bugsnagSendThreads: true,
            bugsnagEnableExceptionHandler: true,
            bugsnagPersistUserBetweenSessions: false
        ]
    }
    productFlavors {
        free {
            manifestPlaceholders = [
                // override defaultConfig values here
            ]
        }
    }
}

For all the values you wish to configure, provide a meta-data element at the bottom of your manifest file.

<application>
    <meta-data android:name="com.bugsnag.android.API_KEY" android:value="${bugsnagApiKey}"/>
    <meta-data android:name="com.bugsnag.android.BUILD_UUID" android:value="${bugsnagBuildUUID}"/>
    <meta-data android:name="com.bugsnag.android.APP_VERSION" android:value="${bugsnagAppVersion}"/>
    <meta-data android:name="com.bugsnag.android.ENDPOINT" android:value="${bugsnagEndpoint}"/>
    <meta-data android:name="com.bugsnag.android.RELEASE_STAGE" android:value="${bugsnagReleaseStage}"/>
    <meta-data android:name="com.bugsnag.android.SEND_THREADS" android:value="${bugsnagSendThreads}"/>
    <meta-data android:name="com.bugsnag.android.ENABLE_EXCEPTION_HANDLER" android:value="${bugsnagEnableExceptionHandler}"/>
    <meta-data android:name="com.bugsnag.android.PERSIST_USER_BETWEEN_SESSIONS" android:value="${bugsnagPersistUserBetweenSessions}"/>
</application>

Finally, initialize Bugsnag in your Application class.

Bugsnag.init(this);

beforeNotify

Add a callback to be executed code before every notification to Bugsnag.

You can use this to add or modify information attached to an error before it is sent to your dashboard. You can also return false from any callback to halt execution.

Bugsnag.beforeNotify {
    it.severity = Severity.INFO
    true
}

See the customizing error reports) reference for more information.

disableExceptionHandler

By default, Bugsnag reports unhandled exceptions in your application automatically. To disable this behavior, call disableExceptionHandler:

Bugsnag.disableExceptionHandler()

setAppVersion

We’ll automatically pull your app version from the versionName field in your AndroidManifest.xml file. If you’d like to override this you can call setAppVersion:

Bugsnag.setAppVersion("1.0.0-alpha")

Note: Bugsnag uses Semantic Versioning for app version sorting and filtering on the Bugsnag dashboard.

setContext

Bugsnag uses the concept of “contexts” to help display and group your errors. Contexts represent what was happening in your application at the time an error occurs. In an android app, it is useful to set this to be your currently active Activity.

If you enable the GET_TASKS permission, then this is set automatically for you. If you would like to set the bugsnag context manually, you can call setContext:

Bugsnag.setContext("MyActivity")

setEndpoint

Set the endpoint to which error reports are sent. By default, reports are sent to https://notify.bugsnag.com endpoint, but this option should be overridden if you are using Bugsnag Enterprise, to point to your own Bugsnag endpoint:

val config = Configuration("your-api-key-here")
config.setEndpoint("https://bugsnag.internal.example.com")
Bugsnag.init(this, config)

setErrorReportApiClient

Sets the ErrorReportApiClient implementation used to make network calls to the Error Reporting API. This may be useful if you have requirements such as certificate pinning, which are not supported by the default implementation.

Bugsnag.setErrorReportApiClient(new CertPinnedApiClient());

Implementations of ErrorReportApiClient must throw a BadResponseException if the response code is not 200, and a NetworkException if the request could not be completed. The request body must match the structure specified in the Error Reporting API documentation.

An example of a custom client which uses certificate pinning is provided below.

/**
 * A custom API client which uses Square's OkHttp3 Library to pin certificates.
 */
class CertPinnedApiClient implements ErrorReportApiClient {
    OkHttpClient okHttpClient;

    CertPinnedApiClient() {
        // The public key hash(es) for your cert can be found by following OkHttp3 instructions:
        // https://square.github.io/okhttp/3.x/okhttp/okhttp3/CertificatePinner.html
        CertificatePinner certificatePinner = new CertificatePinner.Builder()
            .add("mywebsite.com", "sha256/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=")
            .build();

        okHttpClient = new OkHttpClient.Builder()
            .certificatePinner(certificatePinner)
            .build();
    }

    String getReportJson(Report report) {
        try {
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            JsonStream jsonStream = new JsonStream(new PrintWriter(baos));
            report.toStream(jsonStream);
            jsonStream.flush();
            return baos.toString("UTF-8");
        } catch (IOException e) {
            throw new RuntimeException("Failed to generate request", e);
        }
    }

    @Override
    public void postReport(String urlString, Report report)
        throws NetworkException, BadResponseException {
        try {
            Request request = new Request.Builder()
                .url("https://notify.bugsnag.com")
                .post(RequestBody.create(MediaType.parse("application/json"), getReportJson(report)))
                .build();
            Response response = okHttpClient.newCall(request).execute();

            if (response.code() != 200) {
                throw new BadResponseException("", response.code());
            }
        } catch (IOException e) {
            throw new NetworkException("Network Call failed", e);
        }
    }
}

setFilters

Sets which values should be removed from any MetaData objects before sending them to Bugsnag. Use this if you want to ensure you don’t send sensitive data such as passwords, and credit card numbers to our servers. Any keys which contain these strings will be filtered.

Bugsnag.setFilters("password", "credit_card_number")

By default, filters is set to "password"

setIgnoreClasses

Sets for which exception classes we should not send exceptions to Bugsnag.

Bugsnag.setIgnoreClasses("java.net.UnknownHostException", "com.example.Custom")

setNotifyReleaseStages

By default, Bugsnag will be notified of exceptions that happen in any releaseStage. If you would like to change which release stages notify Bugsnag of exceptions you can call setNotifyReleaseStages:

Bugsnag.setNotifyReleaseStages("production", "development", "testing")

setPersistUserBetweenSessions

Set whether or not Bugsnag should persist user information between application sessions. if set then any user information set will be re-used until Bugsnag.clearUser() is called

Configuration config = new Configuration("your-api-key-here");
config.setPersistUserBetweenSessions(true);
Bugsnag.init(this, config);

setProjectPackages

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.

Bugsnag.setProjectPackages("com.company.package1", "com.company.package2")

By default, projectPackages is set to be the package you called Bugsnag.init from.

setReleaseStage

If you would like to distinguish between errors that happen in different stages of the application release process (development, production, etc) you can set the releaseStage that is reported to Bugsnag.

Bugsnag.setReleaseStage("testing")

If you are running a debug build, we’ll automatically set this to “development”, otherwise it is set to “production”.

setSendThreads

Sets if we should collect and send thread state along with errors.

By default sendThreads is set to true.

Bugsnag.setSendThreads(false)

setUser

Bugsnag helps you understand how many of your users are affected by each error. In order to do this, we need to send along user information with every exception.

If you would like to enable this, set the user. You can set the user id, which is usually the unique id to represent that user across all your apps, the user’s email address and the user’s name:

Bugsnag.setUser("userId", "user@email.com", "User Name")

setPersistUserBetweenSessions

Set whether or not Bugsnag should persist user information between application sessions. if set then any user information set will be re-used until Bugsnag.clearUser() is called

val config = Configuration("your-api-key-here")
config.setPersistUserBetweenSessions(true)
Bugsnag.init(this, config)