Skip to content

Commit 53e74e2

Browse files
buenaflorbitsandfoxes
buenaflor
authored and
bitsandfoxes
committed
flutter: v8 to v9 migration (#13500)
Closes getsentry/sentry-dart#2699
1 parent 94135ab commit 53e74e2

File tree

2 files changed

+138
-0
lines changed

2 files changed

+138
-0
lines changed

‎docs/platforms/dart/common/migration/index.mdx

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,53 @@ sidebar_order: 8000
44
description: "Migrate between versions of Sentry's SDK for Dart."
55
---
66

7+
## Migrating from `sentry` `8.x` to `sentry` `9.x`
8+
9+
#### Dart version
10+
11+
The required minimium Dart version is now `3.5.0`.
12+
This change allows us to use safer APIs and better support for features such as WASM compilation.
13+
14+
#### API Removals and Renames
15+
16+
- `LoadImagesListIntegration` has been renamed to `LoadNativeDebugImagesIntegration`.
17+
- The `enableTracing` option has been removed. Use `options.traceSampleRate` or `options.tracesSampler` instead.
18+
- `BeforeSendTransactionCallback` now has a `Hint` parameter.
19+
- 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.
20+
- The `segment` field from `SentryUser` has been removed.
21+
- The old user feedback API has been removed and replaced by `Sentry.captureFeedback`.
22+
23+
#### Logging
24+
25+
The default log level is now `warning` when `debug = true`.
26+
This can be adjusted by setting `options.diagnosticLevel = SentryLevel.info` in `Sentry.init`.
27+
28+
#### SDK Data Classes
29+
30+
SDK data classes are now mutable which makes it easier to manipulate them.
31+
For backwards-compatibility, `copyWith` and `clone` can still be used but are officially deprecated.
32+
33+
```dart
34+
// old
35+
options.beforeSend = (event, hint) {
36+
event = event.copyWith(release: 'my-release')
37+
return event
38+
}
39+
40+
// new
41+
options.beforeSend = (event, hint) {
42+
event.release = 'my-release'
43+
return event
44+
}
45+
```
46+
47+
#### Response Body Handling
48+
49+
Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically.
50+
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.
51+
Response bodies with a size greater than 0.15MB are not added to the hint object.
52+
Currently as of version `9.0.0`, only the `dio` integration is supported.
53+
754
## Migrating From `sentry` `6.18.x` to `sentry` `7.0.0`
855

956
API changes:

‎docs/platforms/dart/guides/flutter/migration.mdx

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,97 @@ title: Migration Guide
33
sidebar_order: 8000
44
---
55

6+
## Migrating from `sentry_flutter` `8.x` to `sentry_flutter` `9.x`
7+
8+
### General
9+
10+
#### Dart and Flutter versions
11+
12+
The required minimum Dart and Flutter versions are now `3.5.0` and `3.24.0` respectively.
13+
This change allows us to use safer APIs and better support for features such as Session Replay and WASM compilation.
14+
15+
#### Android API version
16+
17+
The required minimum Android API is now `21`.
18+
19+
#### API Removals and Renames
20+
21+
- The `beforeScreenshot` method has been replaced by `beforeCaptureScreenshot`.
22+
- 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.
23+
- `LoadImagesListIntegration` has been renamed to `LoadNativeDebugImagesIntegration`.
24+
- The `enableTracing` option has been removed. Use `options.traceSampleRate` or `options.tracesSampler` instead.
25+
- Both `options.autoAppStart` and `setAppStartEnd` have been removed. The [App Start Instrumentation](/platforms/dart/guides/flutter/integrations/app-start-instrumentation/) will now determine the end of app start and is enabled by default.
26+
- 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.
27+
- The `beforeSendTransaction` callback now has a `Hint` parameter.
28+
- The option `attachScreenshotOnlyWhenResumed` has been removed.
29+
- The `segment` field from `SentryUser` has been removed.
30+
- The old user feedback API has been removed and replaced by `Sentry.captureFeedback`.
31+
32+
#### Response Body Handling
33+
34+
Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically.
35+
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.
36+
Response bodies with a size greater than 0.15MB are not added to the hint object.
37+
Currently as of version `9.0.0`, only the `dio` integration is supported.
38+
39+
#### Screenshots
40+
41+
Screenshots are now masked by default for privacy reasons.
42+
For example, text fields are automatically masked to prevent sensitive information from being leaked.
43+
Read the guide [here](/platforms/dart/guides/flutter/enriching-events/screenshots/#redact-screenshots-via-masking) for more information on how to customize the masking.
44+
45+
#### Logging
46+
47+
The default log level is now `warning` when `debug = true`.
48+
This can be adjusted by setting `options.diagnosticLevel = SentryLevel.info` in `SentryFlutter.init`.
49+
50+
#### SDK Data Classes
51+
52+
SDK data classes are now mutable which makes it easier to manipulate them.
53+
For backwards-compatibility, `copyWith` and `clone` can still be used but are officially deprecated.
54+
55+
```dart
56+
// old
57+
options.beforeSend = (event, hint) {
58+
event = event.copyWith(release: 'my-release');
59+
return event;
60+
}
61+
62+
// new
63+
options.beforeSend = (event, hint) {
64+
event.release = 'my-release';
65+
return event;
66+
}
67+
```
68+
69+
### Flutter Desktop
70+
71+
Native crash handling is now enabled by default for Flutter Desktop.
72+
Windows ARM64 uses [breakpad](https://chromium.googlesource.com/breakpad/breakpad) and all other desktop platforms use [crashpad](https://chromium.googlesource.com/crashpad/crashpad).
73+
You can disable this feature by setting the `SENTRY_NATIVE_BACKEND` environment variable to an empty string.
74+
75+
### Flutter Web
76+
77+
The interop with the [Sentry Browser Javascript SDK](/platforms/javascript/) is now enabled by default.
78+
During `SentryFlutter.init` the SDK will inject the CDN script into the HTML's head.
79+
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.
80+
81+
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.
82+
[Read this guide](https://docs.sentry.io/platforms/javascript/install/loader/#cdn) on how to install the SDK into your application via CDN bundles.
83+
84+
### Drift Integration
85+
86+
We have bumped the required Drift version to `2.24.0` and have changed the API on how to use the integration.
87+
Instead of a `SentryQueryExecutor`, Sentry now provides a `SentryQueryInterceptor` that you can use like so:
88+
89+
```dart
90+
final executor = NativeDatabase.memory().interceptWith(
91+
SentryQueryInterceptor(databaseName: 'your_db_name')
92+
);
93+
```
94+
95+
For more information on how to use `QueryInterceptor` read the [Drift documentation](https://drift.simonbinder.eu/examples/tracing/).
96+
697
## Migrating From `sentry_flutter` `6.18.x` to `sentry_flutter` `7.0.0`
798

899
In addition to the changes introduced in [sentry](/platforms/dart/migration/):

0 commit comments

Comments
 (0)