Skip to content

Commit 18e5114

Browse files
buenaflorbuenaflor
authored
ref(flutter): move custom zone handling code snippet from init to troubleshooting (#13478)
It's better to move the code snippet for custom zones to the troubleshooting page as it is not so common to run into this issue.
1 parent 27f6f92 commit 18e5114

File tree

3 files changed

+33
-97
lines changed

3 files changed

+33
-97
lines changed

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

Lines changed: 0 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -96,54 +96,6 @@ Future<void> main() async {
9696
}
9797
```
9898

99-
```dart {tabTitle:With custom zone}
100-
import 'package:flutter/widgets.dart';
101-
import 'package:sentry_flutter/sentry_flutter.dart';
102-
103-
Future<void> main() async {
104-
// The SDK creates it's own custom zone on web for automatic error and breadcrumb tracking on web.
105-
// This could lead to zone mismatch errors if you needed to call `WidgetsBinding.ensureInitialized()` before Sentry in a cusom zone.
106-
// With `Sentry.runZonedGuarded` you still get convenient auto error and breadcrumb tracking and can also call `WidgetsBinding.ensureInitialized()` before Sentry.
107-
Sentry.runZonedGuarded(() async {
108-
WidgetsBinding.ensureInitialized();
109-
110-
// Errors before init will not be handled by Sentry
111-
112-
await SentryFlutter.init(
113-
(options) {
114-
options.dsn = '___PUBLIC_DSN___';
115-
// Adds request headers and IP for users, for more info visit:
116-
// https://docs.sentry.io/platforms/dart/guides/flutter/data-management/data-collected/ for more info
117-
options.sendDefaultPii = true;
118-
// ___PRODUCT_OPTION_START___ performance
119-
// Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
120-
// We recommend adjusting this value in production.
121-
options.tracesSampleRate = 1.0;
122-
// ___PRODUCT_OPTION_END___ performance
123-
// ___PRODUCT_OPTION_START___ profiling
124-
// The sampling rate for profiling is relative to tracesSampleRate
125-
// Setting to 1.0 will profile 100% of sampled transactions:
126-
// Note: Profiling alpha is available for iOS and macOS since SDK version 7.12.0
127-
options.profilesSampleRate = 1.0;
128-
// ___PRODUCT_OPTION_END___ profiling
129-
},
130-
appRunner: () => runApp(
131-
SentryWidget(
132-
child: MyApp(),
133-
),
134-
),
135-
);
136-
} (error, stackTrace) {
137-
// Automatically sends errors to Sentry, no need to do any
138-
// captureException calls on your part.
139-
// On top of that, you can do your own custom stuff in this callback.
140-
});
141-
142-
// you can also configure SENTRY_DSN, SENTRY_RELEASE, SENTRY_DIST, and
143-
// SENTRY_ENVIRONMENT via Dart environment variable (--dart-define)
144-
}
145-
```
146-
14799
## Verify
148100

149101
Verify that your app is sending events to Sentry by adding the following snippet, which includes an intentional error. You should see the error reported in Sentry within a few minutes.

‎docs/platforms/dart/guides/flutter/manual-setup.mdx

Lines changed: 0 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -62,54 +62,6 @@ Future<void> main() async {
6262
}
6363
```
6464

65-
```dart {tabTitle:With custom zone}
66-
import 'package:flutter/widgets.dart';
67-
import 'package:sentry_flutter/sentry_flutter.dart';
68-
69-
Future<void> main() async {
70-
// The SDK creates it's own custom zone on web for automatic error and breadcrumb tracking on web.
71-
// This could lead to zone mismatch errors if you needed to call `WidgetsBinding.ensureInitialized()` before Sentry in a cusom zone.
72-
// With `Sentry.runZonedGuarded` you still get convenient auto error and breadcrumb tracking and can also call `WidgetsBinding.ensureInitialized()` before Sentry.
73-
Sentry.runZonedGuarded(() async {
74-
WidgetsBinding.ensureInitialized();
75-
76-
// Errors before init will not be handled by Sentry
77-
78-
await SentryFlutter.init(
79-
(options) {
80-
options.dsn = '___PUBLIC_DSN___';
81-
// Adds request headers and IP for users, for more info visit:
82-
// https://docs.sentry.io/platforms/dart/data-management/data-collected/
83-
options.sendDefaultPii = true;
84-
// ___PRODUCT_OPTION_START___ performance
85-
// Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
86-
// We recommend adjusting this value in production.
87-
options.tracesSampleRate = 1.0;
88-
// ___PRODUCT_OPTION_END___ performance
89-
// ___PRODUCT_OPTION_START___ profiling
90-
// The sampling rate for profiling is relative to tracesSampleRate
91-
// Setting to 1.0 will profile 100% of sampled transactions:
92-
// Note: Profiling alpha is available for iOS and macOS since SDK version 7.12.0
93-
options.profilesSampleRate = 1.0;
94-
// ___PRODUCT_OPTION_END___ profiling
95-
},
96-
appRunner: () => runApp(
97-
SentryWidget(
98-
child: MyApp(),
99-
),
100-
),
101-
);
102-
} (error, stackTrace) {
103-
// Automatically sends errors to Sentry, no need to do any
104-
// captureException calls on your part.
105-
// On top of that, you can do your own custom stuff in this callback.
106-
});
107-
108-
// you can also configure SENTRY_DSN, SENTRY_RELEASE, SENTRY_DIST, and
109-
// SENTRY_ENVIRONMENT via Dart environment variable (--dart-define)
110-
}
111-
```
112-
11365
## Verify
11466

11567
Verify that your app is sending events to Sentry by adding the following snippet, which includes an intentional error. You should see the error reported in Sentry within a few minutes.

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

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ If you need help solving issues with Sentry's Flutter SDK, you can read the edge
88

99
## Support 16 KB Page Sizes on Android
1010

11-
Starting with Android 15, AOSP supports devices with a 16 KB page size. If your app uses NDK libraries (directly or via an SDK), you’ll need to rebuild it for compatibility with these devices.
11+
Starting with Android 15, AOSP supports devices with a 16 KB page size. If your app uses NDK libraries (directly or via an SDK), you'll need to rebuild it for compatibility with these devices.
1212

1313
Update to Sentry Flutter SDK version `8.11.0` and above order to support 16 KB page sizes on Android devices.
1414

@@ -73,6 +73,38 @@ This is an [issue](https://github.com/flutter/flutter/issues/135245) with Flutte
7373

7474
For prior versions, you can work around this by configuring the SDK only to take screenshots when the app is in the `resumed` state. To do this, set `SentryFlutterOptions.attachScreenshotOnlyWhenResumed` to `true`.
7575

76+
## Zone Mismatch Error on Web
77+
78+
By default, the Sentry Flutter SDK creates a custom zone on web for automatic error and breadcrumb tracking. This can lead to zone mismatch errors when your application calls `WidgetsBinding.ensureInitialized()` before initializing Sentry.
79+
80+
To resolve this issue, use the `Sentry.runZonedGuarded` method to initialize both your application and Sentry within the same zone. This approach ensures proper zone consistency throughout your application:
81+
82+
```dart
83+
import 'package:flutter/widgets.dart';
84+
import 'package:sentry_flutter/sentry_flutter.dart';
85+
86+
Future<void> main() async {
87+
Sentry.runZonedGuarded(() async {
88+
WidgetsBinding.ensureInitialized();
89+
90+
await SentryFlutter.init(
91+
(options) {
92+
// your config...
93+
},
94+
appRunner: () => runApp(
95+
SentryWidget(
96+
child: MyApp(),
97+
),
98+
),
99+
);
100+
} (error, stackTrace) {
101+
// Note: Errors in this zone are already sent to Sentry automatically.
102+
// This callback lets you add your own custom error handling (like logging)
103+
// in addition to Sentry's reporting.
104+
});
105+
}
106+
```
107+
76108
## Using Flutter Multi-view for Web
77109

78110
Multi-view embedding was introduced in Flutter 3.24. You'll find a detailed guide about it in the [Flutter docs](https://docs.flutter.dev/platform-integration/web/embedding-flutter-web) .

0 commit comments

Comments
 (0)