chore: change screenshots debouncing approach to throttling

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## Next
 
+- chore: change screenshots debouncing approach to throttling ([#214](https://github.com/PostHog/posthog-flutter/pull/214))
+  - Added `throttleDelayMs` config and deprecated `debouncerDelayMs` config.
+
 ## 3.9.3 - 2024-11-26
 
 - no user facing changes

posthog-android/api/posthog-android.api

@@ -74,19 +74,22 @@ public final class com/posthog/android/replay/PostHogSessionReplayConfig {
 	public fun <init> (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;)V
 	public fun <init> (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;Z)V
 	public fun <init> (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJ)V
-	public synthetic fun <init> (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJJ)V
+	public synthetic fun <init> (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJJILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun getCaptureLogcat ()Z
 	public final fun getDebouncerDelayMs ()J
 	public final fun getDrawableConverter ()Lcom/posthog/android/replay/PostHogDrawableConverter;
 	public final fun getMaskAllImages ()Z
 	public final fun getMaskAllTextInputs ()Z
 	public final fun getScreenshot ()Z
+	public final fun getThrottleDelayMs ()J
 	public final fun setCaptureLogcat (Z)V
 	public final fun setDebouncerDelayMs (J)V
 	public final fun setDrawableConverter (Lcom/posthog/android/replay/PostHogDrawableConverter;)V
 	public final fun setMaskAllImages (Z)V
 	public final fun setMaskAllTextInputs (Z)V
 	public final fun setScreenshot (Z)V
+	public final fun setThrottleDelayMs (J)V
 }
 
 public class com/posthog/android/replay/internal/LogLine {

posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt

@@ -145,7 +145,7 @@ public class PostHogReplayIntegration(
                                     decorView.onNextDraw(
                                         mainHandler,
                                         config.dateProvider,
-                                        config.sessionReplayConfig.debouncerDelayMs,
+                                        config.sessionReplayConfig.throttleDelayMs,
                                     ) {
                                         if (!isSessionReplayEnabled || !isNativeSdk) {
                                             return@onNextDraw

posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt

@@ -45,6 +45,22 @@ public class PostHogSessionReplayConfig
          * Defaults to 1000ms = 1s
          * Ps: it was 500ms by default until version 3.8.2
          */
-        @PostHogExperimental
+        @Deprecated("Use throttleDelayMs instead")
         public var debouncerDelayMs: Long = 1000,
-    )
+        /**
+         * Throttling delay used to reduce the number of snapshots captured and reduce performance impact
+         * This is used for capturing the view as a wireframe or screenshot
+         * The lower the number more snapshots will be captured but higher the performance impact
+         * Defaults to 1000ms = 1s
+         */
+        @PostHogExperimental
+        public var throttleDelayMs: Long = 1000,
+    ) {
+        init {
+            // for keeping back compatibility
+            @Suppress("DEPRECATION")
+            if (debouncerDelayMs != 1000L) {
+                throttleDelayMs = debouncerDelayMs
+            }
+        }
+    }

posthog-android/src/main/java/com/posthog/android/replay/internal/NextDrawListener.kt

@@ -11,10 +11,10 @@ internal class NextDrawListener(
     private val view: View,
     mainHandler: MainHandler,
     dateProvider: PostHogDateProvider,
-    debouncerDelayMs: Long,
+    throttleDelayMs: Long,
     private val onDrawCallback: () -> Unit,
 ) : ViewTreeObserver.OnDrawListener {
-    private val debounce = Debouncer(mainHandler, dateProvider, debouncerDelayMs)
+    private val debounce = Throttler(mainHandler, dateProvider, throttleDelayMs)
 
     override fun onDraw() {
         debounce.debounce {
@@ -33,10 +33,10 @@ internal class NextDrawListener(
         internal fun View.onNextDraw(
             mainHandler: MainHandler,
             dateProvider: PostHogDateProvider,
-            debouncerDelayMs: Long,
+            throttleDelayMs: Long,
             onDrawCallback: () -> Unit,
         ): NextDrawListener {
-            val nextDrawListener = NextDrawListener(this, mainHandler, dateProvider, debouncerDelayMs, onDrawCallback)
+            val nextDrawListener = NextDrawListener(this, mainHandler, dateProvider, throttleDelayMs, onDrawCallback)
             nextDrawListener.safelyRegisterForNextDraw()
             return nextDrawListener
         }

posthog-android/src/main/java/com/posthog/android/replay/internal/Debouncer.kt → posthog-android/src/main/java/com/posthog/android/replay/internal/Throttler.kt

@@ -5,37 +5,36 @@ import com.posthog.internal.PostHogDateProvider
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.atomic.AtomicBoolean
 
-internal class Debouncer(
+internal class Throttler(
     private val mainHandler: MainHandler,
     private val dateProvider: PostHogDateProvider,
-    private val debouncerDelayMs: Long,
+    private val throttleDelayMs: Long,
 ) {
     private var lastCall = 0L
-    private val delayNs = TimeUnit.MILLISECONDS.toNanos(debouncerDelayMs)
-    private val hasPendingRunnable = AtomicBoolean(false)
+    private val delayNs = TimeUnit.MILLISECONDS.toNanos(throttleDelayMs)
+    private val isThrottling = AtomicBoolean(false)
 
     /**
      * Debounces the given [runnable] by delaying its execution until [delayNs] has passed since the last call.
      */
     internal fun debounce(runnable: Runnable) {
-        if (lastCall == 0L) {
-            lastCall = dateProvider.nanoTime()
-        }
+        val currentTime = dateProvider.nanoTime()
 
-        val timePassedSinceLastExecution = dateProvider.nanoTime() - lastCall
-        if (timePassedSinceLastExecution >= delayNs) {
-            if (!hasPendingRunnable.get()) {
-                execute(runnable)
-            }
+        // Check if enough time has passed since the last execution
+        val timeSinceLastExecution = currentTime - lastCall
+        if (timeSinceLastExecution >= delayNs) {
+            // Execute immediately if enough time has passed
+            execute(runnable)
         } else {
-            if (!hasPendingRunnable.getAndSet(true)) {
+            // If already throttling, ignore additional calls
+            if (!isThrottling.getAndSet(true)) {
                 mainHandler.handler.postDelayed({
                     try {
                         execute(runnable)
                     } finally {
-                        hasPendingRunnable.set(false)
+                        isThrottling.set(false) // Reset throttling after delay
                     }
-                }, debouncerDelayMs)
+                }, throttleDelayMs)
             }
         }
     }