docs(flutter): Document Sentry.runZonedGuarded

docs/platforms/flutter/index.mdx

@@ -46,7 +46,6 @@ dependencies:
 
 Configuration should happen as early as possible in your application's lifecycle.
 
-
 ```dart {"onboardingOptions": {"performance": "8-10", "profiling": "11-14"}}
 import 'package:flutter/widgets.dart';
 import 'package:sentry_flutter/sentry_flutter.dart';
@@ -71,6 +70,43 @@ Future<void> main() async {
 }
 ```
 
+```dart {tabTitle:With custom zone}  {"onboardingOptions": {"performance": "16-18", "profiling": "19-22"}}
+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___';
+        // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
+        // We recommend adjusting this value in production.
+        options.tracesSampleRate = 1.0;
+        // 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;
+      },
+      appRunner: () => runApp(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.

platform-includes/capture-error/flutter.mdx

@@ -1,4 +1,32 @@
 <PlatformContent includePath="capture-error/dart.mdx" />
 
-- Flutter-specific errors, such as using `FlutterError.onError`, are captured automatically
-- The SDK already runs your init `callback` on an error handler, such as [`runZonedGuarded`](https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html) on Flutter versions prior to `3.3`, or [`PlatformDispatcher.onError`](https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onError.html) on Flutter versions 3.3 and higher, so that errors are automatically captured.
+### FlutterError.onError
+
+Flutter-specific errors, such as using `FlutterError.onError`, are captured automatically.
+
+### PlatformDispatcher.onError / runZonedGuarded
+
+The SDK already runs your init `callback` on an error handler, such as [`runZonedGuarded`](https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html) on Flutter versions prior to `3.3`, or [`PlatformDispatcher.onError`](https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/onError.html) on Flutter versions 3.3 and higher, so that errors are automatically captured.
+
+If you need a custom error handling zone which also provides automatic error reporting and breadcrumb tracking, use `Sentry.runZonedGuarded`. It wraps Dart's native [`runZonedGuarded`](https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html) function with Sentry-specific functionality.
+
+This function automatically records calls to `print()` as `Breadcrumbs` and can be configured using `SentryOptions.enablePrintBreadcrumbs`.
+
+```dart
+Sentry.runZonedGuarded(() async {
+  WidgetsBinding.ensureInitialized();
+
+  // Errors before init will not be handled by Sentry
+
+  await SentryFlutter.init(
+    (options) {
+    ...
+    },
+    appRunner: () => runApp(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.
+});
+```