feat(core): Add rage tap detection with ui.frustration breadcrumbs (#5992)

alwx · web-flow · commit 9b6b2bacbfb4 · 2026-04-27T10:00:34.000Z
* feat(core): Add rage tap detection with ui.frustration breadcrumbs Detect rapid consecutive taps on the same UI element and surface them as frustration signals across the SDK: - New RageTapDetector class tracks recent taps in a circular buffer and matches them by component identity (label or name+file). When N taps on the same target occur within a configurable time window, a ui.frustration breadcrumb is emitted automatically. - TouchEventBoundary gains three new props: enableRageTapDetection (default: true), rageTapThreshold (default: 3), and rageTapTimeWindow (default: 1000ms). - Native replay breadcrumb converters on both Android (Java) and iOS (Objective-C) now handle the ui.frustration category, converting it to an RRWeb breadcrumb event so rage taps appear on the session replay timeline with the same touch-path message format as regular ui.tap events. - 7 new JS tests cover detection, threshold configuration, time window expiry, buffer reset, disabled mode, and component-name fallback. Android and iOS converter tests verify the new category is handled correctly. * test(core): Add tests for rage tap detection and replay converters - New ragetap.test.ts with 10 unit tests for RageTapDetector: threshold detection, different targets, time window expiry, buffer reset, disabled mode, custom threshold/timeWindow, component name+file identity, empty path, and consecutive rage tap triggers. - 3 integration tests in touchevents.test.tsx verifying TouchEventBoundary wires the detector correctly: end-to-end detection, disabled prop, and custom threshold/timeWindow props. - Android converter test (Kotlin) and iOS converter test (Swift) for the ui.frustration breadcrumb category in RNSentryReplayBreadcrumbConverter. * docs(changelog): Add entry for rage tap detection (#5992) * fix(core): Address review feedback for rage tap detection - Fix false-positive detection: reset tap buffer when target changes instead of relying on time-window pruning, which could make non-consecutive taps appear consecutive after interleaved taps aged out (Medium severity, reported by Sentry bugbot). - Add null check for breadcrumb data in Android convertFrustrationBreadcrumb, matching the iOS implementation that already guards against nil data (Low severity). - Remove hardcoded MAX_RECENT_TAPS buffer limit that would silently break detection for thresholds > 10. The buffer is now naturally bounded by target-change resets and time-window pruning. - Deduplicate TouchedComponentInfo: export from ragetap.ts and import in touchevents.tsx instead of maintaining identical interfaces in both files. - Read rage tap props at event time via updateOptions() instead of freezing them in the constructor, consistent with how all other TouchEventBoundary props are consumed. * refactor(core): Align rage tap detection with ui.multiClick convention Rename breadcrumb category from ui.frustration to ui.multiClick and reshape the data payload to match the web JS SDK's rage click format, so the Sentry replay timeline renders rage taps with the fire icon and 'Rage Click' label automatically. Changes to the breadcrumb shape: - category: ui.frustration → ui.multiClick - type: user → default - data.tapCount → data.clickCount - data.type (rage_tap) removed - data.metric: true added (marks as metric event) - data.route added (current screen from navigation tracing) - data.node added with DOM-compatible shape: tagName, textContent, attributes (data-sentry-component, data-sentry-source-file, sentry-label) — this allows the existing stringifyNodeAttributes in the Sentry frontend to render component names for mobile taps. Native replay converters updated on both Android and iOS to handle ui.multiClick instead of ui.frustration. * fix(core): Include component name in tap identity to prevent false positives When distinct child elements share a labeled ancestor, the tap identity was based solely on the parent label, causing false rage tap detection when tapping different controls in quick succession. Now the identity always includes the root component name and file, even when a label is present (e.g. label:form|name:SubmitButton|file:form.tsx). * fix(core): Address latest review feedback - iOS: Add NSArray type check on path data in convertMultiClick to prevent runtime crash from unrecognized selector on non-array values (HIGH, Sentry bot). - Clear tap buffer when detection is disabled via updateOptions to prevent stale taps from causing false positives on re-enable (LOW, Sentry bot). - Move changelog entry from released 8.8.0 section to Unreleased (danger bot). - Add time window integration test to touchevents that varies timestamps between taps, verifying rageTapTimeWindow actually excludes old taps (sentry-warden). * fix(core): Address antonis review feedback - Drop level: 'warning' from ui.multiClick breadcrumb to match the web JS SDK which defaults to info. - Export DEFAULT_RAGE_TAP_THRESHOLD and DEFAULT_RAGE_TAP_TIME_WINDOW from ragetap.ts and import them in touchevents.tsx defaultProps for a single source of truth. - Initialize RageTapDetector with props in the constructor and sync via componentDidUpdate, instead of calling updateOptions on every tap event. - Remove incorrect @testonly annotation from Android convertMultiClickBreadcrumb since it is called from convert() in production code. - Add comment explaining id: 0 placeholder in the node object (mobile replays don't have rrweb node IDs). - Add tests for updateOptions: buffer cleared on disable, and threshold change applies immediately. - Run yarn fix for import ordering lint. * fix(android): Check path is a List in convertMultiClickBreadcrumb Align with the iOS converter which validates the path type before use. Prevents potential ClassCastException if a non-list value is passed. * docs(changelog): Move rage tap entry to Unreleased section
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@
 ### Features
 
 - Add `includeWebFeedback` Metro config option to exclude `@sentry-internal/feedback` from the bundle ([#6025](https://github.com/getsentry/sentry-react-native/pull/6025))
+- Add rage tap detection — rapid consecutive taps on the same element emit `ui.multiClick` breadcrumbs and appear on the replay timeline with the rage click icon ([#5992](https://github.com/getsentry/sentry-react-native/pull/5992))
 
 ### Fixes
 
diff --git a/packages/core/RNSentryAndroidTester/app/src/test/java/io/sentry/rnsentryandroidtester/RNSentryReplayBreadcrumbConverterTest.kt b/packages/core/RNSentryAndroidTester/app/src/test/java/io/sentry/rnsentryandroidtester/RNSentryReplayBreadcrumbConverterTest.kt
@@ -90,6 +90,34 @@ class RNSentryReplayBreadcrumbConverterTest {
         assertEquals(null, actual)
     }
 
+    @Test
+    fun convertMultiClickBreadcrumb() {
+        val converter = RNSentryReplayBreadcrumbConverter()
+        val testBreadcrumb = Breadcrumb()
+        testBreadcrumb.level = SentryLevel.WARNING
+        testBreadcrumb.type = "default"
+        testBreadcrumb.category = "ui.multiClick"
+        testBreadcrumb.message = "Submit"
+        testBreadcrumb.setData(
+            "path",
+            arrayListOf(
+                mapOf(
+                    "name" to "SubmitButton",
+                    "label" to "Submit",
+                    "file" to "form.tsx",
+                ),
+            ),
+        )
+        testBreadcrumb.setData("clickCount", 3.0)
+        testBreadcrumb.setData("metric", true)
+        val actual = converter.convert(testBreadcrumb) as RRWebBreadcrumbEvent
+
+        assertRRWebBreadcrumbDefaults(actual)
+        assertEquals(SentryLevel.WARNING, actual.level)
+        assertEquals("ui.multiClick", actual.category)
+        assertEquals("Submit(form.tsx)", actual.message)
+    }
+
     @Test
     fun convertTouchBreadcrumb() {
         val converter = RNSentryReplayBreadcrumbConverter()
diff --git a/packages/core/RNSentryCocoaTester/RNSentryCocoaTesterTests/RNSentryReplayBreadcrumbConverterTests.swift b/packages/core/RNSentryCocoaTester/RNSentryCocoaTesterTests/RNSentryReplayBreadcrumbConverterTests.swift
@@ -100,6 +100,33 @@ final class RNSentryReplayBreadcrumbConverterTests: XCTestCase {
         XCTAssertNil(actual)
     }
 
+    func testConvertMultiClickBreadcrumb() {
+        let converter = RNSentryReplayBreadcrumbConverter()
+        let testBreadcrumb = Breadcrumb()
+        testBreadcrumb.timestamp = Date()
+        testBreadcrumb.level = .warning
+        testBreadcrumb.type = "default"
+        testBreadcrumb.category = "ui.multiClick"
+        testBreadcrumb.message = "Submit"
+        testBreadcrumb.data = [
+            "path": [
+                ["name": "SubmitButton", "label": "Submit", "file": "form.tsx"]
+            ],
+            "clickCount": 3,
+            "metric": true
+        ]
+        let actual = converter.convert(from: testBreadcrumb)
+
+        XCTAssertNotNil(actual)
+        let event = actual!.serialize()
+        let data = event["data"] as! [String: Any?]
+        let payload = data["payload"] as! [String: Any?]
+        assertRRWebBreadcrumbDefaults(actual: event)
+        XCTAssertEqual("warning", payload["level"] as! String)
+        XCTAssertEqual("ui.multiClick", payload["category"] as! String)
+        XCTAssertEqual("Submit(form.tsx)", payload["message"] as! String)
+    }
+
     func testConvertTouchBreadcrumb() {
         let converter = RNSentryReplayBreadcrumbConverter()
         let testBreadcrumb = Breadcrumb()
diff --git a/packages/core/android/src/main/java/io/sentry/react/RNSentryReplayBreadcrumbConverter.java b/packages/core/android/src/main/java/io/sentry/react/RNSentryReplayBreadcrumbConverter.java
@@ -32,6 +32,9 @@ public final class RNSentryReplayBreadcrumbConverter extends DefaultReplayBreadc
     if ("touch".equals(breadcrumb.getCategory())) {
       return convertTouchBreadcrumb(breadcrumb);
     }
+    if ("ui.multiClick".equals(breadcrumb.getCategory())) {
+      return convertMultiClickBreadcrumb(breadcrumb);
+    }
     if ("navigation".equals(breadcrumb.getCategory())) {
       return convertNavigationBreadcrumb(breadcrumb);
     }
@@ -72,6 +75,21 @@ public final class RNSentryReplayBreadcrumbConverter extends DefaultReplayBreadc
     return rrWebBreadcrumb;
   }
 
+  public @Nullable RRWebEvent convertMultiClickBreadcrumb(final @NotNull Breadcrumb breadcrumb) {
+    if (!(breadcrumb.getData("path") instanceof List)) {
+      return null;
+    }
+
+    final RRWebBreadcrumbEvent rrWebBreadcrumb = new RRWebBreadcrumbEvent();
+
+    rrWebBreadcrumb.setCategory("ui.multiClick");
+
+    rrWebBreadcrumb.setMessage(getTouchPathMessage(breadcrumb.getData("path")));
+
+    setRRWebEventDefaultsFrom(rrWebBreadcrumb, breadcrumb);
+    return rrWebBreadcrumb;
+  }
+
   @TestOnly
   public static @Nullable String getTouchPathMessage(final @Nullable Object maybePath) {
     if (!(maybePath instanceof List)) {
diff --git a/packages/core/ios/RNSentryReplayBreadcrumbConverter.m b/packages/core/ios/RNSentryReplayBreadcrumbConverter.m
@@ -35,6 +35,10 @@ - (instancetype _Nonnull)init
         return [self convertTouch:breadcrumb];
     }
 
+    if ([breadcrumb.category isEqualToString:@"ui.multiClick"]) {
+        return [self convertMultiClick:breadcrumb];
+    }
+
     if ([breadcrumb.category isEqualToString:@"navigation"]) {
         return [SentrySessionReplayHybridSDK createBreadcrumbwithTimestamp:breadcrumb.timestamp
                                                                   category:breadcrumb.category
@@ -75,6 +79,26 @@ - (instancetype _Nonnull)init
                                                                   data:breadcrumb.data];
 }
 
+- (id<SentryRRWebEvent> _Nullable)convertMultiClick:(SentryBreadcrumb *_Nonnull)breadcrumb
+{
+    if (breadcrumb.data == nil) {
+        return nil;
+    }
+
+    id maybePath = [breadcrumb.data valueForKey:@"path"];
+    if (![maybePath isKindOfClass:[NSArray class]]) {
+        return nil;
+    }
+
+    NSString *message = [RNSentryReplayBreadcrumbConverter getTouchPathMessageFrom:maybePath];
+
+    return [SentrySessionReplayHybridSDK createBreadcrumbwithTimestamp:breadcrumb.timestamp
+                                                              category:@"ui.multiClick"
+                                                               message:message
+                                                                 level:breadcrumb.level
+                                                                  data:breadcrumb.data];
+}
+
 + (NSString *_Nullable)getTouchPathMessageFrom:(NSArray *_Nullable)path
 {
     if (path == nil) {
diff --git a/packages/core/src/js/ragetap.ts b/packages/core/src/js/ragetap.ts
@@ -0,0 +1,190 @@
+import { addBreadcrumb, debug } from '@sentry/core';
+
+import { getCurrentReactNativeTracingIntegration } from './tracing/reactnativetracing';
+
+export const DEFAULT_RAGE_TAP_THRESHOLD = 3;
+export const DEFAULT_RAGE_TAP_TIME_WINDOW = 1000;
+
+export interface TouchedComponentInfo {
+  name?: string;
+  label?: string;
+  element?: string;
+  file?: string;
+}
+
+export interface RageTapDetectorOptions {
+  enabled: boolean;
+  threshold: number;
+  timeWindow: number;
+}
+
+interface RecentTap {
+  identity: string;
+  timestamp: number;
+}
+
+/**
+ * Detects rage taps (repeated rapid taps on the same target) and emits
+ * `ui.multiClick` breadcrumbs when the threshold is hit.
+ *
+ * Uses the same breadcrumb category and data shape as the web JS SDK's
+ * rage click detection so the Sentry replay timeline renders the fire
+ * icon and "Rage Click" label automatically.
+ */
+export class RageTapDetector {
+  private _recentTaps: RecentTap[] = [];
+  private _enabled: boolean;
+  private _threshold: number;
+  private _timeWindow: number;
+
+  public constructor(options?: Partial<RageTapDetectorOptions>) {
+    this._enabled = options?.enabled ?? true;
+    this._threshold = options?.threshold ?? DEFAULT_RAGE_TAP_THRESHOLD;
+    this._timeWindow = options?.timeWindow ?? DEFAULT_RAGE_TAP_TIME_WINDOW;
+  }
+
+  /**
+   * Update options at runtime (e.g. when React props change).
+   */
+  public updateOptions(options: Partial<RageTapDetectorOptions>): void {
+    if (options.enabled !== undefined) {
+      this._enabled = options.enabled;
+      if (!this._enabled) {
+        this._recentTaps = [];
+      }
+    }
+    if (options.threshold !== undefined) {
+      this._threshold = options.threshold;
+    }
+    if (options.timeWindow !== undefined) {
+      this._timeWindow = options.timeWindow;
+    }
+  }
+
+  /**
+   * Call after each touch event. If a rage tap is detected, a `ui.multiClick`
+   * breadcrumb is emitted automatically.
+   */
+  public check(touchPath: TouchedComponentInfo[], label?: string): void {
+    if (!this._enabled) {
+      return;
+    }
+
+    const root = touchPath[0];
+    if (!root) {
+      return;
+    }
+
+    const identity = getTapIdentity(root, label);
+    const now = Date.now();
+    const tapCount = this._detect(identity, now);
+
+    if (tapCount > 0) {
+      const message = buildTouchMessage(root, label);
+      const node = buildNodeFromTouchPath(root, label);
+
+      addBreadcrumb({
+        category: 'ui.multiClick',
+        type: 'default',
+        message,
+        data: {
+          clickCount: tapCount,
+          metric: true,
+          route: getCurrentRoute(),
+          node,
+          path: touchPath,
+        },
+      });
+
+      debug.log(`[TouchEvents] Rage tap detected: ${tapCount} taps on ${message}`);
+    }
+  }
+
+  /**
+   * Returns the tap count if rage tap is detected, 0 otherwise.
+   */
+  private _detect(identity: string, now: number): number {
+    // If the target changed, reset the buffer — only truly consecutive
+    // taps on the same target count. This prevents false positives where
+    // time-window pruning removes interleaved taps on other targets.
+    const lastTap = this._recentTaps[this._recentTaps.length - 1];
+    if (lastTap && lastTap.identity !== identity) {
+      this._recentTaps = [];
+    }
+
+    this._recentTaps.push({ identity, timestamp: now });
+
+    // Prune taps outside the time window
+    const cutoff = now - this._timeWindow;
+    this._recentTaps = this._recentTaps.filter(tap => tap.timestamp >= cutoff);
+
+    if (this._recentTaps.length >= this._threshold) {
+      const count = this._recentTaps.length;
+      this._recentTaps = [];
+      return count;
+    }
+
+    return 0;
+  }
+}
+
+function getTapIdentity(root: TouchedComponentInfo, label?: string): string {
+  const base = `name:${root.name ?? ''}|file:${root.file ?? ''}`;
+  if (label) {
+    return `label:${label}|${base}`;
+  }
+  return base;
+}
+
+/**
+ * Build a human-readable message matching the touch breadcrumb format.
+ */
+function buildTouchMessage(root: TouchedComponentInfo, label?: string): string {
+  if (label) {
+    return label;
+  }
+  return `${root.name}${root.file ? ` (${root.file})` : ''}`;
+}
+
+/**
+ * Build a node object compatible with the web SDK's `ReplayBaseDomFrameData`
+ * so that `stringifyNodeAttributes` in the Sentry frontend can render it.
+ *
+ * Maps the React Native component info to the DOM-like shape:
+ * - `tagName` → element type (e.g. "RCTView") or component name
+ * - `attributes['data-sentry-component']` → component name from babel plugin
+ * - `attributes['data-sentry-source-file']` → source file
+ */
+function buildNodeFromTouchPath(
+  root: TouchedComponentInfo,
+  label?: string,
+): { id: number; tagName: string; textContent: string; attributes: Record<string, string> } {
+  const attributes: Record<string, string> = {};
+
+  if (root.name) {
+    attributes['data-sentry-component'] = root.name;
+  }
+  if (root.file) {
+    attributes['data-sentry-source-file'] = root.file;
+  }
+  if (label) {
+    attributes['sentry-label'] = label;
+  }
+
+  return {
+    // Mobile replays don't have rrweb node IDs — 0 is a placeholder
+    // to satisfy the ReplayBaseDomFrameData shape expected by the frontend.
+    id: 0,
+    tagName: root.element ?? root.name ?? 'unknown',
+    textContent: '',
+    attributes,
+  };
+}
+
+function getCurrentRoute(): string | undefined {
+  try {
+    return getCurrentReactNativeTracingIntegration()?.state.currentRoute;
+  } catch {
+    return undefined;
+  }
+}
diff --git a/packages/core/src/js/touchevents.tsx b/packages/core/src/js/touchevents.tsx
diff --git a/packages/core/test/ragetap.test.ts b/packages/core/test/ragetap.test.ts
diff --git a/packages/core/test/touchevents.test.tsx b/packages/core/test/touchevents.test.tsx
