Migration Guide
Migrating from sentry-android 2.x
to sentry-android 3.x
Package changes
The package io.sentry.core
has been renamed to io.sentry
. To compile correctly, replace the strings on all the usages from io.sentry.core.
to io.sentry.
Other than that, the APIs didn't change. Release Heath sets by default. If you prefer not to track the health of your releases, disable it with:
<application>
<meta-data android:name="io.sentry.session-tracking.enable" android:value="false" />
</application>
Migrating from sentry-android 1.x
to sentry-android 2.x
With Sentry Android, we've updated the API to resemble the Unified API more closely. And now that the SDK isn't built on top of sentry-java
, Sentry Android has more Android-specific features.
If you want to upgrade from the previous version of the SDK, please check the following sections of changes that may need updating in your code.
Configuration
The file sentry.properties
used by the previous version of the SDK has been discontinued. Configurations for the new SDK are in AndroidManifest.xml
or directly in the code.
Example of the configuration in the Manifest:
<application>
<!-- Example of the Sentry DSN setting -->
<meta-data android:name="io.sentry.dsn" android:value="https://examplePublicKey@o0.ingest.sentry.io/0" />
</application>
If you want to set the configuration manually in the code, you need to initialize the SDK with SentryAndroid.init()
--- described in Installation --- in the same file as SentryAndroidOptions
, which holds configuration items.
Installation
The new SDK can initialize automatically, all you need to do is provide the DSN in your Manifest file, as shown in the previous example in Configuration.
Manual Installation
If you want to register any callback to filter and modify events and/or breadcrumbs, or if you want to provide the configuration values via code, you need to initialize the SDK using the SentryAndroid.init()
.
To initialize the SDK manually:
Disable the
auto-init
feature by providing the following line in the manifest:Copied<application> <meta-data android:name="io.sentry.auto-init" android:value="false" /> </application>
Initialize the SDK directly in your application:
CopiedSentryAndroid.init(context, options -> { options.setDsn("https://examplePublicKey@o0.ingest.sentry.io/0"); });
Releases
Please note that the new SDK will send with each event a release version in a different format than the previous SDK.
If you are using the GitHub or GitLab integrations, you need to do one of the following:
- Use the new format
- Set the release in your
AndroidManifest.xml
- Change your code as described in the configuration section
API
Set tag
Old:
Sentry.getContext().addTag("tagName", "tagValue");
New:
Sentry.setTag("tagName", "tagValue");
Capture custom exception
Old:
try {
int x = 1 / 0;
} catch (Exception e) {
Sentry.capture(e);
}
New:
try {
int x = 1 / 0;
} catch (Exception e) {
Sentry.captureException(e);
}
Capture a message
Old:
Sentry.capture("This is a test");
New:
Sentry.captureMessage("This is a test"); // SentryLevel.INFO by default
Sentry.captureMessage("This is a test", SentryLevel.WARNING); // or specific level
Breadcrumbs
Old:
Sentry.getContext().recordBreadcrumb(
new BreadcrumbBuilder().setMessage("User made an action").build()
);
New:
Sentry.addBreadcrumb("User made an action");
User
Old:
Sentry.getContext().setUser(
new UserBuilder().setEmail("hello@sentry.io").build()
);
New:
User user = new User();
user.setEmail("hello@sentry.io");
Sentry.setUser(user);
Set extra
Old:
Sentry.getContext().addExtra("extra", "thing");
New:
Sentry.setExtra("extra", "thing");
Sentry Gradle Plugin
Disable the autoProguardConfig
flag from the Sentry Gradle Plugin, sentry-android
>= v2.0 already does it automatically.
sentry {
autoProguardConfig false
}