sitepong 0.2.11 → 0.2.13

package/ios/ScreenRecorder/ScreenRecorderModule.swift

@@ -121,10 +121,12 @@ public class SitePongScreenRecorderModule: Module {
       let sampleRate = config["sampleRate"] as? Double ?? 0.1
       // RN host stamps platform "react-native-ios" (§1.1/§4.4).
       let platform = config["platform"] as? String ?? "react-native-ios"
+      // Idle grace before a reopen rolls a new session (default 30s).
+      let sessionGraceMs = config["sessionGraceMs"] as? Double ?? 30_000
       guard let endpoint = URL(string: endpointStr) else { return }
       Watchtower.start(apiKey: apiKey, projectId: projectId,
                        endpoint: endpoint, sampleRate: sampleRate,
-                       platform: platform)
+                       platform: platform, sessionGraceMs: sessionGraceMs)
     }
 
     Function("watchtowerStop") {

package/ios/WatchtowerCore/TapEvent.swift

@@ -14,6 +14,16 @@ public struct CaptureEvent: Codable {
     public var distinct_id: String?
     public var device_model: String?
     public var os_version: String?
+    /// Persistent per-install id (identifierForVendor) — stamped on every event
+    /// so the dashboard can stitch consecutive sessions from the same install
+    /// into a journey at read time, even for anonymous users.
+    public var install_id: String?
+
+    // session_start (only on a session that opened after a background→foreground
+    // gap): the id of the session this one continues from, and the idle gap in
+    // milliseconds. These are the read-time linking hints.
+    public var previous_session_id: String?
+    public var session_gap_ms: UInt64?
 
     // identity traits — only populated on an "identify" event (Watchtower.setUser
     // with email/name), so PII is sent once per identify, not on every tap.

package/ios/WatchtowerCore/Watchtower.swift

@@ -13,18 +13,18 @@ public enum Watchtower {
     /// identity knob — capture logic is identical regardless of platform.
     public static func start(apiKey: String, projectId: String,
                              endpoint: URL, sampleRate: Double = 0.1,
-                             platform: String = "ios") {
+                             platform: String = "ios", sessionGraceMs: Double = 30_000) {
         #if canImport(UIKit)
         // Ensure UIKit work happens on the main thread.
         if Thread.isMainThread {
             WatchtowerEngine.shared.start(apiKey: apiKey, projectId: projectId,
                                           endpoint: endpoint, sampleRate: sampleRate,
-                                          platform: platform)
+                                          platform: platform, sessionGraceMs: sessionGraceMs)
         } else {
             DispatchQueue.main.async {
                 WatchtowerEngine.shared.start(apiKey: apiKey, projectId: projectId,
                                               endpoint: endpoint, sampleRate: sampleRate,
-                                              platform: platform)
+                                              platform: platform, sessionGraceMs: sessionGraceMs)
             }
         }
         #endif

package/ios/WatchtowerCore/WatchtowerEngine.swift

@@ -37,6 +37,22 @@ final class WatchtowerEngine {
     /// overrides to "react-native-ios" via start(platform:).
     private var platform: String = "ios"
 
+    /// Persistent per-install id (identifierForVendor), resolved once at start
+    /// and stamped on every event so the dashboard can stitch consecutive
+    /// sessions from the same install into a journey at read time.
+    private var installId: String?
+    /// Wall-clock of the last background transition (nil until first background).
+    /// Drives the reopen-is-a-new-session decision on the next foreground.
+    private var lastBackgroundedAt: Date?
+    /// Idle grace: a foreground within this window of the last background resumes
+    /// the SAME session (a momentary app-switch shouldn't fragment); beyond it, a
+    /// fresh session is rolled. Default 30s; overridable via start(sessionGraceMs:).
+    private var sessionGraceMs: Double = 30_000
+    /// On a rolled session these carry the prior session id + idle gap (ms); they
+    /// ride the new session's session_start, then clear.
+    private var pendingPreviousSessionId: String?
+    private var pendingSessionGapMs: UInt64?
+
     /// Explicit screen identity override via setScreen (§3.2). Cleared/overridden
     /// by viewDidAppear unless re-set.
     private var explicitScreenName: String?
@@ -67,13 +83,18 @@ final class WatchtowerEngine {
     // MARK: - Lifecycle
 
     func start(apiKey: String, projectId: String, endpoint: URL, sampleRate: Double,
-               platform: String = "ios") {
+               platform: String = "ios", sessionGraceMs: Double = 30_000) {
         guard !isRunning else { return }
         self.transport = Transport(apiKey: apiKey, projectId: projectId, endpoint: endpoint)
         self.sessionId = UUID().uuidString
         self.sequence = 0
         self.sampleRate = sampleRate
         self.platform = platform
+        self.sessionGraceMs = sessionGraceMs
+        self.installId = UIDevice.current.identifierForVendor?.uuidString
+        self.lastBackgroundedAt = nil
+        self.pendingPreviousSessionId = nil
+        self.pendingSessionGapMs = nil
         self.uploadedScreenFps.removeAll()
         self.inFlightScreenFps.removeAll()
         self.fpCache.removeAll()
@@ -130,16 +151,29 @@ final class WatchtowerEngine {
     /// per-session sequence.
     private func baseEvent(type: String) -> CaptureEvent {
         sequence += 1
-        return CaptureEvent(
+        var event = CaptureEvent(
             type: type, session_id: sessionId, sequence: sequence,
             timestamp: ISO8601DateFormatter.wt.string(from: Date()),
             platform: platform, app_version: appVersion,
             distinct_id: distinctId, device_model: deviceModel,
             os_version: osVersion
         )
+        event.install_id = installId
+        // Link hints ride only the session_start of a rolled session.
+        if type == "session_start" {
+            event.previous_session_id = pendingPreviousSessionId
+            event.session_gap_ms = pendingSessionGapMs
+        }
+        return event
     }
 
+    /// Diagnostic seam: when set, receives every emitted event before it is
+    /// enqueued for transport. nil in production; used by tests to assert the
+    /// session lifecycle + linking fields without a network round-trip.
+    var debugOnEmit: ((CaptureEvent) -> Void)?
+
     private func emit(_ event: CaptureEvent) {
+        debugOnEmit?(event)
         transport?.enqueue(event)
     }
 
@@ -165,14 +199,20 @@ final class WatchtowerEngine {
         NotificationCenter.default.addObserver(
             self, selector: #selector(appDidEnterBackground),
             name: UIApplication.didEnterBackgroundNotification, object: nil)
+        NotificationCenter.default.addObserver(
+            self, selector: #selector(appWillEnterForeground),
+            name: UIApplication.willEnterForegroundNotification, object: nil)
     }
 
     @objc private func appDidEnterBackground() {
         // Pending dead-checks can't complete in the background — flush them
-        // undetermined (dead omitted), then mark the session boundary. The
-        // session does NOT end here (§1.1): reason "background" lets the
-        // server close it on timeout if the app never returns.
+        // undetermined (dead omitted), then mark the (soft) session boundary and
+        // record when we backgrounded so the next foreground can decide whether
+        // this was a momentary switch (resume) or a real reopen (roll). The
+        // session does NOT end here: reason "background" lets the server close it
+        // on timeout if the app never returns.
         flushPendingTaps()
+        lastBackgroundedAt = Date()
         var end = baseEvent(type: "session_end")
         end.reason = "background"
         end.duration_ms = durationMs()
@@ -180,6 +220,42 @@ final class WatchtowerEngine {
         transport?.flush()
     }
 
+    /// A reopen. If we were backgrounded longer than the idle grace, the old
+    /// session is done — roll a fresh one (linked to the old via prev id + gap).
+    /// Within the grace it was just an app-switch, so the same session resumes.
+    @objc private func appWillEnterForeground() {
+        guard isRunning, let backgroundedAt = lastBackgroundedAt else { return }
+        let gapMs = Date().timeIntervalSince(backgroundedAt) * 1000
+        lastBackgroundedAt = nil
+        guard gapMs > sessionGraceMs else { return }
+        rollSession(gapMs: UInt64(max(0, gapMs)))
+    }
+
+    /// Open a brand-new session on the same install. Mirrors start()'s
+    /// per-session reset but keeps transport, identity, device, and install id.
+    /// The prior session already emitted a session_end (reason "background") when
+    /// it backgrounded, so we only open the new one here.
+    private func rollSession(gapMs: UInt64) {
+        pendingPreviousSessionId = sessionId
+        pendingSessionGapMs = gapMs
+        sessionId = UUID().uuidString
+        sequence = 0
+        sessionStartedAt = Date()
+        isSampledSession = Double.random(in: 0..<1) < sampleRate
+        uploadedScreenFps.removeAll()
+        inFlightScreenFps.removeAll()
+        fpCache.removeAll()
+        lastCaptureAt.removeAll()
+        capturesInFlight.removeAll()
+        lastFrameHash = nil
+        lastEmittedScreenName = nil
+        navCounter = 0
+        pendingTaps.removeAll()
+        emit(baseEvent(type: "session_start"))
+        pendingPreviousSessionId = nil
+        pendingSessionGapMs = nil
+    }
+
     // MARK: - Screen views (§1.1 screen_view)
 
     /// Single choke point for screen identity changes — called with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sitepong",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Official SitePong SDK for error tracking and monitoring",
   "main": "dist/index.js",
   "module": "dist/index.mjs",