feat: Add beforeCaptureScreenshotCallback

Add a callback to the options to decide if the SDK should capture a
screenshot or not.

Fixes GH-3137

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Add start time to network request breadcrumbs (#4008)
 - Add C++ exception support for `__cxa_rethrow` (#3996)
+- Add beforeCaptureScreenshot callback (#4016)
 
 ### Improvements
 

Samples/iOS-Swift/iOS-Swift/AppDelegate.swift

@@ -22,6 +22,9 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
             options.beforeSend = { event in
                 return event
             }
+            options.beforeCaptureScreenshot = { _ in
+                return true
+            }
             options.debug = true
 
             if #available(iOS 16.0, *) {

Sources/Sentry/Public/SentryDefines.h

@@ -81,6 +81,12 @@ typedef SentryBreadcrumb *_Nullable (^SentryBeforeBreadcrumbCallback)(
  */
 typedef SentryEvent *_Nullable (^SentryBeforeSendEventCallback)(SentryEvent *_Nonnull event);
 
+/**
+ * Block can be used to decide if the SDK should capture a screenshot or not. Return @c true if the
+ * SDK should capture a screenshot, return @c false if not. This callback doesn't work for crashes.
+ */
+typedef BOOL (^SentryBeforeCaptureScreenshotCallback)(SentryEvent *_Nonnull event);
+
 /**
  * A callback to be notified when the last program execution terminated with a crash.
  */

Sources/Sentry/Public/SentryOptions.h

@@ -105,6 +105,13 @@ NS_SWIFT_NAME(Options)
  */
 @property (nullable, nonatomic, copy) SentryBeforeBreadcrumbCallback beforeBreadcrumb;
 
+/**
+ * You can use this callback to decide if the SDK should capture a screenshot or not. Return @c true
+ * if the SDK should capture a screenshot, return @c false if not. This callback doesn't work for
+ * crashes.
+ */
+@property (nullable, nonatomic, copy) SentryBeforeCaptureScreenshotCallback beforeCaptureScreenshot;
+
 /**
  * A block called shortly after the initialization of the SDK when the last program execution
  * terminated with a crash.

Sources/Sentry/SentryOptions.m

@@ -339,6 +339,10 @@ - (BOOL)validateOptions:(NSDictionary<NSString *, id> *)options
         self.beforeBreadcrumb = options[@"beforeBreadcrumb"];
     }
 
+    if ([self isBlock:options[@"beforeCaptureScreenshot"]]) {
+        self.beforeCaptureScreenshot = options[@"beforeCaptureScreenshot"];
+    }
+
     if ([self isBlock:options[@"onCrashedLastRun"]]) {
         self.onCrashedLastRun = options[@"onCrashedLastRun"];
     }

Sources/Sentry/SentryScreenshotIntegration.m

@@ -8,6 +8,7 @@
 #    import "SentryEvent+Private.h"
 #    import "SentryException.h"
 #    import "SentryHub+Private.h"
+#    import "SentryOptions.h"
 #    import "SentrySDK+Private.h"
 
 #    if SENTRY_HAS_METRIC_KIT
@@ -21,10 +22,19 @@
     [SentryDependencyContainer.sharedInstance.screenshot saveScreenShots:reportPath];
 }
 
+@interface
+SentryScreenshotIntegration ()
+
+@property (nonatomic, strong) SentryOptions *options;
+
+@end
+
 @implementation SentryScreenshotIntegration
 
 - (BOOL)installWithOptions:(nonnull SentryOptions *)options
 {
+    self.options = options;
+
     if (![super installWithOptions:options]) {
         return NO;
     }
@@ -70,6 +80,10 @@ - (void)uninstall
         return attachments;
     }
 
+    if (self.options.beforeCaptureScreenshot && !self.options.beforeCaptureScreenshot(event)) {
+        return attachments;
+    }
+
     NSArray *screenshot =
         [SentryDependencyContainer.sharedInstance.screenshot appScreenshotsFromMainThread];
 

Tests/SentryTests/Integrations/Screenshot/SentryScreenshotIntegrationTests.swift

@@ -137,6 +137,26 @@ class SentryScreenshotIntegrationTests: XCTestCase {
     }
 #endif // os(iOS) || targetEnvironment(macCatalyst)
 
+    func test_NoScreenShot_WhenDiscardedInCallback() {
+        let sut = fixture.getSut()
+
+        let expectation = expectation(description: "BeforeCaptureScreenshot must be called.")
+
+        let options = Options()
+        options.beforeCaptureScreenshot = { _ in
+            expectation.fulfill()
+            return false
+        }
+
+        sut.install(with: options)
+
+        let newAttachmentList = sut.processAttachments([], for: Event(error: NSError(domain: "", code: -1)))
+
+        wait(for: [expectation], timeout: 1.0)
+
+        XCTAssertEqual(newAttachmentList?.count, 0)
+    }
+
     func test_noScreenshot_keepAttachment() {
         let sut = fixture.getSut()
         let event = Event()

Tests/SentryTests/SentryOptionsTest.m

@@ -310,6 +310,27 @@ - (void)testDefaultBeforeBreadcrumb
     XCTAssertNil(options.beforeBreadcrumb);
 }
 
+- (void)testBeforeCaptureScreenshot
+{
+    SentryBeforeCaptureScreenshotCallback callback = ^(SentryEvent *event) {
+        if (event.level == kSentryLevelFatal) {
+            return NO;
+        }
+
+        return YES;
+    };
+    SentryOptions *options = [self getValidOptions:@{ @"beforeCaptureScreenshot" : callback }];
+
+    XCTAssertEqual(callback, options.beforeCaptureScreenshot);
+}
+
+- (void)testDefaultBeforeCaptureScreenshot
+{
+    SentryOptions *options = [self getValidOptions:@{}];
+
+    XCTAssertNil(options.beforeCaptureScreenshot);
+}
+
 - (void)testTracePropagationTargets
 {
     SentryOptions *options =