@scalebun/react-native 1.13.0 → 2.0.1

package/src/features/navigation/AutoScreenDetector.ts

@@ -49,6 +49,15 @@ export class AutoScreenDetector {
     private _manualScreen: string | null = null;
     private _manualScreenTs = 0;
     private _autoScreen: string | null = null;
+    /**
+     * When `_autoScreen` was last written.
+     *
+     * Needed so `getCurrentScreen()` can prefer whichever source spoke MOST RECENTLY.
+     * Without a timestamp the only comparison available was "is the manual value still
+     * fresh", which is a different question and gave the wrong answer — see the note on
+     * `_currentScreen()`.
+     */
+    private _autoScreenTs = 0;
     /** `name#key` of the last auto-detected screen VISIT — see _extractActiveVisit. */
     private _autoVisitSig: string | null = null;
     private _navigationRef: any = null;
@@ -124,6 +133,7 @@ export class AutoScreenDetector {
             if (this.isManualScreenActive()) return;
             if (name !== this._autoScreen) {
                 this._autoScreen = name;
+                this._autoScreenTs = Date.now();
                 this._autoVisitSig = name; // native lifecycle carries no route key — name-only visit
                 this._emitScreenChange(name, 'heuristic');
             }
@@ -131,8 +141,19 @@ export class AutoScreenDetector {
     }
 
     /**
-     * Check if a manual screen is currently active.
-     * Used by auto-detection to yield to manual overrides.
+     * Should a WRITER defer to the manual screen right now?
+     *
+     * THIS IS A PRECEDENCE GATE, NOT A VALIDITY TEST, and conflating the two was a real
+     * bug. Its job is what the cooldown constant says: for a short window after a manual
+     * beacon fires, an auto source must not overwrite it — the poller runs every 1500 ms
+     * and would otherwise clobber a fresh declaration with whatever it inferred.
+     *
+     * `getCurrentScreen()` used to reuse this as "is the manual screen still the current
+     * screen", which made a declared screen READABLE for only 2000 ms. Nothing called
+     * `setManualScreen` in production, so the effect was latent — but the moment the
+     * `<ScaleBunScreen>` beacon was wired to it (RN-8), every tap more than two seconds
+     * after a screen mounted would have lost its name, which is very nearly every tap. A
+     * fix that introduced that would have been worse than the gap it closed.
      */
     isManualScreenActive(): boolean {
         if (!this._manualScreen) return false;
@@ -196,6 +217,7 @@ export class AutoScreenDetector {
                                     const visit = this._extractActiveVisit(state);
                                     if (visit && this._visitSig(visit) !== this._autoVisitSig) {
                                         this._autoScreen = visit.name;
+                        this._autoScreenTs = Date.now();
                                         this._autoVisitSig = this._visitSig(visit);
                                         this._emitScreenChange(visit.name, 'navRef');
                                     }
@@ -216,6 +238,7 @@ export class AutoScreenDetector {
                     const visit = this._extractActiveVisit(state);
                     if (visit) {
                         this._autoScreen = visit.name;
+                        this._autoScreenTs = Date.now();
                         this._autoVisitSig = this._visitSig(visit);
                         this._emitScreenChange(visit.name, 'navRef');
                     }
@@ -261,6 +284,7 @@ export class AutoScreenDetector {
                         const visit = this._extractActiveVisit(state);
                         if (visit && this._visitSig(visit) !== this._autoVisitSig) {
                             this._autoScreen = visit.name;
+                        this._autoScreenTs = Date.now();
                             this._autoVisitSig = this._visitSig(visit);
                             this._emitScreenChange(visit.name, 'heuristic');
                         }
@@ -517,16 +541,52 @@ export class AutoScreenDetector {
         this._listeners = [];
         this._manualScreen = null;
         this._autoScreen = null;
+        this._autoScreenTs = 0;
         this._navigationRef = null;
         _instance = null;
     }
 
     /** Get the current best-known screen name */
     getCurrentScreen(): string | null {
-        if (this._manualScreen && this.isManualScreenActive()) {
-            return this._manualScreen;
+        return this._currentScreen().name;
+    }
+
+    /**
+     * WHERE the current screen name came from, or 'none'.
+     *
+     * Recorded on every interaction (RN-8) so low screen coverage is DIAGNOSABLE rather
+     * than merely visible. Production shows 13.8% of Android interactions carrying a
+     * screen and 0.5% on iOS, and those numbers cannot today distinguish three different
+     * causes: the app never instrumented anything, the app instrumented manually and the
+     * value never reached interactions, or auto-detection ran and failed. Those have
+     * different owners and different fixes, and guessing between them is how a P0 stays
+     * open.
+     */
+    getCurrentScreenSource(): 'manual' | 'navigation' | 'none' {
+        return this._currentScreen().source;
+    }
+
+    /**
+     * LAST WRITER WINS between the manual beacon and auto-detection.
+     *
+     * A screen declared by `<ScaleBunScreen name>` stays current until something else
+     * declares a different one — that is what mounting a screen means. It does not
+     * expire, which is the correction here: the previous rule returned the manual name
+     * only while it was under 2000 ms old and then silently fell back to the auto value,
+     * which in a manually-instrumented app is `null`.
+     *
+     * Comparing timestamps rather than hard-coding a priority also handles the real
+     * interleaving: an app can use React Navigation for most screens AND drop a manual
+     * beacon on one modal, and whichever spoke last is the truth.
+     */
+    private _currentScreen(): { name: string | null; source: 'manual' | 'navigation' | 'none' } {
+        const manual = this._manualScreen;
+        const auto = this._autoScreen;
+        if (manual && (!auto || this._manualScreenTs >= this._autoScreenTs)) {
+            return { name: manual, source: 'manual' };
         }
-        return this._autoScreen;
+        if (auto) return { name: auto, source: 'navigation' };
+        return { name: null, source: 'none' };
     }
 
     // ─── Internal ───────────────────────────────────────────────────────

package/src/features/network/NetworkFeature.ts

@@ -25,6 +25,7 @@
 
 import type { IFeature, FeatureContext } from '../../core/contracts/IFeature';
 import { installNetworkMonitoring, type NetworkMonitoringOptions } from './index';
+import { isThirdPartyBeacon } from './thirdParty';
 import { reportNetworkRequest } from '../replay/integrations/network/networkAdapter';
 import { SessionManager } from '../session/SessionManager';
 import { getTrackedScreen } from '../../debug/screenTracking';
@@ -53,13 +54,32 @@ export class NetworkFeature implements IFeature {
             // self-capture loop. Apply the SAME isSdkInternalUrl filter the replay
             // branch below already uses so genuine app requests still flow through.
             const isInternal = isSdkInternalUrl(data.url, this.options.sdkBaseUrl);
+            /**
+             * Beacons and denied URLs leave NO trace, in any lane.
+             *
+             * A network request reaches three places from here: the analytics echo
+             * (`$network_request`), the local replay pipeline, and the backend network endpoint
+             * that becomes the `network_requests` row the session panel renders. Filtering one
+             * and not the others is how a request half-disappears and two counts of the same
+             * call stop agreeing -- so this is applied to all three.
+             *
+             * Kept separate from `isInternal` rather than folded into it: the SDK's own uploads
+             * are already excluded from two of the three lanes and DELIBERATELY still reach the
+             * local replay pipeline. Widening that here would be an unrelated behaviour change
+             * riding along on a filter.
+             */
+            const isBeaconOrDenied =
+                (this.options.captureThirdParty !== true &&
+                    isThirdPartyBeacon(data.url, this.options.thirdPartyHosts)) ||
+                matchesDenyUrl(data.url, this.options.denyUrls);
+            const isExcluded = isInternal || isBeaconOrDenied;
 
-            if (!isInternal) {
+            if (!isExcluded) {
                 this.trackFn('$network_request', data);
             }
 
             // Bridge the raw network event into the Session Replay pipeline
-            if (data.type === 'network') {
+            if (data.type === 'network' && !isBeaconOrDenied) {
                 reportNetworkRequest({
                     method: data.method,
                     url: data.url,
@@ -82,8 +102,10 @@ export class NetworkFeature implements IFeature {
                 // (correlated by sessionId+timestamp), so we no longer emit
                 // NETWORK_REQUEST_* replay events here (that produced duplicate rows
                 // and count divergence between replay_events and network_requests).
-                // Skip SDK's own upload calls to prevent recursive event spam.
-                if (!isInternal) {
+                // Skip SDK's own upload calls to prevent recursive event spam, and anything the
+                // beacon/denyUrls filter excluded -- this is the lane that becomes the
+                // network_requests row a person sees on the session panel.
+                if (!isExcluded) {
                     const sessionManager = SessionManager.getExistingInstance();
                     if (sessionManager) {
                         const backendTransport = sessionManager.getBackendTransport();
@@ -119,6 +141,21 @@ export class NetworkFeature implements IFeature {
     }
 }
 
+/**
+ * Substring or RegExp, the same rule as the web SDK's `matchUrl`.
+ *
+ * Spelled out rather than shared because the two SDKs have no common runtime package, and the
+ * rule is two lines. What must NOT differ is the beacon list, which is why that one is a
+ * byte-identical vendored copy with a hash gate rather than a retyped constant.
+ */
+function matchesDenyUrl(url: string, patterns?: (string | RegExp)[]): boolean {
+    if (!patterns || !patterns.length || !url) return false;
+    for (const p of patterns) {
+        if (typeof p === 'string' ? url.includes(p) : p.test(url)) return true;
+    }
+    return false;
+}
+
 // Returns true if the URL is a ScaleBun SDK internal endpoint that must not be
 // captured — doing so would cause recursive network event spam.
 function isSdkInternalUrl(url: string, sdkBaseUrl?: string): boolean {

package/src/features/network/index.ts

@@ -18,6 +18,24 @@ export interface NetworkMonitoringOptions {
     redactNetwork?: boolean;
     /** SDK backend base URL — used to filter out SDK's own upload calls from capture */
     sdkBaseUrl?: string;
+    /**
+     * Never capture requests whose URL matches (substring or RegExp).
+     *
+     * Parity with the web SDK, which has had this since F-NET. Mobile had no way to exclude a
+     * URL at all, so an app that wanted one endpoint out of its replays had no answer.
+     */
+    denyUrls?: (string | RegExp)[];
+    /**
+     * Keep known telemetry beacons: analytics collectors, ad pixels, IP-enrichment calls.
+     *
+     * Default false — they are dropped before capture. They are not the app, they cost the
+     * device real battery and cellular data to upload, and a beacon that fails counts against
+     * the SESSION HEALTH score. Matching is by hostname only, never by path, so an app route
+     * called /collect is never touched. See features/network/thirdParty.ts.
+     */
+    captureThirdParty?: boolean;
+    /** Replace the built-in beacon host list wholesale. Comma-joined hostname suffixes. */
+    thirdPartyHosts?: string;
 }
 
 export function installNetworkMonitoring(

package/src/features/network/thirdParty.ts

@@ -0,0 +1,92 @@
+/**
+ * THIRD-PARTY BEACON HOSTS — the one list, and the one matcher, for every layer that drops them.
+ *
+ * WHAT THIS IS FOR
+ * A session on an instrumented site spends most of its network tab on traffic the app did not
+ * meaningfully make: analytics collectors, ad pixels, IP-enrichment calls, tag managers. It is
+ * captured, uploaded, stored and rendered, and none of it answers a question anyone asks a session
+ * replay. One real sign-in screen was 27 requests, most of them beacons.
+ *
+ * It is not only clutter. Session health scores `failedRequests` and `slowRequests`, so a tracker
+ * killed by an ad blocker (a transport error) or one that is simply slow moves a number that is
+ * supposed to describe the APP. That is the part that makes this a correctness fix rather than a
+ * tidy-up.
+ *
+ * WHY HOSTS ONLY, NEVER PATHS
+ * The obvious rules from looking at a network tab are `/collect`, `/p`, `/api/v2/pixel`. Every one
+ * of them is a path that a customer's own API is allowed to have, and dropping a real API call is
+ * far worse than keeping a beacon: the noise is visible and annoying, the missing request is
+ * invisible and misleading. So matching is on the HOSTNAME, with a dot boundary, and a request to
+ * `/collect` on the app's own origin is kept — correctly.
+ *
+ * WHY IT IS A SUFFIX LIST AND NOT A REGEX
+ * Two reasons, both practical. It is applied inside an SDK whose eager bundle is measured in bytes,
+ * and a comma-joined string of suffixes compresses to almost nothing next to an equivalent pattern
+ * source. And it has to be COPIED, byte for byte, into the React Native SDK and into the backend's
+ * ingest path — a list with no syntax is a list that cannot drift in meaning between three
+ * languages' worth of tooling. `third-party:parity` hashes all three copies.
+ *
+ * ZERO IMPORTS, DELIBERATELY. That is what makes the byte-identical copy possible. If an edit here
+ * ever needs an import, the parity gate is the thing that will say so — keep the module pure rather
+ * than weakening the gate.
+ *
+ * WHAT IS DELIBERATELY NOT ON THE LIST
+ * The rule is: a host whose ONLY purpose is to receive telemetry. Everything else stays, because a
+ * dropped request is invisible and a kept one is merely noisy.
+ *
+ *   - Feature-flag and experiment services (LaunchDarkly, Optimizely, Split). Their RESPONSES
+ *     change what the app does, so a failed flag fetch is an application incident and the single
+ *     most useful request in the session.
+ *   - Chat and support widgets (Intercom, Zendesk, Drift). A broken widget is a broken feature the
+ *     user can see.
+ *   - `facebook.com` as a whole. `graph.facebook.com` is an API real apps call; only the pixel
+ *     delivery hosts are listed.
+ *   - CDNs of any kind, even ones that mostly serve tags: they also serve application assets, and
+ *     dropping them would hide a real asset failure.
+ *
+ * When in doubt, leave it out. `denyUrls` stays the per-app escape hatch in both SDKs, and it can
+ * do what this list will not.
+ */
+
+/**
+ * Known telemetry, advertising and enrichment endpoints, as hostname suffixes.
+ *
+ * One comma-joined string rather than an array: identical meaning, materially smaller once gzipped,
+ * and it keeps the copy in three repos a single line to compare by eye.
+ */
+export const THIRD_PARTY_BEACON_HOSTS =
+  'google-analytics.com,googletagmanager.com,analytics.google.com,doubleclick.net,googlesyndication.com,' +
+  'googleadservices.com,app-measurement.com,facebook.net,analytics.tiktok.com,' +
+  'ads-twitter.com,analytics.twitter.com,ct.pinterest.com,bat.bing.com,px.ads.linkedin.com,tr.snapchat.com,' +
+  'criteo.com,criteo.net,taboola.com,outbrain.com,adroll.com,adsrvr.org,quantserve.com,scorecardresearch.com,' +
+  'hotjar.com,hotjar.io,clarity.ms,fullstory.com,mouseflow.com,crazyegg.com,luckyorange.com,inspectlet.com,' +
+  'segment.io,mixpanel.com,amplitude.com,heap.io,heapanalytics.com,rudderstack.com,posthog.com,' +
+  'matomo.cloud,plausible.io,simpleanalytics.com,statcounter.com,' +
+  'appsflyer.com,adjust.com,branch.io,' +
+  'ipify.org,ipinfo.io,ipapi.co,ip-api.com,geolocation-db.com,cloudflareinsights.com,' +
+  'nr-data.net,browser-intake-datadoghq.com,sentry.io,bugsnag.com,rollbar.com';
+
+/**
+ * True when `url` is addressed to a known beacon host.
+ *
+ * Deliberately total: an unparseable or relative URL is NOT third party. A relative URL is
+ * same-origin by definition — the app's own call — and guessing on garbage input would drop real
+ * requests for no benefit.
+ */
+export function isThirdPartyBeacon(url: string, hosts?: string): boolean {
+  if (!url) return false;
+  let host = '';
+  try {
+    // A relative URL throws here, which is the answer we want: it is first-party.
+    host = new URL(url).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  if (!host) return false;
+  for (const suffix of (hosts ?? THIRD_PARTY_BEACON_HOSTS).split(',')) {
+    // Dot boundary, so `notevil-facebook.com` does not match `facebook.com` while
+    // `connect.facebook.com` does. The bare-equality arm covers the apex domain itself.
+    if (host === suffix || host.endsWith('.' + suffix)) return true;
+  }
+  return false;
+}