Feat: Screenshot Attachment

dart/lib/sentry.dart

@@ -30,3 +30,5 @@ export 'src/sentry_user_feedback.dart';
 export 'src/utils/tracing_utils.dart';
 // tracing
 export 'src/tracing.dart';
+// attachments
+export 'src/sentry_client_attachment_processor.dart';

dart/lib/src/sentry_client.dart

@@ -19,6 +19,7 @@ import 'sentry_envelope.dart';
 import 'client_reports/client_report_recorder.dart';
 import 'client_reports/discard_reason.dart';
 import 'transport/data_category.dart';
+import 'sentry_client_attachment_processor.dart';
 
 /// Default value for [User.ipAddress]. It gets set when an event does not have
 /// a user and IP address. Only applies if [SentryOptions.sendDefaultPii] is set
@@ -37,6 +38,9 @@ class SentryClient {
 
   SentryStackTraceFactory get _stackTraceFactory => _options.stackTraceFactory;
 
+  SentryClientAttachmentProcessor get _clientAttachmentProcessor =>
+      _options.clientAttachmentProcessor;
+
   /// Instantiates a client using [SentryOptions]
   factory SentryClient(SentryOptions options) {
     if (options.sendClientReports) {
@@ -130,12 +134,15 @@ class SentryClient {
       preparedEvent = _eventWithRemovedBreadcrumbsIfHandled(preparedEvent);
     }
 
+    final attachments = await _clientAttachmentProcessor.processAttachments(
+        scope?.attachments ?? [], preparedEvent);
+
     final envelope = SentryEnvelope.fromEvent(
       preparedEvent,
       _options.sdk,
       dsn: _options.dsn,
       traceContext: scope?.span?.traceContext(),
-      attachments: scope?.attachments,
+      attachments: attachments.isNotEmpty ? attachments : null,
     );
 
     final id = await captureEnvelope(envelope);

dart/lib/src/sentry_client_attachment_processor.dart

@@ -0,0 +1,11 @@
+import 'dart:async';
+
+import './sentry_attachment/sentry_attachment.dart';
+import './protocol/sentry_event.dart';
+
+class SentryClientAttachmentProcessor {
+  Future<List<SentryAttachment>> processAttachments(
+      List<SentryAttachment> attachments, SentryEvent event) async {
+    return attachments;
+  }
+}

dart/lib/src/sentry_options.dart

@@ -354,6 +354,10 @@ class SentryOptions {
   @internal
   late SentryStackTraceFactory stackTraceFactory =
       SentryStackTraceFactory(this);
+
+  @internal
+  late SentryClientAttachmentProcessor clientAttachmentProcessor =
+      SentryClientAttachmentProcessor();
 }
 
 /// This function is called with an SDK specific event object and can return a modified event

dart/test/sentry_client_test.dart

@@ -2,6 +2,7 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:typed_data';
 
+import 'package:collection/collection.dart';
 import 'package:sentry/sentry.dart';
 import 'package:sentry/src/client_reports/client_report.dart';
 import 'package:sentry/src/client_reports/discard_reason.dart';
@@ -1043,6 +1044,45 @@ void main() {
     });
   });
 
