chore: change screenshots debouncing approach to throttling

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Next
 
+## 4.8.0
+
+- chore: change screenshots debouncing approach to throttling ([#131](https://github.com/PostHog/posthog-flutter/pull/131))
+  - Added `throttleDelay` config and deprecated `debouncerDelay` config.
+
 ## 4.7.1
 
 - chore: do not send repeated snapshots ([#126](https://github.com/PostHog/posthog-flutter/pull/126))

example/lib/main.dart

@@ -14,8 +14,7 @@ Future<void> main() async {
   config.sessionReplay = true;
   config.sessionReplayConfig.maskAllTexts = false;
   config.sessionReplayConfig.maskAllImages = false;
-  config.sessionReplayConfig.debouncerDelay =
-      const Duration(milliseconds: 1000);
+  config.sessionReplayConfig.throttleDelay = const Duration(milliseconds: 1000);
   config.flushAt = 1;
   await Posthog().setup(config);
 

lib/src/posthog_config.dart

@@ -67,17 +67,29 @@ class PostHogSessionReplayConfig {
   /// Default: true.
   var maskAllImages = true;
 
+  /// Note: Deprecated in favor of [throttleDelay] from v4.8.0.
+  /// The value assigned to this var will be forwarded to [throttleDelay]
+  ///
   /// Debouncer delay used to reduce the number of snapshots captured and reduce performance impact.
   /// This is used for capturing the view as a screenshot.
   /// The lower the number, the more snapshots will be captured but higher the performance impact.
   /// Defaults to 1s.
-  var debouncerDelay = const Duration(seconds: 1);
+  set debouncerDelay(Duration debouncerDelay) {
+    throttleDelay = debouncerDelay;
+  }
+
+  /// Debouncer delay used to reduce the number of snapshots captured and reduce performance impact.
+  /// This is used for capturing the view as a screenshot.
+  /// The lower the number, the more snapshots will be captured but higher the performance impact.
+  /// Experimental support.
+  /// Defaults to 1s.
+  var throttleDelay = const Duration(seconds: 1);
 
   Map<String, dynamic> toMap() {
     return {
       'maskAllImages': maskAllImages,
       'maskAllTexts': maskAllTexts,
-      'debouncerDelayMs': debouncerDelay.inMilliseconds,
+      'throttleDelayMs': throttleDelay.inMilliseconds,
     };
   }
 }

lib/src/posthog_widget_widget.dart

@@ -23,8 +23,9 @@ class PostHogWidgetState extends State<PostHogWidget> {
   ScreenshotCapturer? _screenshotCapturer;
   NativeCommunicator? _nativeCommunicator;
 
-  Timer? _debounceTimer;
-  Duration _debounceDuration = const Duration(milliseconds: 1000);
+  Timer? _throttleTimer;
+  bool _isThrottling = false;
+  Duration _throttleDuration = const Duration(milliseconds: 1000);
 
   @override
   void initState() {
@@ -35,7 +36,7 @@ class PostHogWidgetState extends State<PostHogWidget> {
       return;
     }
 
-    _debounceDuration = config.sessionReplayConfig.debouncerDelay;
+    _throttleDuration = config.sessionReplayConfig.throttleDelay;
 
     _screenshotCapturer = ScreenshotCapturer(config);
     _nativeCommunicator = NativeCommunicator();
@@ -46,10 +47,20 @@ class PostHogWidgetState extends State<PostHogWidget> {
 
   // This works as onRootViewsChangedListeners
   void _onChangeDetected() {
-    _debounceTimer?.cancel();
+    if (_isThrottling) {
+      // If throttling is active, ignore this call
+      return;
+    }
+
+    // Start throttling
+    _isThrottling = true;
+
+    // Execute the snapshot generation
+    _generateSnapshot();
 
-    _debounceTimer = Timer(_debounceDuration, () {
-      _generateSnapshot();
+    // Reset throttling after the duration
+    _throttleTimer = Timer(_throttleDuration, () {
+      _isThrottling = false;
     });
   }
 
@@ -91,8 +102,8 @@ class PostHogWidgetState extends State<PostHogWidget> {
 
   @override
   void dispose() {
-    _debounceTimer?.cancel();
-    _debounceTimer = null;
+    _throttleTimer?.cancel();
+    _throttleTimer = null;
     _changeDetector?.stop();
     _changeDetector = null;
     _screenshotCapturer = null;