flutter: improve session and screenshots docs (#11708)

* improve docs

* update

* update

* update snippet

* update doc

* update screenshots

* Update docs/platforms/flutter/configuration/options.mdx

Co-authored-by: Alex Krawiec <[email protected]>

* Update docs/platforms/flutter/configuration/releases.mdx

Co-authored-by: Alex Krawiec <[email protected]>

* Update platform-includes/configuration/auto-session-tracking/flutter.mdx

Co-authored-by: Alex Krawiec <[email protected]>

* Update platform-includes/enriching-events/attach-screenshots/flutter.mdx

Co-authored-by: Alex Krawiec <[email protected]>

* Update platform-includes/configuration/auto-session-tracking/flutter.mdx

Co-authored-by: Alex Krawiec <[email protected]>

* update code snippets

* update code snippets

* update code snippets

---------

Co-authored-by: Alex Krawiec <[email protected]>

Author: buenaflor

docs/platforms/dart/configuration/releases.mdx

@@ -57,3 +57,14 @@ Setting the release name tags each event with that release name. We recommend th
 If you don't tell Sentry about a new release, Sentry will automatically create a release entity in the system the first time it sees an event with that release ID.
 
 After configuring your SDK, you can install a repository integration or manually supply Sentry with your own commit metadata. Read our documentation about [setting up releases](/product/releases/setup/) for further information about integrations, associating commits, and telling Sentry when deploying releases.
+
+## Release Health
+
+<Note>
+
+Looking for Flutter release health? [See the Flutter documentation](/platforms/flutter/configuration/releases/#release-health).
+
+</Note>
+
+Monitoring release health is currently not supported for pure Dart applications.
+

docs/platforms/dart/index.mdx

@@ -68,7 +68,7 @@ Verify that your app is sending events to Sentry by adding the following snippet
 import 'package:sentry/sentry.dart';
 
 try {
-  aMethodThatMightFail();
+  throw Exception('Sentry Test Error');
 } catch (exception, stackTrace) {
   await Sentry.captureException(
     exception,

docs/platforms/flutter/configuration/options.mdx

@@ -151,6 +151,7 @@ This option can be overridden using <PlatformIdentifier name="in-app-include" />
 <ConfigKey name="attach-screenshot">
 
 Takes a screenshot of the application when an error happens and includes it as an attachment.
+Enable this option by setting <PlatformIdentifier name="attach-screenshot" /> to `true` and wrapping your root widget with `SentryWidget(child: MyApp())`.
 Learn more about enriching events with screenshots in our <PlatformLink to="/enriching-events/screenshots/">Screenshots documentation</PlatformLink>.
 
 </ConfigKey>

docs/platforms/flutter/configuration/releases.mdx

@@ -62,14 +62,14 @@ After configuring your SDK, you can install a repository integration or manually
 
 Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crash), and [session data](/product/releases/health/#session). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters.
 
+In order to monitor release health, the SDK sends session data.
+
 <Note>
 
-Crash reporting and app hang detection are not available for watchOS.
+Release health in Flutter is only available for Android, iOS, and macOS.
 
 </Note>
 
-In order to monitor release health, the SDK sends session data.
-
 ### Sessions
 
 A session represents the interaction between the user and the application. Sessions contain a timestamp, a status (if the session was OK or if it crashed), and are always linked to a release. Most Sentry SDKs can manage sessions automatically.

docs/platforms/flutter/enriching-events/screenshots/index.mdx

@@ -9,7 +9,7 @@ This feature is only available for SDKs with a user interface, like the ones for
 
 ## Enabling Screenshots
 
-Because screenshots may contain <PlatformLink to="/data-management/sensitive-data/">PII</PlatformLink>, they are an opt-in feature. You can enable screenshots as shown below:
+Because screenshots may contain <PlatformLink to="/data-management/sensitive-data/">PII</PlatformLink>, they are an opt-in feature.
 
 <PlatformContent includePath="enriching-events/attach-screenshots" />
 

docs/platforms/flutter/integrations/routing-instrumentation.mdx

@@ -30,7 +30,7 @@ Before starting, ensure:
 
 Add an instance of `SentryNavigationObserver` to your application's `navigatorObservers`.
 
-```dart {tabTitle: Flutter Routing}
+```dart {8} {tabTitle: Flutter Routing}
 import 'package:flutter/material.dart';
 import 'package:sentry_flutter/sentry_flutter.dart';
 
@@ -43,7 +43,7 @@ return MaterialApp(
 );
 ```
 
-```dart {tabTitle: GoRouter}
+```dart {6} {tabTitle: GoRouter}
 import 'package:go_router/go_router.dart';
 import 'package:sentry_flutter/sentry_flutter.dart';
 
@@ -62,21 +62,15 @@ For transactions to be created when navigation changes, you need to provide rout
 - Flutter routing: use `RouteSettings` and set the name in the constructor.
 - GoRouter: use the `name` parameter to set the route name.
 
-```dart {tabTitle: Flutter Routing}
-import 'package:flutter/material.dart';
-import 'package:sentry_flutter/sentry_flutter.dart';
-
+```dart {4} {tabTitle: Flutter Routing}
 /// Setting the route name is required
 MaterialPageRoute(
   builder: (BuildContext context) => MyWidget(),
   settings: RouteSettings(name: 'My Widget'),
 )
 ```
 
-```dart {tabTitle: GoRouter}
-import 'package:go_router/go_router.dart';
-import 'package:sentry_flutter/sentry_flutter.dart';
-
+```dart {13} {tabTitle: GoRouter}
 final GoRouter _router = GoRouter(
   observers: [SentryNavigatorObserver()],
   routes: <RouteBase>[
@@ -110,8 +104,6 @@ There are two ways to set up TTID:
 The default setup is enabled automatically, but only provides an approximation of TTID. To set a more accurate TTID, manually wrap the desired widget with `SentryDisplayWidget`, as shown below:
 
 ```dart
-import 'package:sentry_flutter/sentry_flutter.dart';
-
 SentryDisplayWidget(
   child: MyWidget(),
 )
@@ -129,23 +121,17 @@ TTFD is disabled by default. To enable TTFD measurements, follow these steps:
 
 1. Enable the `enableTimeToFullDisplayTracing` option in the SDK configuration:
 
-```dart
-import 'package:flutter/widgets.dart';
-import 'package:sentry_flutter/sentry_flutter.dart';
-
-Future<void> main() async {
-  await SentryFlutter.init(
-    (options) => options.enableTimeToFullDisplayTracing = true,
-    appRunner: () => runApp(MyApp()),
-  );
-}
+```dart {3}
+await SentryFlutter.init(
+  (options) {
+    options.enableTimeToFullDisplayTracing = true;
+  }, appRunner: () => runApp(MyApp()),
+);
 ```
 
 2. Report the span manually:
 
 ```dart
-import 'package:sentry_flutter/sentry_flutter.dart';
-
 SentryFlutter.reportFullyDisplayed();
 ```
 
@@ -231,9 +217,6 @@ Log into [sentry.io](https://sentry.io) and open your project's performance page
 Adjust the duration before a routing transaction automatically finishes. The default is 3 seconds.
 
 ```dart
-import 'package:sentry_flutter/sentry_flutter.dart';
-
-/// Change how long navigation transactions idle before being finished
 SentryNavigatorObserver(
   autoFinishAfter: Duration(seconds: 5)
 )
@@ -251,9 +234,6 @@ Set `enableAutoTransactions` to `false` if you only want to track navigation bre
 Enabled by default.
 
 ```dart
-import 'package:sentry_flutter/sentry_flutter.dart';
-
-/// Only track navigation breadcrumbs
 SentryNavigatorObserver(
   enableAutoTransactions: false,
 )
@@ -265,9 +245,6 @@ Set `ignoreRoutes` if you want routes to be ignored and not processed by the nav
 Empty by default.
 
 ```dart
-import 'package:sentry_flutter/sentry_flutter.dart';
-
-/// Ignore matching routes
 SentryNavigatorObserver(
   ignoreRoutes: ["/ignoreThisRoute", "/my/ignored/route"],
 )
@@ -280,9 +257,6 @@ An existing transaction in the scope 'CustomTransaction' will be renamed to 'MyW
 Disabled by default.
 
 ```dart
-import 'package:sentry_flutter/sentry_flutter.dart';
-
-/// Override transaction name with route name
 SentryNavigatorObserver(
   setRouteNameAsTransaction: true,
 )

platform-includes/configuration/auto-session-tracking/flutter.mdx

@@ -1,29 +1,21 @@
 To benefit from the health data, you must use at least version 4.0.0 of the Flutter SDK.
 
-By default, the session is terminated once the application is in the background for more than 30 seconds. You can change the time out with the option named `sessionTrackingIntervalMillis`. It takes the amount in milliseconds. For example, to configure it to be 60 seconds:
+#### Session Timeout
 
-```dart
-import 'package:flutter/widgets.dart';
-import 'package:sentry_flutter/sentry_flutter.dart';
+By default, the session is terminated once the application is in the background for more than `30 seconds`. You can change this default by setting the `autoSessionTrackingInterval` option to a `Duration` of your choosing.
 
-Future<void> main() async {
-  await SentryFlutter.init(
-    (options) => options.autoSessionTrackingInterval = const Duration(milliseconds: 60000)
-    appRunner: () => runApp(MyApp()),
-  );
-}
+```dart {2}
+SentryFlutter.init((options) {
+  options.autoSessionTrackingInterval = const Duration(seconds: 60)
+});
 ```
 
-If you'd like to opt out of this feature, you can do so using options.
+#### Disable Auto Session Tracking
 
-```dart
-import 'package:flutter/widgets.dart';
-import 'package:sentry_flutter/sentry_flutter.dart';
+If you'd like to opt out of capturing sessions, set the `enableAutoSessionTracking` option to `false`. If you disable this feature, release health will not be available.
 
-Future<void> main() async {
-  await SentryFlutter.init(
-    (options) => options.enableAutoSessionTracking = true, // it's enabled by default
-    appRunner: () => runApp(MyApp()),
-  );
-}
+```dart {2}
+SentryFlutter.init((options) {
+  options.enableAutoSessionTracking = false;
+});
 ```

platform-includes/enriching-events/attach-screenshots/flutter.mdx

@@ -1,48 +1,40 @@
-```dart
-import 'package:flutter/widgets.dart';
-import 'package:sentry_flutter/sentry_flutter.dart';
+Enable screenshots by setting the `attachScreenshot` option to `true` and wrap your root widget with `SentryWidget`.
 
-Future<void> main() async {
-  await SentryFlutter.init(
-    (options) {
-      options.dsn = '___PUBLIC_DSN___';
-      options.attachScreenshot = true;
-    },
-    appRunner: () => runApp(
-      // Wrap your app widget with the [SentryWidget] widget.
-      SentryWidget(
-        child: MyApp(),
-      ),
+```dart {3, 6-8}
+await SentryFlutter.init(
+  (options) {
+    options.attachScreenshot = true;
+  },
+  appRunner: () => runApp(
+    SentryWidget(
+      child: MyApp(),
     ),
-  );
-}
+  ),
+);
 ```
 
-### Filtering Screenshots
+## Filtering Screenshots
 
-You can filter your screenshots by using the `beforeScreenshot` callback.
-It is called before taking a screenshot and if the callback returns `false`, the screenshot will not be attached.
+You can filter your screenshots by using the `beforeScreenshot` callback, which is called before attaching a screenshot to an event. By default, the callback returns `true` which means that all screenshots are attached.
 
-```dart
-import 'package:flutter/widgets.dart';
-import 'package:sentry_flutter/sentry_flutter.dart';
+If the callback returns `false`, the screenshot will not be attached.
 
-Future<void> main() async {
-  await SentryFlutter.init(
-    (options) {
-      options.dsn = '___PUBLIC_DSN___';
-      options.attachScreenshot = true;
-      options.beforeScreenshot = (event, {hint}) {
-        // Return false if you don't want to attach the screenshot based on some condition.
-        return true;
-      };
-    },
-    appRunner: () => runApp(
-      // Wrap your app widget with the [SentryWidget] widget.
-      SentryWidget(
-        child: MyApp(),
-      ),
+```dart {4-10}
+await SentryFlutter.init(
+  (options) {
+    options.attachScreenshot = true;
+    options.beforeScreenshot = (event, {hint}) {
+    // Based on some condition you can decide to attach the screenshot or drop it
+    if (event.throwable is MyImportantException) {
+      return true;
+    }
+      return false;
+    };
+  },
+  appRunner: () => runApp(
+    SentryWidget(
+      child: MyApp(),
     ),
-  );
-}
+  ),
+);
 ```