+  group('SentryClientAttachmentProcessor', () {
+    late Fixture fixture;
+
+    setUp(() {
+      fixture = Fixture();
+    });
+
+    test('processor filtering out attachments', () async {
+      fixture.options.clientAttachmentProcessor =
+          MockAttachmentProcessor(MockAttachmentProcessorMode.filter);
+      final scope = Scope(fixture.options);
+      scope.addAttachment(SentryAttachment.fromIntList([], "scope-attachment"));
+      final sut = fixture.getSut();
+
+      final event = SentryEvent();
+      await sut.captureEvent(event, scope: scope);
+
+      final capturedEnvelope = (fixture.transport).envelopes.first;
+      final attachmentItem = capturedEnvelope.items.firstWhereOrNull(
+          (element) => element.header.type == SentryItemType.attachment);
+      expect(attachmentItem, null);
+    });
+
+    test('processor adding attachments', () async {
+      fixture.options.clientAttachmentProcessor =
+          MockAttachmentProcessor(MockAttachmentProcessorMode.add);
+      final scope = Scope(fixture.options);
+      final sut = fixture.getSut();
+
+      final event = SentryEvent();
+      await sut.captureEvent(event, scope: scope);
+
+      final capturedEnvelope = (fixture.transport).envelopes.first;
+      final attachmentItem = capturedEnvelope.items.firstWhereOrNull(
+          (element) => element.header.type == SentryItemType.attachment);
+      expect(attachmentItem != null, true);
+    });
+  });
+
   group('ClientReportRecorder', () {
     late Fixture fixture;
 
@@ -1341,3 +1381,23 @@ class Fixture {
     loggedException = exception;
   }
 }
+
+enum MockAttachmentProcessorMode { filter, add }
+
+/// Filtering out all attachments.
+class MockAttachmentProcessor implements SentryClientAttachmentProcessor {
+  MockAttachmentProcessorMode mode;
+
+  MockAttachmentProcessor(this.mode);
+
+  @override
+  Future<List<SentryAttachment>> processAttachments(
+      List<SentryAttachment> attachments, SentryEvent event) async {
+    switch (mode) {
+      case MockAttachmentProcessorMode.filter:
+        return <SentryAttachment>[];
+      case MockAttachmentProcessorMode.add:
+        return <SentryAttachment>[SentryAttachment.fromIntList([], "added")];
+    }
+  }
+}

flutter/example/lib/main.dart

@@ -38,9 +38,11 @@ Future<void> main() async {
     },
     // Init your App.
     appRunner: () => runApp(
-      DefaultAssetBundle(
-        bundle: SentryAssetBundle(enableStructuredDataTracing: true),
-        child: MyApp(),
+      SentryWidget(
+        child: DefaultAssetBundle(
+          bundle: SentryAssetBundle(enableStructuredDataTracing: true),
+          child: MyApp(),
+        ),
       ),
     ),
   );

flutter/lib/sentry_flutter.dart

@@ -8,3 +8,4 @@ export 'src/sentry_flutter_options.dart';
 export 'src/flutter_sentry_attachment.dart';
 export 'src/sentry_asset_bundle.dart';
 export 'src/integrations/on_error_integration.dart';
+export 'src/sentry_widget.dart';

flutter/lib/src/integrations/screenshot_integration.dart

@@ -0,0 +1,29 @@
+import 'dart:async';
+
+import 'package:flutter/scheduler.dart';
+import 'package:sentry/sentry.dart';
+import '../screenshot/screenshot_attachment_processor.dart';
+import '../sentry_flutter_options.dart';
+
+class ScreenshotIntegration implements Integration<SentryFlutterOptions> {
+  SentryFlutterOptions? _options;
+
+  @override
+  FutureOr<void> call(Hub hub, SentryFlutterOptions options) {
+    // ignore: invalid_use_of_internal_member
+    options.clientAttachmentProcessor = ScreenshotAttachmentProcessor(() {
+      try {
+        /// Flutter >= 2.12 throws if SchedulerBinding.instance isn't initialized.
+        return SchedulerBinding.instance;
+      } catch (_) {}
+      return null;
+    }, options);
+    _options = options;
+  }
+
+  @override
+  FutureOr<void> close() {
+    // ignore: invalid_use_of_internal_member
+    _options?.clientAttachmentProcessor = SentryClientAttachmentProcessor();
+  }
+}

flutter/lib/src/screenshot/screenshot_attachment.dart

@@ -0,0 +1,63 @@
+import 'dart:async';
+import 'dart:typed_data';
+import 'dart:ui' as ui show ImageByteFormat;
+
+import 'package:flutter/rendering.dart';
+import 'package:flutter/scheduler.dart';
+import 'package:sentry/sentry.dart';
+
+import '../sentry_widget.dart';
+
+class ScreenshotAttachment implements SentryAttachment {
+  final SchedulerBinding _schedulerBinding;
+  final SentryOptions _options;
+
+  ScreenshotAttachment(this._schedulerBinding, this._options);
+
+  @override
+  String attachmentType = SentryAttachment.typeAttachmentDefault;
+
+  @override
+  String? contentType = 'image/png';
+
+  @override
+  String filename = 'screenshot.png';
+
+  @override
+  bool addToTransactions = true;
+
+  @override
+  FutureOr<Uint8List> get bytes async {
+    final _completer = Completer<Uint8List?>();
+    // We add an post frame callback because we aren't able to take a screenshot
+    // if there's currently a draw in process.
+    _schedulerBinding.addPostFrameCallback((timeStamp) async {
+      final screenshot = await _createScreenshot();
+      _completer.complete(screenshot);
+    });
+    return await _completer.future ?? Uint8List.fromList([]);
+  }
+
+  Future<Uint8List?> _createScreenshot() async {
+    try {
+      final renderObject =
+          sentryWidgetGlobalKey.currentContext?.findRenderObject();
+
+      if (renderObject is RenderRepaintBoundary) {
+        final image = await renderObject.toImage(pixelRatio: 1);
+        // At the time of writing there's no other image format available which
+        // Sentry understands.
+        final bytes = await image.toByteData(format: ui.ImageByteFormat.png);
+        return bytes?.buffer.asUint8List();
+      }
+    } catch (exception, stackTrace) {
+      _options.logger(
+        SentryLevel.error,
+        'Could not create screenshot.',
+        exception: exception,
+        stackTrace: stackTrace,
+      );
+    }
+    return null;
+  }
+}

flutter/lib/src/screenshot/screenshot_attachment_processor.dart

@@ -0,0 +1,36 @@
+import 'dart:async';
+
+import 'package:sentry/sentry.dart';
+import '../integrations/native_app_start_integration.dart';
+import '../sentry_widget.dart';
+import 'screenshot_attachment.dart';
+
+class ScreenshotAttachmentProcessor implements SentryClientAttachmentProcessor {
+  final SchedulerBindingProvider _schedulerBindingProvider;
+  final SentryOptions _options;
+
+  ScreenshotAttachmentProcessor(this._schedulerBindingProvider, this._options);
+
+  /// This is true when the SentryWidget is in the view hierarchy
+  bool get _attachScreenshot => sentryWidgetGlobalKey.currentContext != null;
+
+  @override
+  Future<List<SentryAttachment>> processAttachments(
+      List<SentryAttachment> attachments, SentryEvent event) async {
+    if (event.exceptions == null &&
+        event.throwable == null &&
+        _attachScreenshot) {
+      return attachments;
+    }
+    final schedulerBinding = _schedulerBindingProvider();
+    if (schedulerBinding != null) {
+      final attachmentsWithScreenshot = <SentryAttachment>[];
+      attachmentsWithScreenshot.addAll(attachments);
+      attachmentsWithScreenshot
+          .add(ScreenshotAttachment(schedulerBinding, _options));
+      return attachmentsWithScreenshot;
+    } else {
+      return attachments;
+    }
+  }
+}

flutter/lib/src/sentry_flutter.dart

@@ -7,6 +7,7 @@ import 'package:meta/meta.dart';
 import 'package:package_info_plus/package_info_plus.dart';
 import '../sentry_flutter.dart';
 import 'event_processor/android_platform_exception_event_processor.dart';
+import 'integrations/screenshot_integration.dart';
 import 'native_scope_observer.dart';
 import 'sentry_native.dart';
 import 'sentry_native_channel.dart';
@@ -139,6 +140,7 @@ mixin SentryFlutter {
         !platformChecker.isWeb &&
         (platform.isAndroid || platform.isIOS || platform.isMacOS)) {
       integrations.add(LoadImageListIntegration(channel));
+      integrations.add(ScreenshotIntegration());
     }
 
     integrations.add(DebugPrintIntegration());

flutter/lib/src/sentry_widget.dart

@@ -0,0 +1,38 @@
+import 'package:flutter/material.dart';
+
+/// Key which is used to identify the [RepaintBoundary]
+final sentryWidgetGlobalKey = GlobalKey(debugLabel: 'sentry_widget');
+
+/// You can add screenshots of [child] to crash reports by adding this widget.
+/// Ideally you are adding it around your app widget like in the following
+/// example.
+/// ```dart
+/// runApp(SentryWidget(child: App()));
+/// ```
+///
+/// Remarks:
+/// - Depending on the place where it's used, you might have a transparent
+///   background.
+/// - Platform Views currently can't be captured.
+/// - It only works on Flutters Canvas Kit Web renderer. For more information
+///   see https://flutter.dev/docs/development/tools/web-renderers
+/// - You can only have one [SentryWidget] widget in your widget tree at all
+///   times.
+class SentryWidget extends StatefulWidget {
+  const SentryWidget({Key? key, required this.child}) : super(key: key);
+
+  final Widget child;
+
+  @override
+  _SentryWidgetState createState() => _SentryWidgetState();
+}
+
+class _SentryWidgetState extends State<SentryWidget> {
+  @override
+  Widget build(BuildContext context) {
+    return RepaintBoundary(
+      key: sentryWidgetGlobalKey,
+      child: widget.child,
+    );
+  }
+}

flutter/test/integrations/screenshot_integration_test.dart

@@ -0,0 +1,47 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:sentry_flutter/sentry_flutter.dart';
+import 'package:sentry_flutter/src/integrations/screenshot_integration.dart';
+import 'package:sentry_flutter/src/integrations/widgets_binding_integration.dart';
+import 'package:sentry_flutter/src/screenshot/screenshot_attachment_processor.dart';
+
+import '../mocks.mocks.dart';
+
+/// Tests that require `WidgetsFlutterBinding.ensureInitialized();` not
+/// being called at all.
+void main() {
+  late Fixture fixture;
+
+  setUp(() {
+    fixture = Fixture();
+  });
+
+  test('screenshotIntegration creates screenshot processor', () async {
+    final integration = ScreenshotIntegration();
+
+    await integration(fixture.hub, fixture.options);
+
+    expect(
+        // ignore: invalid_use_of_internal_member
+        fixture.options.clientAttachmentProcessor
+            is ScreenshotAttachmentProcessor,
+        true);
+  });
+
+  test('screenshotIntegration close resets processor', () async {
+    final integration = ScreenshotIntegration();
+
+    await integration(fixture.hub, fixture.options);
+    await integration.close();
+
+    expect(
+        // ignore: invalid_use_of_internal_member
+        fixture.options.clientAttachmentProcessor
+            is ScreenshotAttachmentProcessor,
+        false);
+  });
+}
+
+class Fixture {
+  final hub = MockHub();
+  final options = SentryFlutterOptions();
+}