Skip to content

ref(flutter): move custom zone handling code snippet from init to troubleshooting #13478

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
buenaflor merged 3 commits into from
Apr 30, 2025
Merged

ref(flutter): move custom zone handling code snippet from init to troubleshooting #13478

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2fcbc8b
Update
buenaflor Apr 22, 2025
7ffc94c
Update
buenaflor Apr 22, 2025
5c69675
Update
buenaflor Apr 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 0 additions & 48 deletions docs/platforms/dart/guides/flutter/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,54 +96,6 @@ Future<void> main() async {
}
```

```dart {tabTitle:With custom zone}
import 'package:flutter/widgets.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
// The SDK creates it's own custom zone on web for automatic error and breadcrumb tracking on web.
// This could lead to zone mismatch errors if you needed to call `WidgetsBinding.ensureInitialized()` before Sentry in a cusom zone.
// With `Sentry.runZonedGuarded` you still get convenient auto error and breadcrumb tracking and can also call `WidgetsBinding.ensureInitialized()` before Sentry.
Sentry.runZonedGuarded(() async {
WidgetsBinding.ensureInitialized();

// Errors before init will not be handled by Sentry

await SentryFlutter.init(
(options) {
options.dsn = '___PUBLIC_DSN___';
// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/dart/guides/flutter/data-management/data-collected/ for more info
options.sendDefaultPii = true;
// ___PRODUCT_OPTION_START___ performance
// Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
// We recommend adjusting this value in production.
options.tracesSampleRate = 1.0;
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ profiling
// The sampling rate for profiling is relative to tracesSampleRate
// Setting to 1.0 will profile 100% of sampled transactions:
// Note: Profiling alpha is available for iOS and macOS since SDK version 7.12.0
options.profilesSampleRate = 1.0;
// ___PRODUCT_OPTION_END___ profiling
},
appRunner: () => runApp(
SentryWidget(
child: MyApp(),
),
),
);
} (error, stackTrace) {
// Automatically sends errors to Sentry, no need to do any
// captureException calls on your part.
// On top of that, you can do your own custom stuff in this callback.
});

// you can also configure SENTRY_DSN, SENTRY_RELEASE, SENTRY_DIST, and
// SENTRY_ENVIRONMENT via Dart environment variable (--dart-define)
}
```

## Verify

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.
Expand Down
48 changes: 0 additions & 48 deletions docs/platforms/dart/guides/flutter/manual-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,54 +62,6 @@ Future<void> main() async {
}
```

```dart {tabTitle:With custom zone}
import 'package:flutter/widgets.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
// The SDK creates it's own custom zone on web for automatic error and breadcrumb tracking on web.
// This could lead to zone mismatch errors if you needed to call `WidgetsBinding.ensureInitialized()` before Sentry in a cusom zone.
// With `Sentry.runZonedGuarded` you still get convenient auto error and breadcrumb tracking and can also call `WidgetsBinding.ensureInitialized()` before Sentry.
Sentry.runZonedGuarded(() async {
WidgetsBinding.ensureInitialized();

// Errors before init will not be handled by Sentry

await SentryFlutter.init(
(options) {
options.dsn = '___PUBLIC_DSN___';
// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/dart/data-management/data-collected/
options.sendDefaultPii = true;
// ___PRODUCT_OPTION_START___ performance
// Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
// We recommend adjusting this value in production.
options.tracesSampleRate = 1.0;
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ profiling
// The sampling rate for profiling is relative to tracesSampleRate
// Setting to 1.0 will profile 100% of sampled transactions:
// Note: Profiling alpha is available for iOS and macOS since SDK version 7.12.0
options.profilesSampleRate = 1.0;
// ___PRODUCT_OPTION_END___ profiling
},
appRunner: () => runApp(
SentryWidget(
child: MyApp(),
),
),
);
} (error, stackTrace) {
// Automatically sends errors to Sentry, no need to do any
// captureException calls on your part.
// On top of that, you can do your own custom stuff in this callback.
});

// you can also configure SENTRY_DSN, SENTRY_RELEASE, SENTRY_DIST, and
// SENTRY_ENVIRONMENT via Dart environment variable (--dart-define)
}
```

## Verify

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.
Expand Down
34 changes: 33 additions & 1 deletion docs/platforms/dart/guides/flutter/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ If you need help solving issues with Sentry's Flutter SDK, you can read the edge

## Support 16 KB Page Sizes on Android

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.
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.

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

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

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`.

## Zone Mismatch Error on Web

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.

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:

```dart
import 'package:flutter/widgets.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
Sentry.runZonedGuarded(() async {
WidgetsBinding.ensureInitialized();

await SentryFlutter.init(
(options) {
// your config...
},
appRunner: () => runApp(
SentryWidget(
child: MyApp(),
),
),
);
} (error, stackTrace) {
// Note: Errors in this zone are already sent to Sentry automatically.
// This callback lets you add your own custom error handling (like logging)
// in addition to Sentry's reporting.
});
}
```

## Using Flutter Multi-view for Web

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) .
Expand Down