@oneuptime/react-native-replay 14.0.10 → 14.0.12

package/README.md

@@ -196,8 +196,8 @@ Pass `debug: true` at startup to mirror those codes to the development console.
 
 Use the current consented session ID to correlate the application's own traces
 and logs with replay. The listener fires immediately when a session exists,
-again on every rotation, and with `null` when capture stops or consent is
-withdrawn:
+again on every rotation, and with `null` when capture stops, consent is
+withdrawn, or the session ends idle:
 
 ```ts
 const unsubscribe = OneUptimeReplay.onSessionChange((sessionId) => {
@@ -221,6 +221,12 @@ server response. AppState backgrounding records visibility, closes the current
 chunk, drains the outbox only when policy and consent permit uploading, and
 pauses sampling; foregrounding resumes with a fresh full snapshot.
 
+Thirty minutes with no touch and no SDK call ends the session at that last
+activity, so time in the background is never added to the end of a session.
+An app left open in the foreground stops sampling then rather than starting a
+session every half hour. The user's next touch, a return to the foreground,
+or `captureSession()` starts a new session on a fresh full snapshot.
+
 Policy is revalidated without HTTP-cache reuse before every foreground resume,
 after identity changes, and at five-minute intervals while the app remains
 active. An explicit disable takes effect before more capture; a transient

package/dist/index.cjs

@@ -98,7 +98,7 @@ var SESSION_REPLAY_MAX_OFFLINE_DELAY_MS = 3 * 24 * 60 * 60 * 1e3;
 var MOBILE_CAPTURE_INTERVAL_MS = 500;
 var MOBILE_RECORDER_KIND = "rn-view-tree";
 var SYNTHETIC_RRWEB_VERSION = "synthetic-1";
-var RECORDER_VERSION = true ? "14.0.10" : "0.0.0-dev";
+var RECORDER_VERSION = true ? "14.0.12" : "0.0.0-dev";
 var SESSION_REPLAY_MOBILE_RECORDER_CAPABILITIES = [
   "mobile-view-tree",
   "mobile-touch-events",
@@ -150,6 +150,7 @@ var IDENTIFY_CUSTOM_EVENT_TAG = "oneuptime.identify";
 var TAGS_CUSTOM_EVENT_TAG = "oneuptime.tags";
 var VISIBILITY_CUSTOM_EVENT_TAG = "oneuptime.visibility";
 var TOUCH_CUSTOM_EVENT_TAG = "oneuptime.touch";
+var SESSION_ROTATED_CUSTOM_EVENT_TAG = "oneuptime.session-rotated";
 
 // src/Sanitize.ts
 var MAX_TRAIT_KEYS = 20;
@@ -3120,6 +3121,19 @@ var MobileReplayRecorder = class {
     __publicField(this, "pendingStartCancellation", null);
     __publicField(this, "identityPersisted", false);
     __publicField(this, "sessionLastActivityUnixMs", 0);
+    /*
+     * The session went the idle window without activity, was sealed where it
+     * ended, and nobody has come back since.
+     *
+     * Rotating on the spot instead (the old behaviour) started a session
+     * nobody was in: an app left open in the foreground with the screen on
+     * re-snapshots every minute, so it filed a new session every half hour
+     * for as long as it stayed open. Now nothing is captured, uploaded or
+     * handed to the host as a session id until the user is back - a touch,
+     * the app returning to the foreground, or an explicit captureSession() -
+     * and that starts the next session (see maybeRotateSession).
+     */
+    __publicField(this, "sealedForIdle", false);
     __publicField(this, "rotatingSession", false);
     __publicField(this, "rotationPromise", null);
     __publicField(this, "appStateQueue", Promise.resolve());
@@ -3207,6 +3221,7 @@ var MobileReplayRecorder = class {
     this.appStateQueue = Promise.resolve();
     this.rotationPromise = null;
     this.rotatingSession = false;
+    this.sealedForIdle = false;
     this.policyRefreshPromise = null;
     this.lastPolicyRefreshAtUnixMs = 0;
     this.forceFullSnapshot = true;
@@ -3379,12 +3394,14 @@ var MobileReplayRecorder = class {
       this.diagnosticsStatus = "stopped";
       return;
     }
-    this.appendCustom(
-      VISIBILITY_CUSTOM_EVENT_TAG,
-      { state: "stopped" },
-      void 0,
-      true
-    );
+    if (this.rotationReason(this.now()) !== "idle") {
+      this.appendCustom(
+        VISIBILITY_CUSTOM_EVENT_TAG,
+        { state: "stopped" },
+        void 0,
+        true
+      );
+    }
     this.haltCapture();
     await this.closeCurrent(true);
     if (this.uploadActive) {
@@ -3547,6 +3564,9 @@ var MobileReplayRecorder = class {
       return;
     }
     this.route = next;
+    if (this.sealedForIdle) {
+      return;
+    }
     this.appendCustom(
       ROUTE_CUSTOM_EVENT_TAG,
       {
@@ -3565,7 +3585,7 @@ var MobileReplayRecorder = class {
     if (!this.running || !this.acceptingEvents) {
       return;
     }
-    await this.maybeRotateSession(this.now());
+    await this.maybeRotateForUser(this.now());
     const safeReason2 = truncate(
       (typeof reason === "string" ? reason.trim() : "") || "manual",
       MAX_CAPTURE_REASON_LENGTH
@@ -3582,6 +3602,9 @@ var MobileReplayRecorder = class {
       return;
     }
     await this.maybeRotateSession(this.now());
+    if (this.sealedForIdle) {
+      return;
+    }
     const rawName = error instanceof Error && typeof error.name === "string" ? error.name.trim() : "";
     const name = SAFE_ERROR_NAMES.has(rawName) ? rawName : "Error";
     this.appendCustom(
@@ -3632,9 +3655,9 @@ var MobileReplayRecorder = class {
       this.lastTouchMoveAtUnixMs = touch.timestamp;
     }
     const nowUnixMs = this.now();
-    if (this.rotatingSession || this.rotationReason(nowUnixMs)) {
+    if (this.rotatingSession || this.sealedForIdle || this.rotationReason(nowUnixMs)) {
       this.diagnostic("touch-dropped-session-rotation");
-      void this.maybeRotateSession(nowUnixMs);
+      void this.maybeRotateForUser(nowUnixMs);
       return;
     }
     this.appendEvent(
@@ -3682,9 +3705,14 @@ var MobileReplayRecorder = class {
       )
     };
   }
-  /** Current consented replay session for host trace/log correlation. */
+  /**
+   * Current consented replay session for host trace/log correlation. None
+   * while the session has ended idle and nobody is back: a background poll
+   * on an idle app is no part of a recording that ended at the user's last
+   * activity.
+   */
   getSessionId() {
-    return this.running && this.identityPersisted ? this.identity?.sessionId ?? null : null;
+    return this.running && this.identityPersisted && !this.sealedForIdle ? this.identity?.sessionId ?? null : null;
   }
   /** Fires immediately when a session exists and again on rotate/clear. */
   onSessionChange(listener) {
@@ -3739,7 +3767,7 @@ var MobileReplayRecorder = class {
   }
   async captureTick(force = false) {
     const generation = this.lifecycleGeneration;
-    if (!this.running || !this.acceptingEvents || !this.foreground || !this.rootTag || this.captureGeneration === generation || !this.options) {
+    if (!this.running || !this.acceptingEvents || !this.foreground || !this.rootTag || this.sealedForIdle || this.captureGeneration === generation || !this.options) {
       return;
     }
     this.captureGeneration = generation;
@@ -3754,7 +3782,7 @@ var MobileReplayRecorder = class {
         return;
       }
       await this.maybeRotateSession(nowUnixMs);
-      if (!this.running || !this.acceptingEvents || !this.foreground || !this.isCurrentGeneration(generation)) {
+      if (!this.running || !this.acceptingEvents || !this.foreground || !this.isCurrentGeneration(generation) || this.sealedForIdle) {
         return;
       }
       const capturedSessionId = this.identity?.sessionId;
@@ -3763,7 +3791,6 @@ var MobileReplayRecorder = class {
         return;
       }
       this.touchPrivacyMap = deriveTouchPrivacyMap(tree);
-      const size = getViewport();
       const shouldForce = force || this.forceFullSnapshot || nowUnixMs - this.lastFullSnapshotAtUnixMs >= SESSION_REPLAY_CHECKOUT_INTERVAL_MS;
       if (shouldForce && !this.chunkBuffer.isEmpty()) {
         await this.closeCurrent(false);
@@ -3771,22 +3798,7 @@ var MobileReplayRecorder = class {
       if (!this.running || !this.acceptingEvents || !this.foreground || !this.isCurrentGeneration(generation) || this.identity?.sessionId !== capturedSessionId) {
         return;
       }
-      const capture = this.serializer.capture(tree, {
-        timestamp: nowUnixMs,
-        url: toAppUrl(this.options.mobileAppIdentifier, this.route),
-        viewportWidth: size.width,
-        viewportHeight: size.height,
-        forceFullSnapshot: shouldForce
-      });
-      this.droppedEvents += capture.droppedNodes;
-      this.chunkBuffer.appendMany(capture.events, {
-        route: toAppUrl(this.options.mobileAppIdentifier, this.route),
-        fidelityNotices: capture.fidelityNotices
-      });
-      if (capture.hasFullSnapshot) {
-        this.lastFullSnapshotAtUnixMs = nowUnixMs;
-        this.forceFullSnapshot = false;
-      }
+      this.appendCapture(tree, this.options, nowUnixMs, shouldForce);
       if (this.chunkBuffer.shouldFlush()) {
         await this.closeCurrent(false);
       }
@@ -3803,6 +3815,26 @@ var MobileReplayRecorder = class {
       }
     }
   }
+  appendCapture(tree, options, nowUnixMs, forceFullSnapshot) {
+    const size = getViewport();
+    const url = toAppUrl(options.mobileAppIdentifier, this.route);
+    const capture = this.serializer.capture(tree, {
+      timestamp: nowUnixMs,
+      url,
+      viewportWidth: size.width,
+      viewportHeight: size.height,
+      forceFullSnapshot
+    });
+    this.droppedEvents += capture.droppedNodes;
+    this.chunkBuffer.appendMany(capture.events, {
+      route: url,
+      fidelityNotices: capture.fidelityNotices
+    });
+    if (capture.hasFullSnapshot) {
+      this.lastFullSnapshotAtUnixMs = nowUnixMs;
+      this.forceFullSnapshot = false;
+    }
+  }
   appendCustom(tag, payload, signal, allowWhenQuiesced = false) {
     this.appendEvent(
       createCustomEvent(tag, payload, this.now()),
@@ -3814,6 +3846,9 @@ var MobileReplayRecorder = class {
     if (!this.running || !this.acceptingEvents && !allowWhenQuiesced) {
       return;
     }
+    if (this.sealedForIdle) {
+      return;
+    }
     if (!Number.isFinite(event.timestamp)) {
       this.droppedEvents += 1;
       this.diagnostic("invalid-event-timestamp");
@@ -3842,7 +3877,7 @@ var MobileReplayRecorder = class {
     }
   }
   async closeCurrent(isFinal) {
-    const closesFinalChunkSlot = !isFinal && !this.rotatingSession && this.uploadActive && this.sessionStore?.getNextChunkIndex() === MAX_SESSION_REPLAY_CHUNKS_PER_SESSION - 1;
+    const closesFinalChunkSlot = !isFinal && !this.rotatingSession && !this.sealedForIdle && this.uploadActive && this.sessionStore?.getNextChunkIndex() === MAX_SESSION_REPLAY_CHUNKS_PER_SESSION - 1;
     if (closesFinalChunkSlot) {
       this.rotatingSession = true;
       const rotationOptions = {};
@@ -3854,7 +3889,7 @@ var MobileReplayRecorder = class {
       }
       this.chunkBuffer.append(
         createCustomEvent(
-          "oneuptime.session-rotated",
+          SESSION_ROTATED_CUSTOM_EVENT_TAG,
           { reason: "chunk-cap" },
           this.now()
         ),
@@ -4054,15 +4089,19 @@ var MobileReplayRecorder = class {
       if (!policyReady) {
         return;
       }
-      await this.maybeRotateSession(this.now());
+      const sessionIdBeforeResume = this.identity?.sessionId;
+      await this.maybeRotateSession(this.now(), true);
       if (!this.running || !this.isCurrentGeneration(generation)) {
         return;
       }
       this.appendCustom(VISIBILITY_CUSTOM_EVENT_TAG, { state: "visible" });
-      this.forceFullSnapshot = true;
+      const openedOnSnapshot = this.identity?.sessionId !== sessionIdBeforeResume && this.lastFullSnapshotAtUnixMs > 0;
+      if (!openedOnSnapshot) {
+        this.forceFullSnapshot = true;
+      }
       this.startTimers();
       this.diagnosticsStatus = this.consentState() === "Unknown" ? "consent-required" : "recording";
-      await this.captureTick(true);
+      await this.captureTick(!openedOnSnapshot);
       if (this.uploadActive && this.running) {
         this.transport?.resume();
       }
@@ -4342,9 +4381,12 @@ var MobileReplayRecorder = class {
       if (!this.running || identityEpoch !== this.identityCancellationEpoch) {
         return;
       }
+      if (!this.rotationPromise && !this.sealedForIdle && this.rotationReason(this.now()) === "idle") {
+        await this.maybeRotateSession(this.now());
+      }
       if (this.rotationPromise) {
         await this.rotationPromise;
-      } else {
+      } else if (!this.sealedForIdle) {
         this.rotatingSession = true;
         const rotation = this.performSessionRotation(
           this.now(),
@@ -4679,16 +4721,24 @@ var MobileReplayRecorder = class {
       chunkIndex: 0
     };
   }
+  /*
+   * Idle before the duration cap, the order Common's SessionIdentity decides
+   * them in. A session left for the idle window ended where it was left,
+   * even when it has outlived the cap by the time anything notices, and
+   * only an idle rotation dates its end there (see performSessionRotation):
+   * called "duration", a session three hours old put in the background for
+   * two more was sealed two hours after its footage.
+   */
   rotationReason(nowUnixMs) {
     if (!this.identity) {
       return null;
     }
-    if (nowUnixMs - this.identity.sessionStartUnixMs >= SESSION_REPLAY_MAX_SESSION_MS) {
-      return "duration";
-    }
     if (nowUnixMs - this.sessionLastActivityUnixMs >= SESSION_REPLAY_IDLE_ROLLOVER_MS) {
       return "idle";
     }
+    if (nowUnixMs - this.identity.sessionStartUnixMs >= SESSION_REPLAY_MAX_SESSION_MS) {
+      return "duration";
+    }
     return null;
   }
   runExternalActivity(nowUnixMs, action) {
@@ -4723,23 +4773,37 @@ var MobileReplayRecorder = class {
       }
     });
   }
-  async maybeRotateSession(nowUnixMs) {
-    if (this.rotationPromise) {
+  /*
+   * isUserBack: the caller knows the user is here - a touch, the app
+   * returning to the foreground, an explicit captureSession(). An idle
+   * session then rotates at once. Anything else (a capture tick, a route
+   * change, a developer event) only finds out the session went idle, and
+   * seals it to wait for them (see sealedForIdle).
+   */
+  async maybeRotateSession(nowUnixMs, isUserBack = false) {
+    while (this.rotationPromise) {
       await this.rotationPromise;
-      return;
+      if (!isUserBack || !this.sealedForIdle) {
+        return;
+      }
     }
     if (!this.running || this.rotatingSession || !this.identity || !this.config || !this.sessionStore || !this.options) {
       return;
     }
-    const reason = this.rotationReason(nowUnixMs);
+    let reason;
+    if (this.sealedForIdle) {
+      if (!isUserBack) {
+        return;
+      }
+      reason = "idle";
+    } else {
+      reason = this.rotationReason(nowUnixMs);
+    }
     if (!reason) {
       return;
     }
     this.rotatingSession = true;
-    const operation = this.performSessionRotation(
-      nowUnixMs,
-      reason
-    );
+    const operation = reason === "idle" && !isUserBack ? this.sealForIdle() : this.performSessionRotation(nowUnixMs, reason);
     this.rotationPromise = operation;
     try {
       await operation;
@@ -4750,8 +4814,60 @@ var MobileReplayRecorder = class {
       this.rotatingSession = false;
     }
   }
+  /*
+   * maybeRotateSession for a user who is here. On an app whose session
+   * ended idle, the policy is brought up to date first: no capture tick has
+   * refreshed it while the app sat idle, and the next session must not open
+   * under one that has since changed (or turned replay off).
+   */
+  async maybeRotateForUser(nowUnixMs) {
+    if (this.sealedForIdle && !this.rotatingSession) {
+      const policyReady = await this.refreshRuntimePolicy(
+        this.lifecycleGeneration,
+        false,
+        "periodic"
+      );
+      if (!policyReady) {
+        return;
+      }
+    }
+    await this.maybeRotateSession(nowUnixMs, true);
+  }
+  /*
+   * End the session as idle, where it really ended, and wait for the user.
+   *
+   * Sealed with whatever footage is still buffered - dated by that footage,
+   * never by now - and with no marker of its own: a marker stamped now
+   * would date the session's end half an hour or more after anything the
+   * player can show. With nothing buffered nothing is sent, and the server
+   * ends the session at its last chunk.
+   */
+  async sealForIdle() {
+    this.sealedForIdle = true;
+    this.diagnostic("session-ended-idle", {
+      idleForMs: Math.max(0, this.now() - this.sessionLastActivityUnixMs)
+    });
+    this.notifySessionChange();
+    await this.closeCurrent(true);
+    await this.closeQueue;
+    if (!this.running) {
+      return;
+    }
+    if (this.uploadActive) {
+      await this.transport?.drain();
+    } else {
+      this.rollingBuffer.clear();
+    }
+  }
   async performSessionRotation(nowUnixMs, reason) {
-    this.appendCustom("oneuptime.session-rotated", { reason }, void 0, true);
+    if (reason !== "idle") {
+      this.appendCustom(
+        SESSION_ROTATED_CUSTOM_EVENT_TAG,
+        { reason },
+        void 0,
+        true
+      );
+    }
     await this.closeCurrent(true);
     await this.closeQueue;
     if (!this.running) {
@@ -4766,12 +4882,64 @@ var MobileReplayRecorder = class {
       return;
     }
     await this.completeSessionIdentityRotation(nowUnixMs, reason);
+    if (reason === "idle" && this.running) {
+      await this.openSessionAfterIdle();
+    }
+  }
+  /*
+   * The first things a session after an idle one records: a full snapshot
+   * of the screen the user came back to, then the rotation marker - the
+   * snapshot first, so chunk 0 is a seek anchor rather than a lone marker.
+   *
+   * Taken here, inside the rotation, rather than left to the next capture
+   * tick: until the rotation settles, touches are dropped and every other
+   * event waits for it (rotatingSession), so nothing can land ahead of the
+   * snapshot. A user who has just come back is touching the screen, and
+   * half a second of that was otherwise a chunk 0 with no screen in it.
+   *
+   * In the background or without a registered root there is no screen to
+   * capture yet; the marker opens the session alone.
+   */
+  async openSessionAfterIdle() {
+    const generation = this.lifecycleGeneration;
+    const rootTag = this.rootTag;
+    const options = this.options;
+    const sessionId = this.identity?.sessionId;
+    if (this.foreground && rootTag && options && sessionId) {
+      const capturedAtUnixMs = this.now();
+      let tree;
+      try {
+        tree = await this.nativeViewTree.captureViewTree(rootTag);
+      } catch (error) {
+        if (this.running && this.isCurrentGeneration(generation)) {
+          this.disable("native-capture-failed", {
+            name: error instanceof Error ? error.name : "Error"
+          });
+          this.haltCapture();
+        }
+        return;
+      }
+      if (!this.running || !this.isCurrentGeneration(generation) || this.identity?.sessionId !== sessionId) {
+        return;
+      }
+      if (this.foreground) {
+        this.touchPrivacyMap = deriveTouchPrivacyMap(tree);
+        this.appendCapture(tree, options, capturedAtUnixMs, true);
+      }
+    }
+    this.appendCustom(
+      SESSION_ROTATED_CUSTOM_EVENT_TAG,
+      { reason: "idle" },
+      void 0,
+      true
+    );
   }
   async completeSessionIdentityRotation(nowUnixMs, reason) {
     if (!this.sessionStore || !this.config || !this.options) {
       return;
     }
     this.identity = this.identityPersisted ? await this.sessionStore.rotate(nowUnixMs) : this.ephemeralIdentity(nowUnixMs);
+    this.sealedForIdle = false;
     this.notifySessionChange();
     this.sampled = this.identityPersisted ? deterministicSample(
       this.identity.sessionId,