feat: replay quality setting (#2582)

vaind · web-flow · commit ea6d86d569f2 · 2025-01-20T12:55:01.000+01:00
* replay quality config

* configure quality on ios

* chore

* ktlint

* chore: format

* swiftlint

* fix kotlin tests
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Add SentryReplayQuality setting (`options.experimental.replay.quality`) ([#2582](https://github.com/getsentry/sentry-dart/pull/2582))
+
 ### Dependencies
 
 - Bump Native SDK from v0.7.17 to v0.7.18 ([#2578](https://github.com/getsentry/sentry-dart/pull/2578))
diff --git a/flutter/android/src/main/kotlin/io/sentry/flutter/SentryFlutter.kt b/flutter/android/src/main/kotlin/io/sentry/flutter/SentryFlutter.kt
@@ -163,6 +163,14 @@ class SentryFlutter(
     options: SentryReplayOptions,
     data: Map<String, Any>,
   ) {
+    options.quality =
+      when (data["quality"] as? String) {
+        "low" -> SentryReplayOptions.SentryReplayQuality.LOW
+        "high" -> SentryReplayOptions.SentryReplayQuality.HIGH
+        else -> {
+          SentryReplayOptions.SentryReplayQuality.MEDIUM
+        }
+      }
     options.sessionSampleRate = data["sessionSampleRate"] as? Double
     options.onErrorSampleRate = data["onErrorSampleRate"] as? Double
 
diff --git a/flutter/ios/Classes/SentryFlutter.swift b/flutter/ios/Classes/SentryFlutter.swift
@@ -113,6 +113,14 @@ public final class SentryFlutter {
         }
 #if canImport(UIKit) && !SENTRY_NO_UIKIT && (os(iOS) || os(tvOS))
         if let replayOptions = data["replay"] as? [String: Any] {
+            switch data["quality"] as? String {
+            case "low":
+                options.sessionReplay.quality = SentryReplayOptions.SentryReplayQuality.low
+            case "high":
+                options.sessionReplay.quality = SentryReplayOptions.SentryReplayQuality.high
+            default:
+                options.sessionReplay.quality = SentryReplayOptions.SentryReplayQuality.medium
+            }
             options.sessionReplay.sessionSampleRate =
                 (replayOptions["sessionSampleRate"] as? NSNumber)?.floatValue ?? 0
             options.sessionReplay.onErrorSampleRate =
diff --git a/flutter/lib/sentry_flutter.dart b/flutter/lib/sentry_flutter.dart
@@ -9,6 +9,7 @@ export 'src/navigation/sentry_navigator_observer.dart';
 export 'src/sentry_flutter.dart';
 export 'src/sentry_flutter_options.dart';
 export 'src/sentry_replay_options.dart';
+export 'src/replay/replay_quality.dart';
 export 'src/sentry_privacy_options.dart';
 export 'src/flutter_sentry_attachment.dart';
 export 'src/sentry_asset_bundle.dart' show SentryAssetBundle;
diff --git a/flutter/lib/src/native/cocoa/cocoa_replay_recorder.dart b/flutter/lib/src/native/cocoa/cocoa_replay_recorder.dart
@@ -17,8 +17,12 @@ class CocoaReplayRecorder {
   var _completer = Completer<Map<String, int>?>();
 
   CocoaReplayRecorder(this._options)
-      : _recorder =
-            ReplayScreenshotRecorder(ScreenshotRecorderConfig(), _options) {
+      : _recorder = ReplayScreenshotRecorder(
+            ScreenshotRecorderConfig(
+              pixelRatio:
+                  _options.experimental.replay.quality.resolutionScalingFactor,
+            ),
+            _options) {
     _stabilizer = ScreenshotStabilizer(_recorder, _options, (screenshot) async {
       final data = await screenshot.rawRgbaData;
       _options.logger(
diff --git a/flutter/lib/src/native/sentry_native_channel.dart b/flutter/lib/src/native/sentry_native_channel.dart
@@ -69,6 +69,7 @@ class SentryNativeChannel
           options.appHangTimeoutInterval.inMilliseconds,
       if (options.proxy != null) 'proxy': options.proxy?.toJson(),
       'replay': <String, dynamic>{
+        'quality': options.experimental.replay.quality.name,
         'sessionSampleRate': options.experimental.replay.sessionSampleRate,
         'onErrorSampleRate': options.experimental.replay.onErrorSampleRate,
         // TMP: this doesn't actually mask, just ensures we show the correct
@@ -235,7 +236,6 @@ class SentryNativeChannel
         'width': config.width,
         'height': config.height,
         'frameRate': config.frameRate,
-        'bitRate': config.bitRate,
       });
 
   @override
diff --git a/flutter/lib/src/replay/integration.dart b/flutter/lib/src/replay/integration.dart
@@ -18,22 +18,22 @@ class ReplayIntegration extends Integration<SentryFlutterOptions> {
 
   @override
   FutureOr<void> call(Hub hub, SentryFlutterOptions options) {
-    if (_native.supportsReplay && options.experimental.replay.isEnabled) {
+    final replayOptions = options.experimental.replay;
+    if (_native.supportsReplay && replayOptions.isEnabled) {
       options.sdk.addIntegration(replayIntegrationName);
 
       // We only need the integration when error-replay capture is enabled.
-      if ((options.experimental.replay.onErrorSampleRate ?? 0) > 0) {
+      if ((replayOptions.onErrorSampleRate ?? 0) > 0) {
         options.addEventProcessor(ReplayEventProcessor(hub, _native));
       }
 
       SentryScreenshotWidget.onBuild((status, prevStatus) {
         if (status != prevStatus) {
           _native.setReplayConfig(ReplayConfig(
-            width: status.size?.width ?? 0.0,
-            height: status.size?.height ?? 0.0,
-            frameRate: 1,
-            bitRate: 75000, // TODO replay quality config
-          ));
+              width: replayOptions.quality.resolutionScalingFactor *
+                  (status.size?.width ?? 0.0),
+              height: replayOptions.quality.resolutionScalingFactor *
+                  (status.size?.height ?? 0.0)));
         }
         return true;
       });
diff --git a/flutter/lib/src/replay/replay_config.dart b/flutter/lib/src/replay/replay_config.dart
@@ -11,12 +11,9 @@ class ReplayConfig extends ScheduledScreenshotRecorderConfig {
   @override
   double get height => super.height!;
 
-  final int bitRate;
-
   const ReplayConfig({
     required double super.width,
     required double super.height,
-    required super.frameRate,
-    required this.bitRate,
+    super.frameRate = 1,
   });
 }
diff --git a/flutter/lib/src/replay/replay_quality.dart b/flutter/lib/src/replay/replay_quality.dart
@@ -0,0 +1,13 @@
+import 'package:meta/meta.dart';
+
+/// The quality of the captured replay.
+enum SentryReplayQuality {
+  high(resolutionScalingFactor: 1.0),
+  medium(resolutionScalingFactor: 1.0),
+  low(resolutionScalingFactor: 0.8);
+
+  @internal
+  final double resolutionScalingFactor;
+
+  const SentryReplayQuality({required this.resolutionScalingFactor});
+}
diff --git a/flutter/lib/src/screenshot/recorder_config.dart b/flutter/lib/src/screenshot/recorder_config.dart
@@ -6,17 +6,24 @@ import 'package:meta/meta.dart';
 class ScreenshotRecorderConfig {
   final double? width;
   final double? height;
+  final double? pixelRatio;
 
-  const ScreenshotRecorderConfig({
-    this.width,
-    this.height,
-  });
+  const ScreenshotRecorderConfig({this.width, this.height, this.pixelRatio});
 
   double? getPixelRatio(double srcWidth, double srcHeight) {
-    assert((width == null) == (height == null));
-    if (width == null || height == null) {
+    assert((width == null) == (height == null),
+        "Screenshot width and height must be both set or both null (automatic).");
+    assert(pixelRatio == null || (pixelRatio! > 0 && pixelRatio! <= 1.0),
+        'Screenshot pixelRatio must be between 0 and 1.');
+    assert(!(width != null && pixelRatio != null),
+        'Screenshot config may only define the size (width & height) or the pixelRatio, not both.');
+
+    if (pixelRatio != null) {
+      return pixelRatio;
+    } else if (width != null && height != null) {
+      return min(width! / srcWidth, height! / srcHeight);
+    } else {
       return null;
     }
-    return min(width! / srcWidth, height! / srcHeight);
   }
 }
diff --git a/flutter/lib/src/sentry_replay_options.dart b/flutter/lib/src/sentry_replay_options.dart
@@ -1,5 +1,7 @@
 import 'package:meta/meta.dart';
 
+import 'replay/replay_quality.dart';
+
 /// Configuration of the experimental replay feature.
 @experimental
 class SentryReplayOptions {
@@ -25,6 +27,11 @@ class SentryReplayOptions {
     _onErrorSampleRate = value;
   }
 
+  ///  Defines the image quality of the session replay. The higher the quality,
+  ///  the more accurate the replay will be, but also more data to transfer and
+  /// more CPU load, defaults to MEDIUM.
+  var quality = SentryReplayQuality.medium;
+
   @internal
   bool get isEnabled =>
       ((sessionSampleRate ?? 0) > 0) || ((onErrorSampleRate ?? 0) > 0);
diff --git a/flutter/test/integrations/init_native_sdk_test.dart b/flutter/test/integrations/init_native_sdk_test.dart
@@ -66,6 +66,7 @@ void main() {
       'readTimeoutMillis': 5000,
       'appHangTimeoutIntervalMillis': 2000,
       'replay': <String, dynamic>{
+        'quality': 'medium',
         'sessionSampleRate': null,
         'onErrorSampleRate': null,
         'maskAllText': true,
@@ -121,6 +122,7 @@ void main() {
         user: 'admin',
         pass: '0000',
       )
+      ..experimental.replay.quality = SentryReplayQuality.high
       ..experimental.replay.sessionSampleRate = 0.1
       ..experimental.replay.onErrorSampleRate = 0.2
       ..spotlight =
@@ -177,6 +179,7 @@ void main() {
         'pass': '0000',
       },
       'replay': <String, dynamic>{
+        'quality': 'high',
         'sessionSampleRate': 0.1,
         'onErrorSampleRate': 0.2,
         'maskAllText': true,
diff --git a/flutter/test/replay/replay_integration_test.dart b/flutter/test/replay/replay_integration_test.dart
@@ -84,9 +84,24 @@ void main() {
 
     final config = verify(native.setReplayConfig(captureAny)).captured.single
         as ReplayConfig;
-    expect(config.bitRate, 75000);
     expect(config.frameRate, 1);
     expect(config.width, 800);
     expect(config.height, 600);
   });
+
+  testWidgets('Adjusts resolution based on quality', (tester) async {
+    options.experimental.replay.sessionSampleRate = 1.0;
+    options.experimental.replay.quality = SentryReplayQuality.low;
+    when(native.setReplayConfig(any)).thenReturn(null);
+    sut.call(hub, options);
+
+    TestWidgetsFlutterBinding.ensureInitialized();
+    await pumpTestElement(tester);
+    await tester.pumpAndSettle(Duration(seconds: 1));
+
+    final config = verify(native.setReplayConfig(captureAny)).captured.single
+        as ReplayConfig;
+    expect(config.width, 640);
+    expect(config.height, 480);
+  });
 }
diff --git a/flutter/test/replay/replay_native_test.dart b/flutter/test/replay/replay_native_test.dart
@@ -33,14 +33,12 @@ void main() {
       late SentryFlutterOptions options;
       late MockHub hub;
       late FileSystem fs;
-      late Directory replayDir;
       late Map<String, dynamic> replayConfig;
 
       setUp(() {
         if (mockPlatform.isIOS) {
           replayConfig = {
             'replayId': '123',
-            'directory': 'dir',
           };
         } else if (mockPlatform.isAndroid) {
           replayConfig = {
@@ -55,15 +53,14 @@ void main() {
         hub = MockHub();
 
         fs = MemoryFileSystem.test();
-        replayDir = fs.directory(replayConfig['directory'])
-          ..createSync(recursive: true);
 
         native = NativeChannelFixture();
 
         options =
             defaultTestOptions(MockPlatformChecker(mockPlatform: mockPlatform))
               ..fileSystem = fs
-              ..methodChannel = native.channel;
+              ..methodChannel = native.channel
+              ..experimental.replay.quality = SentryReplayQuality.low;
 
         sut = createBinding(options);
       });
@@ -129,6 +126,9 @@ void main() {
 
             await pumpTestElement(tester);
             if (mockPlatform.isAndroid) {
+              final replayDir = fs.directory(replayConfig['directory'])
+                ..createSync(recursive: true);
+
               var callbackFinished = Completer<void>();
 
               nextFrame({bool wait = true}) async {
@@ -209,8 +209,8 @@ void main() {
 
                 expect(json['length'], greaterThan(3000));
                 expect(json['address'], greaterThan(0));
-                expect(json['width'], greaterThan(0));
-                expect(json['height'], greaterThan(0));
+                expect(json['width'], 640);
+                expect(json['height'], 480);
                 NativeMemory.fromJson(json).free();
               }
 
diff --git a/flutter/test/sentry_native_channel_test.dart b/flutter/test/sentry_native_channel_test.dart
@@ -331,16 +331,14 @@ void main() {
         when(channel.invokeMethod('setReplayConfig', any))
             .thenAnswer((_) => Future.value());
 
-        final config =
-            ReplayConfig(width: 1.1, height: 2.2, frameRate: 3, bitRate: 4);
+        final config = ReplayConfig(width: 1.1, height: 2.2, frameRate: 3);
         await sut.setReplayConfig(config);
 
         if (mockPlatform.isAndroid) {
           verify(channel.invokeMethod('setReplayConfig', {
             'width': config.width,
             'height': config.height,
             'frameRate': config.frameRate,
-            'bitRate': config.bitRate,
           }));
         } else {
           verifyNever(channel.invokeMethod('setReplayConfig', any));
diff --git a/flutter/test/web/sentry_web_test.dart b/flutter/test/web/sentry_web_test.dart
@@ -163,8 +163,7 @@ void main() {
           sut.pauseAppHangTracking();
           sut.setContexts('key', 'value');
           sut.setExtra('key', 'value');
-          sut.setReplayConfig(
-              ReplayConfig(width: 0, height: 0, frameRate: 0, bitRate: 0));
+          sut.setReplayConfig(ReplayConfig(width: 0, height: 0, frameRate: 0));
           sut.setTag('key', 'value');
           sut.setUser(null);
           sut.startProfiler(SentryId.empty());
