@@ -19,6 +19,7 @@ body:
       label: 2. Agent Version
       description: Please select the exact version of the `splunk-otel-ios` agent you are using.
       options:
+        - 2.4.1
         - 2.4.0
         - 2.3.2
         - 2.3.1
 
@@ -77,6 +77,13 @@ struct CustomTrackingDemoView: View {
                     }
                 )
 
+                FeatureSection(
+                    title: "Explicit Stacktrace Error Tracking (hybrid agents)",
+                    content: FeatureButton(label: "Track Explicit Error (JS stack)") {
+                        trackExplicitError()
+                    }
+                )
+
                 FeatureSection(
                     title: "Legacy Tracking",
                     content: VStack(spacing: 8) {
@@ -136,6 +143,33 @@ struct CustomTrackingDemoView: View {
     }
 
 
+    // MARK: - Explicit stacktrace error tracking
+
+    /// Simulates how the React Native / Flutter bridge reports a caught JS/Dart
+    /// error: an explicit type, message, and verbatim (here Hermes-style) stack,
+    /// with the hybrid layer's context carried through `attributes`.
+    func trackExplicitError() {
+        let frames = [
+            "TypeError: undefined is not a function (evaluating 'cart.checkout()')",
+            "    at Checkout (index.android.bundle:1:537284)",
+            "    at onPress (index.android.bundle:1:540122)"
+        ]
+        let stacktrace = frames.joined(separator: "\n")
+
+        SplunkRum.shared.customTracking.trackError(
+            typeName: "TypeError",
+            message: "undefined is not a function (evaluating 'cart.checkout()')",
+            stacktrace: stacktrace,
+            attributes: [
+                "screen.name": "Cart",
+                "error.source": "custom",
+                "exception.escaped": false,
+                "rum.sdk.rn.version": "react-native"
+            ]
+        )
+    }
+
+
     // MARK: - Legacy API calls demonstrating available but deprecated methods
 
     // Note:
 
@@ -7,6 +7,22 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.4.1] - 2026-08-13
+
+### Changed
+
+* Deployment environment resources now use the OpenTelemetry `deployment.environment.name` attribute instead of `deployment.environment`
+
+### Added
+
+* Session Replay segment metadata now includes a `userActivity` field containing Unix-millisecond timestamps of user interactions that occurred during the segment window, enabling timeline visualization in the backend. Timestamps are only collected while Session Replay is recording; disabling `InteractionsConfiguration` does not affect Session Replay segment recording but does prevent user-activity timestamps from being collected because they originate from the Interactions detector. #646
+* Added `customTracking.trackError(typeName:message:stacktrace:attributes:)` for reporting an error with an explicitly supplied stacktrace. Unlike the existing `trackError` overloads, the supplied stack is emitted verbatim as `exception.stacktrace` (no native stack is derived) and the resulting `component=error` span is named after `typeName` (falling back to `"error"`). This is the native emission path for caught JavaScript/Dart errors bridged from the React Native and Flutter agents. A matching Objective-C selector (`trackErrorWithType:message:stacktrace:attributes:`) is also available.
+
+### Fixed
+
+* Improved accuracy of `slowRenders` and `frozenRenders` detection: the detector now derives the expected cadence per frame, counts a continuous freeze once, and makes slow and frozen classifications mutually exclusive. #696
+* Fixed a spurious `frozenRenders` event that could be emitted when the app backgrounded while a frame was in flight. #696
+
 ## [2.4.0] - 2026-07-20
 
 ### Fixed
 
@@ -1,50 +1,84 @@
 # How to Release Splunk RUM for iOS
 
-This project is distributed as a Swift Package. The release process is driven by creating and pushing versioned Git tags.
-
-## Automated workflow
-
-- An action named “New release” is available in the Actions tab of the repository.
-- Fill in the required fields and select the target branch.
-- The action will prepare a release pull request.
-- After the release pull request is merged into main, a new tag and release will be created automatically, and a new pull request into develop will be opened.
-
-## Manual workflow
-
-### 1. Prepare the Release
-
-1. Ensure the `main` branch is stable and all changes for the release have been merged.
-2. Update `CHANGELOG.md` by moving all items from the `[Unreleased]` section to a new version heading (e.g., `[2.0.0] - YYYY-MM-DD`).
-3. Update the `version` constant in `SplunkAgent/Sources/SplunkAgent/Public API/SplunkRum.swift`.
-
-### 2. Run Final Checks
-
-Build the project and run the full test suite from the command line to ensure everything is passing.
-
-```bash
-# Build the project
-xcodebuild build -scheme SplunkAgent -destination 'generic/platform=iOS Simulator'
-
-# Run the tests
-xcodebuild test -scheme SplunkAgent -destination 'platform=iOS Simulator,name=iPhone 16'
-```
-
-### 3. Tag and Push the Release
-
-Create a signed Git tag for the new version. Swift Package Manager uses these tags to resolve package versions.
-
-```bash
-# Create a signed tag (e.g., for version 2.0.0) with a 'v' prefix
-git tag -s v2.0.0
-
-# Push the tag to the remote repository
-git push origin v2.0.0
-```
-
-### 4. Publish on GitHub
-
-1. Go to the "Releases" page in the GitHub repository and click "Draft a new release".
-2. Choose the tag you just pushed.
-3. For the release notes, copy and paste the content from the corresponding version section in `CHANGELOG.md`.
-4. Click the **Publish release** button. This will finalize the release, making it public and visible to the community.
-
+This project is distributed through Swift Package Manager and as signed XCFramework archives attached to GitHub releases. Versioned Git tags define the versions available to Swift Package Manager.
+
+## Pre-flight
+
+1. Confirm all features for the release are merged to `develop`.
+2. Confirm `CHANGELOG.md` on `develop` has complete `[Unreleased]` entries, each with a PR link (e.g., `#123`).
+
+## Release
+
+3. Run the **"New release"** workflow from the Actions tab, targeting `develop`, with the version (e.g., `2.3.2`) and Jira ticket (e.g., `DEMRUM-1234`). The action will prepare a release pull request.
+4. On the resulting PR, click **"Approve workflows to run"** when prompted, obtain the required approvals, and wait for the required checks.
+5. Merge the PR into `main` with a **regular merge commit only** (not squash or rebase). If the CLA check remains pending after everything else passes, use the administrator workaround below.
+6. After the release PR is merged into `main`, a new tag and release will be created automatically, and a new back-merge PR into `develop` will be opened.
+
+## Sign and upload XCFrameworks
+
+7. With the Apple Distribution certificate and private key in your keychain and the Session Replay repository checked out locally, replace `<VERSION>` and `<APPLE_DISTRIBUTION_SIGNING_IDENTITY>` with the release values and upload both distributions:
+   ```bash
+   export SESSION_REPLAY_LOCAL_PATH=/path/to/session-replay
+   tools/xcframework/scripts/sign-and-upload.sh <VERSION> \
+     --identity "<APPLE_DISTRIBUTION_SIGNING_IDENTITY>" \
+     --upload-to <VERSION>
+   tools/xcframework/scripts/sign-and-upload.sh <VERSION> \
+     --identity "<APPLE_DISTRIBUTION_SIGNING_IDENTITY>" \
+     --ios-only \
+     --upload-to <VERSION>
+   ```
+8. Open the GitHub release for `<VERSION>` and confirm both `SplunkAgent-XCFrameworks.zip` and `SplunkAgent-XCFrameworks-iOS-only.zip` are attached and downloadable. This check validates the uploaded XCFramework distributions; the SPM smoke test below does not validate these archives.
+
+## Back-merge
+
+9. On the back-merge PR, click **"Approve workflows to run"** when prompted, obtain the required approvals, and wait for the required checks.
+10. Ask a repository administrator to temporarily disable **"Require linear history"** for `develop`, merge the PR into `develop` with a **regular merge commit only** (not squash or rebase), and immediately re-enable the rule. If the CLA check remains pending after everything else passes, the administrator should bypass it during this merge.
+
+## Smoke test
+
+11. In a test app, add an SPM dependency on `signalfx/splunk-otel-ios` at the new version.
+12. In Xcode: **File → Packages → Reset Package Caches**, then **File → Packages → Resolve Package Versions**.
+13. Build and run. Confirm the session appears in a testing realm with `rum.sdk.version` matching the new version.
+
+## Manual recovery
+
+Use this only when an automated workflow fails. Inspect the failed run and complete only the missing steps; do not recreate a branch, tag, release, or PR that already exists.
+
+### Prepare the release PR
+
+1. Create the release branch from `develop`:
+   ```bash
+   git switch develop
+   git pull --ff-only
+   git switch -c release/<VERSION>
+   ```
+2. In `CHANGELOG.md`, rename `[Unreleased]` to `[<VERSION>] - YYYY-MM-DD` and add a new empty `[Unreleased]` section above it.
+3. Bump the version constant in `SplunkAgent/Sources/SplunkAgent/Public API/SplunkRum.swift`.
+4. Add `<VERSION>` to the version dropdown in `.github/ISSUE_TEMPLATE/bug.yml`.
+5. Build the project and run the full test suite using an installed simulator:
+   ```bash
+   xcodebuild -scheme SplunkAgent -destination 'generic/platform=iOS Simulator' build
+   xcodebuild -scheme SplunkAgent -showdestinations
+   xcodebuild -scheme SplunkAgent -destination 'OS=<installed OS>,name=<installed iPhone simulator>' test
+   ```
+6. Create a signed commit, push the branch, and open a PR from `release/<VERSION>` to `main`. Title: `DEMRUM-XXXX: Release <VERSION>`.
+7. Merge the PR with a **regular merge commit only** (not squash or rebase). This starts the **"Release finalize"** workflow.
+
+### Complete a failed Release finalize workflow
+
+The workflow creates the tag, GitHub release, and back-merge PR in that order. Check which artifacts exist and perform only the missing steps.
+
+1. If the `<VERSION>` tag is missing, create and push it without a `v` prefix. Swift Package Manager uses this tag to resolve the release:
+   ```bash
+   git switch main
+   git pull --ff-only
+   git tag -s <VERSION> -m "Release <VERSION>"
+   git push origin <VERSION>
+   ```
+2. If the GitHub release is missing, draft one for the `<VERSION>` tag, use the `[<VERSION>]` section from `CHANGELOG.md` as its notes, and publish it.
+3. If the back-merge PR is missing, open one from `main` to `develop`. Title: `NO-TICKET: Merge back <VERSION> to develop`.
+4. Complete the back-merge steps above.
+
+## Known issue: pending CLA check
+
+The `ContributorLicenseAgreement` check on bot-created PRs may remain at "Waiting for status to be reported." After every other required check and review passes, ask a repository administrator to bypass the pending check and perform a regular merge commit. This workaround applies to both the release and back-merge PRs until the workflow is fixed.
@@ -79,6 +79,7 @@ class DefaultEventManager: AgentEventManager {
 
     var sessionReplayIndexer: EventIndexer
     var sessionReplayMemorizer: EventMemorizer
+    let userActivityCollector = UserActivityCollector()
 
     /// Agent reference.
     unowned let agent: SplunkRum
@@ -149,6 +150,7 @@ class DefaultEventManager: AgentEventManager {
 
         // Crash Reports module data
         #if canImport(SplunkCrashReports)
+
             case let (metadata as CrashReportsMetadata, data as String):
                 publishCrashReports(data: data, metadata: metadata, completion: completion)
         #endif
@@ -196,29 +198,29 @@ class DefaultEventManager: AgentEventManager {
             // Use scriptInstanceId as a 16 character substring of a sessionId
             let scriptInstanceId = String(sessionId.prefix(upTo: sessionId.index(sessionId.startIndex, offsetBy: 16)))
 
+            let flush = userActivityCollector.flush(startMs: metadata.startUnixMs, endMs: metadata.endUnixMs)
+
             let event = SessionReplayDataEvent(
                 metadata: metadata,
                 data: data,
                 index: eventIndex,
                 sessionId: sessionId,
-                scriptInstanceId: scriptInstanceId
+                scriptInstanceId: scriptInstanceId,
+                userActivity: flush.timestamps
             )
 
-            sessionReplayProcessor.sendEvent(
-                event: event,
-                immediateProcessing: false,
-                completion: { [weak self] processed in
-                    if processed {
-                        self?
-                            .removeSessionReplayIndex(
-                                sessionId: sessionId,
-                                timestamp: metadata.timestamp
-                            )
-                    }
-
-                    completion(processed)
+            sessionReplayProcessor.sendEvent(event: event, immediateProcessing: false) { [weak self] processed in
+                if processed {
+                    self?.removeSessionReplayIndex(sessionId: sessionId, timestamp: metadata.timestamp)
                 }
-            )
+                else {
+                    // Return timestamps to the collector so they are included on retry.
+                    // The generation guards against a stop/reset that happened while the
+                    // send was in flight — restore is a no-op in that case.
+                    self?.userActivityCollector.restore(flush.timestamps, generation: flush.generation)
+                }
+                completion(processed)
+            }
         }
     }
 
 
@@ -51,7 +51,8 @@ class SessionReplayDataEvent: AgentEvent {
     ///   - sessionId: The `session Id` of a session in which the event occurred.
     ///               Optional so that we can see sessions with no session id in the backend.
     ///   - scriptInstanceId: Internal identifier used for backend purposes.
-    init(metadata: Metadata, data: Data, index: Int, sessionId: String?, scriptInstanceId: String) {
+    ///   - userActivity: Unix-millisecond timestamps of user interactions recorded during this segment.
+    init(metadata: Metadata, data: Data, index: Int, sessionId: String?, scriptInstanceId: String, userActivity: [Int] = []) {
         // Event properties
         timestamp = metadata.timestamp
         body = EventAttributeValue(data)
@@ -64,7 +65,7 @@ class SessionReplayDataEvent: AgentEvent {
         // Event attributes
         attributes = [
             // Chunk metadata
-            "segmentMetadata": .string(metadataToJSONString(metadata)),
+            "segmentMetadata": .string(metadataToJSONString(metadata, userActivity: userActivity)),
 
             // Script ID
             "splunk.scriptInstance": .string(scriptInstanceId),
@@ -80,16 +81,82 @@ class SessionReplayDataEvent: AgentEvent {
 
     // MARK: - Private methods
 
-    private func metadataToJSONString(_ metadata: Metadata) -> String {
+    private func metadataToJSONString(_ metadata: Metadata, userActivity: [Int]) -> String {
         // We always prefer conversion with a standard encoder ...
         guard
             let metadataContent = try? JSONEncoder().encode(metadata),
-            let jsonString = String(data: metadataContent, encoding: .utf8)
+            var jsonObject = try? JSONSerialization.jsonObject(with: metadataContent) as? [String: Any]
         else {
             // ... but if something fails, we can build it manually
-            return "{\"startUnixMs\":\(metadata.startUnixMs), \"endUnixMs\":\(metadata.endUnixMs), \"source\":\"\(metadata.source)\"}"
+            return fallbackJSON(metadata: metadata, userActivity: userActivity)
+        }
+
+        jsonObject["userActivity"] = userActivity
+
+        guard
+            let enrichedData = try? JSONSerialization.data(withJSONObject: jsonObject),
+            let jsonString = String(data: enrichedData, encoding: .utf8)
+        else {
+            return fallbackJSON(metadata: metadata, userActivity: userActivity)
+        }
+
+        return jsonString
+    }
+
+    private func fallbackJSON(metadata: Metadata, userActivity: [Int]) -> String {
+        let dict: [String: Any] = [
+            "startUnixMs": metadata.startUnixMs,
+            "endUnixMs": metadata.endUnixMs,
+            "source": metadata.source,
+            "userActivity": userActivity
+        ]
+        guard
+            let data = try? JSONSerialization.data(withJSONObject: dict),
+            let jsonString = String(data: data, encoding: .utf8)
+        else {
+            let activityJSON = userActivity.map(String.init).joined(separator: ",")
+            let src = jsonEscaped(metadata.source)
+            let start = metadata.startUnixMs
+            let end = metadata.endUnixMs
+            return "{\"startUnixMs\":\(start),\"endUnixMs\":\(end),\"source\":\"\(src)\",\"userActivity\":[\(activityJSON)]}"
         }
 
         return jsonString
     }
+
+    private func jsonEscaped(_ string: String) -> String {
+        var result = ""
+        result.reserveCapacity(string.utf16.count)
+        for char in string.unicodeScalars {
+            switch char.value {
+            case 0x22:
+                result += "\\\""
+
+            case 0x5C:
+                result += "\\\\"
+
+            case 0x08:
+                result += "\\b"
+
+            case 0x09:
+                result += "\\t"
+
+            case 0x0A:
+                result += "\\n"
+
+            case 0x0C:
+                result += "\\f"
+
+            case 0x0D:
+                result += "\\r"
+
+            case 0x00 ..< 0x20:
+                result += String(format: "\\u%04X", char.value)
+
+            default:
+                result.unicodeScalars.append(char)
+            }
+        }
+        return result
+    }
 }