Updated on 2026-08-14

core/analytics/models/src/main/java/com/tangem/core/analytics/models/OneTimePerSessionEvent.kt

@@ -1,22 +1,32 @@
 package com.tangem.core.analytics.models
 
 /**
- * Marker interface for analytics events that should be sent only once per session.
+ * Marker interface for analytics events that can be throttled by session and/or time.
  *
- * Events implementing this interface will be tracked by their [oneTimeEventId] to ensure
- * they are not sent multiple times during the same application session. Once an event
- * with a specific [oneTimeEventId] has been sent, subsequent attempts to send an event
- * with the same ID will be ignored.
+ * Events implementing this interface will be tracked by their [oneTimeEventId].
+ *
+ * Behavior depends on [throttleSeconds]:
+ * - **null** (default): One time per session — event is sent only once during the application session.
+ * - **non-null**: Time-based throttling — event is not sent if less than [throttleSeconds] seconds
+ *   have passed since the last send for this [oneTimeEventId].
  *
  * @see Analytics.send
  */
 interface OneTimePerSessionEvent {
     /**
-     * Unique identifier for the one-time event.
+     * Unique identifier for the throttled event.
      *
-     * This ID is used to track whether the event has already been sent in the current session.
-     * Events with the same [oneTimeEventId] will only be sent once, even if they are
-     * different instances of the same event class.
+     * This ID is used to track whether and when the event was last sent.
+     * Events with the same [oneTimeEventId] share the same throttling state.
      */
     val oneTimeEventId: String
+
+    /**
+     * Minimum interval in seconds between sends for this event.
+     *
+     * - **null**: One time per session only. Event is sent at most once per session.
+     * - **non-null**: Don't send if less than this many seconds have passed since the last send.
+     */
+    val throttleSeconds: Long?
+        get() = null
 }