Migration Guide

The required minimum Dart and Flutter versions are now 3.5.0 and 3.24.0 respectively. This change allows us to use safer APIs and better support for features such as Session Replay and WASM compilation.

  • The beforeScreenshot method has been replaced by beforeCaptureScreenshot.
  • Manual TTID implementation has been removed as the automatic TTID instrumentation has proven to be accurate enough so a manual one is not needed anymore.
  • LoadImagesListIntegration has been renamed to LoadNativeDebugImagesIntegration.
  • The enableTracing option has been removed. Use options.traceSampleRate or options.tracesSampler instead.
  • Both options.autoAppStart and setAppStartEnd have been removed. The App Start Instrumentation will now determine the end of app start and is enabled by default.
  • Usage of dart:html has been removed in favor of package:web. The SDK is now packaged with the package:web dependency for better interoperability with web APIs.
  • The beforeSendTransaction callback now has a Hint parameter.
  • The option attachScreenshotOnlyWhenResumed has been removed.
  • The segment field from SentryUser has been removed.

The old user feedback API has been removed and replaced by Sentry.captureFeedback.

Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically. Responses are now attached to the Hint object, which can be read in beforeSend/beforeSendTransaction callbacks via hint.response so you can manually attach the response to your event. Response bodies with a size greater than 0.15MB are not added to the hint object. Currently as of version 9.0.0, only the dio integration is supported.

Screenshots are now masked by default for privacy reasons. For example, text fields are automatically masked to prevent sensitive information from being leaked. Read the guide here for more information on how to customize the masking.

The default log level is now warning when debug = true. This can be adjusted by setting options.diagnosticLevel = SentryLevel.info in Sentry.init.

SDK data classes are now mutable which makes it easier to manipulate them. For backwards-compatibility, copyWith and clone can still be used but are officially deprecated.

Copied
// old
options.beforeSend = (event, hint) {
  event = event.copyWith(release: 'my-release');
  return event;
}

// new
options.beforeSend = (event, hint) {
  event.release = 'my-release';
  return event;
}

Native crash handling is now enabled by default for Flutter Desktop. Windows ARM64 uses breakpad and all other desktop platforms use crashpad. You can turn off this feature by setting the SENTRY_NATIVE_BACKEND environment variable to an empty string.

The interop with the Sentry Browser Javascript SDK is now enabled by default. During SentryFlutter.init the SDK will inject the CDN script into the HTML's head. This change allows us to utilize existing SDK functionality such as native JS Errors, add new features such as release health and makes it easier to develop features such as debug ids in the future.

If you initialize the native SDKs separately with options.autoInitializeNativeSdk = false you will also need to add the Sentry Browser Javascript SDK to your website's HTML head. Read this guide on how to install the SDK into your application via CDN bundles.

We have bumped the required Drift version to 2.24.0 and have changed the API on how to use the integration. Instead of a SentryQueryExecutor, Sentry now provides a SentryQueryInterceptor that you can use like so:

Copied
final executor = NativeDatabase.memory().interceptWith(
  SentryQueryInterceptor(databaseName: 'your_db_name')
);

For more information on how to use QueryInterceptor read the Drift documentation.

In addition to the changes introduced in sentry:

API changes:

  • Sentry's Flutter SDK version 7.0.0 and above requires Flutter 3.0.0.
  • sentry_dio, version 7.0.0 requires dio 5.0.0
  • The Sentry Cocoa SDK was upgraded to 8.0.0 which introduces breaking changes, see the migration guide.
  • The following fields have been removed from the SentryFlutterOptions class and replaced:
    • enableAutoPerformanceTracking replaced with enableAutoPerformanceTracing.
    • enableOutOfMemoryTracking replaced with enableWatchdogTerminationTracking.
    • anrTimeoutIntervalMillis replaced with anrTimeoutInterval.
    • autoSessionTrackingIntervalMillis replaced with autoSessionTrackingInterval.
  • The enableNdkScopeSync feature is now enabled by default.

The SDK already runs your init callback on an error handler, such as runZonedGuarded on Flutter versions prior to 3.3, or PlatformDispatcher.onError on Flutter versions 3.3 and higher, so that errors are automatically captured. No code changes are needed on your part.

There are no Flutter-specific breaking changes. However, there are some in sentry for Dart.

To build a Flutter app for Android, Kotlin 1.5.31 or higher is required. If your app uses a lower version, you will receive the following error message.

There are no Flutter specific breaking changes. However there are some in sentry for Dart.

You may remove android:extractNativeLibs="true" meta-data in the AndroidManifest file or android.bundle.enableUncompressedNativeLibs=false in the gradle.properties file if you're using the Android Native Development Kit. Sentry can now symbolicate events with the default value of extractNativeLibs and android.bundle.enableUncompressedNativeLibs.

A random generated installationId replaces Settings.Secure.ANDROID_ID, which has been removed. This may affect the number of unique users displayed on the the Issues page and Alerts. If you always set a custom user using Sentry.setUser(customUser), the behavior has not changed. While you don't have to make any update, if you want to maintain the old behavior, use the following code snippet. It makes use of the device_info_plus plugin:

Copied
import 'package:flutter/foundation.dart';
import 'package:device_info_plus/device_info_plus.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
  await SentryFlutter.init(
    (options) {
      options.dsn = 'https://examplePublicKey@o0.ingest.sentry.io/0';
      // revert to old behavior on Android
      if (defaultTargetPlatform == TargetPlatform.android && !kIsWeb) {
        options.addEventProcessor(addAndroidDeviceId);
      }
    },
    // Init your App.
    appRunner: () => runApp(MyApp()),
  );
}

FutureOr<SentryEvent?> addAndroidId(
  SentryEvent event, {
  Hint? hint,
}) async {
  var info = await DeviceInfoPlugin().androidInfo;
  var user = (event.user ?? SentryUser()).copyWith(id: info.androidId);

  return event.copyWith(
    user: user,
  );
}

In addition to the changes introduced in sentry:

  • SentryFlutterOptions.enableLifecycleBreadcrumbs was replaced with SentryFlutterOptions.enableAppLifecycleBreadcrumbs.
  • The Web Plugin Registrant import changed from import 'package:sentry_flutter/src/sentry_flutter_web.dart'; to import 'package:sentry_flutter/sentry_flutter_web.dart';
    • This change may lead to breaking changes. In most cases, however, this change won't lead to breaking changes since the referencing file is auto-generated.
Previous
SDK Overhead
Next
Migration Guide
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").