@rejourneyco/react-native 1.0.9 → 1.0.10

package/README.md

@@ -11,15 +11,89 @@ npm install @rejourneyco/react-native
 ## Quick Start
 
 ```typescript
-import { initRejourney, startRejourney } from '@rejourneyco/react-native';
+import { Rejourney } from '@rejourneyco/react-native';
 
 // Initialize with your public key
-initRejourney('pk_live_xxxxxxxxxxxx');
+Rejourney.init('pk_live_xxxxxxxxxxxx');
 
 // Start recording after obtaining user consent
-startRejourney();
+Rejourney.start();
 ```
 
+## Navigation Tracking
+
+Rejourney automatically tracks screen changes to provide context for your session replays.
+
+### Expo Router (Automatic)
+If you use **Expo Router**, simply add this import at your root layout (`app/_layout.tsx`):
+```ts
+import '@rejourneyco/react-native/expo-router';
+```
+
+### React Navigation
+If you are using **React Navigation** (`@react-navigation/native`), use the `useNavigationTracking` hook in your root `NavigationContainer`:
+```tsx
+import { Rejourney } from '@rejourneyco/react-native';
+import { NavigationContainer } from '@react-navigation/native';
+
+const navigationTracking = Rejourney.useNavigationTracking();
+return <NavigationContainer {...navigationTracking}>{/*...*/}</NavigationContainer>;
+```
+
+### Custom Screen Names
+If you want to manually specify screen names or use a different library:
+
+#### For Expo Router users:
+Disable automatic tracking in your initialization:
+```ts
+Rejourney.init('pk_live_xxxxxxxxxxxx', {
+  autoTrackExpoRouter: false
+});
+```
+
+#### Manual tracking call:
+Notify Rejourney of screen changes using `trackScreen`:
+```ts
+import { Rejourney } from '@rejourneyco/react-native';
+
+Rejourney.trackScreen('Custom Screen Name');
+```
+
+> [!NOTE]
+> `expo-router` is an **optional peer dependency**. The SDK is carefully architectural to avoid requiring `expo-router` in the main bundle. This prevents Metro from attempting to resolve it at build time in projects where it's not installed, which would otherwise cause a "Requiring unknown module" crash.
+
+## Custom Events & Metadata
+
+You can track custom events and assign metadata to sessions to filter and segment them later.
+
+```typescript
+import { Rejourney } from '@rejourneyco/react-native';
+
+// Log custom events
+Rejourney.logEvent('button_clicked', { buttonName: 'signup' });
+
+// Add custom session metadata
+Rejourney.setMetadata('plan', 'premium');
+Rejourney.setMetadata({
+  role: 'tester',
+  ab_test_group: 'A'
+});
+```
+
+## API Reference & Compatibility
+
+Rejourney supports both a standardized `Rejourney.` namespace and standalone function exports (AKA calls). Both are fully supported.
+
+| Standardized Method | Standalone Alias (AKA) |
+| --- | --- |
+| `Rejourney.init()` | `initRejourney()` |
+| `Rejourney.start()` | `startRejourney()` |
+| `Rejourney.stop()` | `stopRejourney()` |
+| `Rejourney.useNavigationTracking()` | `useNavigationTracking()` |
+
+> [!TIP]
+> We recommend using the `Rejourney.` prefix for better discoverability and a cleaner import surface.
+
 ## Documentation
 
 Full integration guides and API reference: https://rejourney.co/docs/reactnative/overview

package/android/src/main/AndroidManifest.xml

@@ -4,6 +4,12 @@
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
     
     <application>
+        <!-- Run before bridge init so OkHttpClientProvider uses our factory when NetworkingModule is created -->
+        <provider
+            android:name=".RejourneyOkHttpInitProvider"
+            android:authorities="${applicationId}.rejourney.okhttpinit"
+            android:exported="false"
+            android:initOrder="100" />
         <!-- Service to detect app termination when swiped away from recent apps -->
         <!-- stopWithTask="false" is CRITICAL - allows onTaskRemoved() to fire when app is killed -->
         <service

package/android/src/main/java/com/rejourney/RejourneyModuleImpl.kt

@@ -37,8 +37,14 @@ import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.ProcessLifecycleOwner
 import com.facebook.react.bridge.*
+import com.facebook.react.modules.network.CustomClientBuilder
+import com.facebook.react.modules.network.OkHttpClientFactory
+import com.facebook.react.modules.network.OkHttpClientProvider
+import com.facebook.react.modules.network.NetworkingModule
+import okhttp3.OkHttpClient
 import com.rejourney.engine.DeviceRegistrar
 import com.rejourney.engine.DiagnosticLog
+
 import com.rejourney.platform.OEMDetector
 import com.rejourney.platform.SessionLifecycleService
 import com.rejourney.platform.TaskRemovedListener
@@ -155,6 +161,41 @@ class RejourneyModuleImpl(
                     StabilityMonitor.getInstance(reactContext).transmitStoredReport()
                 }
                 
+                // Register OkHttp interceptor so native/RN fetch() and XHR go through Rejourney.
+                // Use both mechanisms so we catch requests regardless of init order:
+                // 1) OkHttpClientProvider factory + clear cache (correct field: sClient)
+                // 2) NetworkingModule.setCustomClientBuilder — applied on every request's client
+                try {
+                    OkHttpClientProvider.setOkHttpClientFactory(OkHttpClientFactory {
+                        OkHttpClientProvider.createClientBuilder()
+                            .addInterceptor(RejourneyNetworkInterceptor())
+                            .build()
+                    })
+                    // React Native caches the client in OkHttpClientProvider.sClient (not "client").
+                    // Clear it so the next getOkHttpClient() uses our factory.
+                    try {
+                        val clientField = OkHttpClientProvider::class.java.getDeclaredField("sClient")
+                        clientField.isAccessible = true
+                        clientField.set(null, null)
+                    } catch (_: Exception) {}
+                    OkHttpClientProvider.getOkHttpClient()
+                    // Ensure every request (including those already using a cached client) gets our
+                    // interceptor. NetworkingModule builds per-request clients via mClient.newBuilder()
+                    // and applies this builder, so this catches all native API calls.
+                    try {
+                        NetworkingModule.setCustomClientBuilder(object : CustomClientBuilder {
+                            override fun apply(builder: OkHttpClient.Builder) {
+                                builder.addInterceptor(RejourneyNetworkInterceptor())
+                            }
+                        })
+                        DiagnosticLog.notice("[Rejourney] Registered OkHttp interceptor + CustomClientBuilder")
+                    } catch (e: Exception) {
+                        DiagnosticLog.notice("[Rejourney] OkHttp interceptor registered (CustomClientBuilder skipped: ${e.message})")
+                    }
+                } catch (e: Exception) {
+                    DiagnosticLog.fault("[Rejourney] Failed to register OkHttp interceptor factory: ${e.message}")
+                }
+                
                 // Android-specific: OEM detection and task removed handling
                 setupOEMSpecificHandling()
                 
@@ -231,6 +272,8 @@ class RejourneyModuleImpl(
                 // Flush pending data
                 TelemetryPipeline.shared?.dispatchNow()
                 SegmentDispatcher.shared.shipPending()
+                // Stop the heartbeat timer to prevent event uploads while backgrounded
+                TelemetryPipeline.shared?.pause()
             }
         }
     }
@@ -254,6 +297,9 @@ class RejourneyModuleImpl(
 
             DiagnosticLog.notice("[Rejourney] App foregrounded after ${backgroundDuration / 1000}s (timeout: ${SESSION_TIMEOUT_MS / 1000}s)")
 
+            // Resume the heartbeat timer now that we're back in foreground
+            TelemetryPipeline.shared?.resume()
+
             if (backgroundDuration > SESSION_TIMEOUT_MS) {
                 // End current session and start a new one
                 state = SessionState.Idle
@@ -322,6 +368,14 @@ class RejourneyModuleImpl(
 
         DiagnosticLog.notice("[Rejourney] Starting new session after timeout (user: $savedUserId)")
 
+        // Refresh activity on capture components (guards against race with onActivityResumed)
+        val activity = reactContext.currentActivity
+        if (activity != null) {
+            VisualCapture.shared?.setCurrentActivity(activity)
+            ViewHierarchyScanner.shared?.setCurrentActivity(activity)
+            InteractionRecorder.shared?.setCurrentActivity(activity)
+        }
+
         // Try fast path with cached credentials
         val existingCred = DeviceRegistrar.shared?.uploadCredential
         if (existingCred != null && DeviceRegistrar.shared?.credentialValid == true) {

package/android/src/main/java/com/rejourney/RejourneyOkHttpInitProvider.kt

@@ -0,0 +1,68 @@
+/**
+ * Copyright 2026 Rejourney
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.rejourney
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.database.Cursor
+import android.net.Uri
+import com.facebook.react.modules.network.OkHttpClientFactory
+import com.facebook.react.modules.network.OkHttpClientProvider
+import com.rejourney.recording.RejourneyNetworkInterceptor
+
+/**
+ * ContentProvider that runs before Application.onCreate() (and thus before the React Native
+ * bridge and NetworkingModule are created). It registers our OkHttpClientFactory so the
+ * first (and all) OkHttpClient instances created by OkHttpClientProvider already include
+ * RejourneyNetworkInterceptor, ensuring native API calls are captured on Android like on iOS.
+ */
+class RejourneyOkHttpInitProvider : ContentProvider() {
+
+    override fun onCreate(): Boolean {
+        try {
+            OkHttpClientProvider.setOkHttpClientFactory(OkHttpClientFactory {
+                OkHttpClientProvider.createClientBuilder()
+                    .addInterceptor(RejourneyNetworkInterceptor())
+                    .build()
+            })
+        } catch (_: Exception) {
+            // Ignore; RejourneyModuleImpl will still register factory + CustomClientBuilder later
+        }
+        return true
+    }
+
+    override fun query(
+        uri: Uri,
+        projection: Array<out String>?,
+        selection: String?,
+        selectionArgs: Array<out String>?,
+        sortOrder: String?
+    ): Cursor? = null
+
+    override fun getType(uri: Uri): String? = null
+
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+
+    override fun delete(uri: Uri, selection: String?, selectionArgs: Array<out String>?): Int = 0
+
+    override fun update(
+        uri: Uri,
+        values: ContentValues?,
+        selection: String?,
+        selectionArgs: Array<out String>?
+    ): Int = 0
+}

package/android/src/main/java/com/rejourney/engine/DeviceRegistrar.kt

@@ -22,6 +22,7 @@ import android.os.Build
 import android.provider.Settings
 import kotlinx.coroutines.*
 import okhttp3.*
+import com.rejourney.recording.RejourneyNetworkInterceptor
 import okhttp3.MediaType.Companion.toMediaType
 import okhttp3.RequestBody.Companion.toRequestBody
 import org.json.JSONObject
@@ -71,6 +72,8 @@ class DeviceRegistrar private constructor(private val context: Context) {
         .connectTimeout(5, TimeUnit.SECONDS) // Short timeout for debugging
         .readTimeout(10, TimeUnit.SECONDS)
         .writeTimeout(10, TimeUnit.SECONDS)
+        // Mirror iOS URLProtocol behaviour: make native SDK HTTP calls observable
+        .addInterceptor(RejourneyNetworkInterceptor())
         .build()
     
     init {

package/android/src/main/java/com/rejourney/recording/RejourneyNetworkInterceptor.kt

@@ -19,13 +19,6 @@ class RejourneyNetworkInterceptor : Interceptor {
     @Throws(IOException::class)
     override fun intercept(chain: Interceptor.Chain): Response {
         val request = chain.request()
-        val host = request.url.host
-
-        // Skip Rejourney's own API traffic to avoid ingestion duplication (mirrors iOS RejourneyURLProtocol)
-        if (host.contains("api.rejourney.co") || host.contains("rejourney")) {
-            return chain.proceed(request)
-        }
-
         val startMs = System.currentTimeMillis()
 
         var response: Response? = null

package/android/src/main/java/com/rejourney/recording/ReplayOrchestrator.kt

@@ -31,6 +31,7 @@ import android.view.View
 import com.rejourney.engine.DeviceRegistrar
 import com.rejourney.engine.DiagnosticLog
 import com.rejourney.engine.PerformanceSnapshot
+import com.rejourney.utility.gzipCompress
 import org.json.JSONObject
 import java.io.File
 import java.util.*
@@ -505,6 +506,7 @@ class ReplayOrchestrator private constructor(private val context: Context) {
         visitedScreens.clear()
         bgTimeMs = 0
         bgStartMs = null
+        lastHierarchyHash = null
 
         TelemetryPipeline.shared?.currentReplayId = replayId
         SegmentDispatcher.shared.currentReplayId = replayId
@@ -797,9 +799,10 @@ class ReplayOrchestrator private constructor(private val context: Context) {
         lastHierarchyHash = hash
 
         val json = JSONObject(hierarchy).toString().toByteArray(Charsets.UTF_8)
+        val compressed = json.gzipCompress() ?: return
         val ts = System.currentTimeMillis()
 
-        SegmentDispatcher.shared.transmitHierarchy(sid, json, ts, null)
+        SegmentDispatcher.shared.transmitHierarchy(sid, compressed, ts, null)
     }
 
     private fun hierarchyHash(h: Map<String, Any>): String {

package/android/src/main/java/com/rejourney/recording/SegmentDispatcher.kt

@@ -19,6 +19,7 @@ package com.rejourney.recording
 import com.rejourney.engine.DiagnosticLog
 import kotlinx.coroutines.*
 import okhttp3.*
+import com.rejourney.recording.RejourneyNetworkInterceptor
 import okhttp3.MediaType.Companion.toMediaType
 import okhttp3.RequestBody.Companion.toRequestBody
 import org.json.JSONObject
@@ -127,6 +128,8 @@ class SegmentDispatcher private constructor() {
         .connectTimeout(5, TimeUnit.SECONDS) // Short timeout for debugging
         .readTimeout(10, TimeUnit.SECONDS)
         .writeTimeout(10, TimeUnit.SECONDS)
+        // Mirror iOS URLProtocol: ensure native upload/auth traffic is captured
+        .addInterceptor(RejourneyNetworkInterceptor())
         .build()
     
     private val retryQueue = mutableListOf<PendingUpload>()

package/android/src/main/java/com/rejourney/recording/TelemetryPipeline.kt

@@ -130,6 +130,32 @@ class TelemetryPipeline private constructor(private val context: Context) {
         }
     }
     
+    /**
+     * Pause the heartbeat timer when the app goes to background.
+     * This prevents the pipeline from uploading empty event batches
+     * while backgrounded, which would inflate session duration.
+     */
+    fun pause() {
+        heartbeatRunnable?.let { mainHandler.removeCallbacks(it) }
+        heartbeatRunnable = null
+    }
+    
+    /**
+     * Resume the heartbeat timer when the app returns to foreground.
+     */
+    fun resume() {
+        if (heartbeatRunnable != null) return
+        mainHandler.post {
+            heartbeatRunnable = object : Runnable {
+                override fun run() {
+                    dispatchNow()
+                    mainHandler.postDelayed(this, 5000)
+                }
+            }
+            mainHandler.postDelayed(heartbeatRunnable!!, 5000)
+        }
+    }
+    
     fun shutdown() {
         heartbeatRunnable?.let { mainHandler.removeCallbacks(it) }
         heartbeatRunnable = null

package/android/src/main/java/com/rejourney/utility/DataCompression.kt

@@ -17,21 +17,33 @@
 package com.rejourney.utility
 
 import java.io.ByteArrayOutputStream
+import java.io.OutputStream
+import java.util.zip.Deflater
 import java.util.zip.GZIPOutputStream
 
 /**
  * Data compression utilities
  * Android implementation aligned with iOS DataCompression.swift
+ * Uses level 9 (BEST_COMPRESSION) for smaller S3 payloads.
  */
 object DataCompression {
+
+    /**
+     * GZIPOutputStream that uses Deflater.BEST_COMPRESSION for maximum ratio.
+     */
+    private class GzipLevel9OutputStream(out: OutputStream) : GZIPOutputStream(out) {
+        init {
+            def.setLevel(Deflater.BEST_COMPRESSION)
+        }
+    }
     
     /**
-     * Compress data using gzip
+     * Compress data using gzip (level 9)
      */
     fun gzipCompress(data: ByteArray): ByteArray? {
         return try {
             val bos = ByteArrayOutputStream()
-            GZIPOutputStream(bos).use { gzip ->
+            GzipLevel9OutputStream(bos).use { gzip ->
                 gzip.write(data)
             }
             bos.toByteArray()

package/ios/Engine/RejourneyImpl.swift

@@ -110,6 +110,8 @@ public final class RejourneyImpl: NSObject {
             DiagnosticLog.notice("[Rejourney] ⏸️ Session '\(sid)' paused (app backgrounded)")
             TelemetryPipeline.shared.dispatchNow()
             SegmentDispatcher.shared.shipPending()
+            // Stop the heartbeat timer to prevent event uploads while backgrounded
+            TelemetryPipeline.shared.pause()
         }
     }
 
@@ -139,6 +141,9 @@ public final class RejourneyImpl: NSObject {
 
         DiagnosticLog.notice("[Rejourney] App foregrounded after \(Int(backgroundDuration))s (timeout: \(Int(sessionTimeoutSeconds))s)")
 
+        // Resume the heartbeat timer now that we're back in foreground
+        TelemetryPipeline.shared.resume()
+
         if backgroundDuration > sessionTimeoutSeconds {
             // End current session and start a new one
             state = .idle

package/ios/Recording/RejourneyURLProtocol.swift

@@ -38,14 +38,67 @@ public class RejourneyURLProtocol: URLProtocol, URLSessionDataDelegate, URLSessi
     
     @objc public static func enable() {
         URLProtocol.registerClass(RejourneyURLProtocol.self)
-        // Hook into default session configs
-        if let method = class_getInstanceMethod(URLSessionConfiguration.self, #selector(getter: URLSessionConfiguration.protocolClasses)) {
-            let original = method_getImplementation(method)
-            // Note: Safest swizzling approach for URLSessionConfiguration here is complex,
-            // standard approach is registering the protocol which covers shared sessions and simple setups.
+        
+        // Swizzle URLSessionConfiguration.protocolClasses to automatically inject our protocol
+        // into custom sessions (e.g. used by SDWebImage, AlamoFire, etc.)
+        swizzleProtocolClasses()
+    }
+    
+    private static var isSwizzled = false
+    
+    /// Store the original IMP so we can call through to it safely.
+    private static var originalProtocolClassesIMP: IMP?
+    
+    private static func swizzleProtocolClasses() {
+        guard !isSwizzled else { return }
+        
+        let configClass: AnyClass = URLSessionConfiguration.self
+        let originalSel = #selector(getter: URLSessionConfiguration.protocolClasses)
+        let swizzledSel = #selector(RejourneyURLProtocol.rj_protocolClasses)
+        
+        guard let originalMethod = class_getInstanceMethod(configClass, originalSel),
+              let swizzledMethod = class_getInstanceMethod(RejourneyURLProtocol.self, swizzledSel) else {
+            return
         }
+        
+        // Add the swizzled method onto URLSessionConfiguration itself so that
+        // method_exchangeImplementations works within a single class.
+        let didAdd = class_addMethod(
+            configClass,
+            swizzledSel,
+            method_getImplementation(swizzledMethod),
+            method_getTypeEncoding(swizzledMethod)
+        )
+        
+        if didAdd, let addedMethod = class_getInstanceMethod(configClass, swizzledSel) {
+            originalProtocolClassesIMP = method_getImplementation(originalMethod)
+            method_exchangeImplementations(originalMethod, addedMethod)
+        }
+        
+        isSwizzled = true
     }
     
+    /// Replacement getter injected into URLSessionConfiguration.
+    /// After exchange, `self` IS a URLSessionConfiguration instance.
+    @objc private func rj_protocolClasses() -> [AnyClass]? {
+        // Call through to the original implementation via the saved IMP
+        typealias OriginalFunc = @convention(c) (AnyObject, Selector) -> [AnyClass]?
+        var classes: [AnyClass] = []
+        
+        if let imp = RejourneyURLProtocol.originalProtocolClassesIMP {
+            let original = unsafeBitCast(imp, to: OriginalFunc.self)
+            classes = original(self, #selector(getter: URLSessionConfiguration.protocolClasses)) ?? []
+        }
+        
+        // Inject our protocol at the beginning if not already present
+        if !classes.contains(where: { $0 == RejourneyURLProtocol.self }) {
+            classes.insert(RejourneyURLProtocol.self, at: 0)
+        }
+        
+        return classes
+    }
+
+    
     @objc public static func disable() {
         URLProtocol.unregisterClass(RejourneyURLProtocol.self)
     }
@@ -62,11 +115,6 @@ public class RejourneyURLProtocol: URLProtocol, URLSessionDataDelegate, URLSessi
             return false
         }
         
-        // Ignore requests to the Rejourney API endpoints themselves to prevent ingestion duplication
-        if let host = url.host, host.contains("api.rejourney.co") {
-            return false
-        }
-        
         return true
     }
     

package/ios/Recording/ReplayOrchestrator.swift

@@ -451,6 +451,7 @@ public final class ReplayOrchestrator: NSObject {
         _visitedScreens.removeAll()
         _bgTimeMs = 0
         _bgStartMs = nil
+        _lastHierarchyHash = nil
 
         TelemetryPipeline.shared.currentReplayId = replayId
         SegmentDispatcher.shared.currentReplayId = replayId
@@ -674,9 +675,10 @@ public final class ReplayOrchestrator: NSObject {
         _lastHierarchyHash = hash
 
         guard let json = try? JSONSerialization.data(withJSONObject: hierarchy) else { return }
+        guard let compressed = json.gzipCompress() else { return }
         let ts = UInt64(Date().timeIntervalSince1970 * 1000)
 
-        SegmentDispatcher.shared.transmitHierarchy(replayId: sid, hierarchyPayload: json, timestampMs: ts, completion: nil)
+        SegmentDispatcher.shared.transmitHierarchy(replayId: sid, hierarchyPayload: compressed, timestampMs: ts, completion: nil)
     }
 
     private func _hierarchyHash(_ h: [String: Any]) -> String {

package/ios/Recording/TelemetryPipeline.swift

@@ -101,6 +101,25 @@ public final class TelemetryPipeline: NSObject {
         NotificationCenter.default.addObserver(self, selector: #selector(_appSuspending), name: UIApplication.willTerminateNotification, object: nil)
     }
     
+    /// Pause the heartbeat timer when the app goes to background.
+    /// This prevents the pipeline from uploading empty event batches
+    /// while backgrounded, which would inflate session duration.
+    @objc public func pause() {
+        _heartbeat?.invalidate()
+        _heartbeat = nil
+    }
+    
+    /// Resume the heartbeat timer when the app returns to foreground.
+    @objc public func resume() {
+        guard _heartbeat == nil else { return }
+        DispatchQueue.main.async { [weak self] in
+            guard let self else { return }
+            self._heartbeat = Timer.scheduledTimer(withTimeInterval: 5, repeats: true) { [weak self] _ in
+                self?.dispatchNow()
+            }
+        }
+    }
+    
     @objc public func shutdown() {
         _heartbeat?.invalidate()
         _heartbeat = nil
@@ -207,9 +226,13 @@ public final class TelemetryPipeline: NSObject {
         let isConstrained = ReplayOrchestrator.shared.networkIsConstrained
         let isExpensive = ReplayOrchestrator.shared.networkIsExpensive
         
+        // Prefer detailed hardware model (e.g. "iPhone16,1") when available,
+        // falling back to the generic UIDevice.model ("iPhone", "iPad", etc.).
+        let hardwareModel = (DeviceRegistrar.shared.gatherDeviceProfile()["hwModel"] as? String) ?? device.model
+        
         let meta: [String: Any] = [
             "platform": "ios",
-            "model": device.model,
+            "model": hardwareModel,
             "osVersion": device.systemVersion,
             "vendorId": device.identifierForVendor?.uuidString ?? "",
             "time": Date().timeIntervalSince1970,
@@ -276,9 +299,12 @@ public final class TelemetryPipeline: NSObject {
         let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "unknown"
         let appId = Bundle.main.bundleIdentifier ?? "unknown"
         
+        // Prefer detailed hardware model from DeviceRegistrar when available.
+        let hardwareModel = (DeviceRegistrar.shared.gatherDeviceProfile()["hwModel"] as? String) ?? device.model
+        
         let meta: [String: Any] = [
             "platform": "ios",
-            "model": device.model,
+            "model": hardwareModel,
             "osVersion": device.systemVersion,
             "vendorId": device.identifierForVendor?.uuidString ?? "",
             "time": Date().timeIntervalSince1970,

package/ios/Recording/VisualCapture.swift

@@ -327,7 +327,7 @@ public final class VisualCapture: NSObject {
         
         guard !images.isEmpty else { return }
         
-        // All heavy work (tar, gzip, network) happens in background queue
+        // All heavy work (package, gzip, network) happens in background queue
         _encodeQueue.addOperation { [weak self] in
             self?._packageAndShip(images: images, sessionEpoch: sessionEpoch)
         }
@@ -466,34 +466,38 @@ public final class VisualCapture: NSObject {
         )
     }
     
+    /// Android-compatible binary format: [8-byte BE timestamp offset][4-byte BE size][jpeg] per frame. Backend auto-detects.
     private func _packageFrameBundle(images: [(Data, UInt64)], sessionEpoch: UInt64) -> Data? {
         var archive = Data()
-        
         for (jpeg, timestamp) in images {
-            let name = "\(sessionEpoch)_1_\(timestamp).jpeg"
-            archive.append(_tarHeader(name: name, size: jpeg.count))
+            let tsOffset = timestamp - sessionEpoch
+            archive.append(_uint64BigEndian(tsOffset))
+            archive.append(_uint32BigEndian(UInt32(jpeg.count)))
             archive.append(jpeg)
-            let padding = (512 - (jpeg.count % 512)) % 512
-            if padding > 0 { archive.append(Data(repeating: 0, count: padding)) }
         }
-        
-        archive.append(Data(repeating: 0, count: 1024))
         return archive.gzipCompress()
     }
     
-    private func _tarHeader(name: String, size: Int) -> Data {
-        var h = Data(count: 512)
-        if let nd = name.data(using: .utf8) { h.replaceSubrange(0..<min(100, nd.count), with: nd.prefix(100)) }
-        "0000644\0".data(using: .utf8).map { h.replaceSubrange(100..<108, with: $0) }
-        let z = "0000000\0".data(using: .utf8)!
-        h.replaceSubrange(108..<124, with: z + z)
-        String(format: "%011o\0", size).data(using: .utf8).map { h.replaceSubrange(124..<136, with: $0) }
-        String(format: "%011o\0", Int(Date().timeIntervalSince1970)).data(using: .utf8).map { h.replaceSubrange(136..<148, with: $0) }
-        h[156] = 0x30
-        "        ".data(using: .utf8).map { h.replaceSubrange(148..<156, with: $0) }
-        let sum = h.reduce(0) { $0 + Int($1) }
-        String(format: "%06o\0 ", sum).data(using: .utf8).map { h.replaceSubrange(148..<156, with: $0) }
-        return h
+    private func _uint64BigEndian(_ value: UInt64) -> Data {
+        Data([
+            UInt8((value >> 56) & 0xff),
+            UInt8((value >> 48) & 0xff),
+            UInt8((value >> 40) & 0xff),
+            UInt8((value >> 32) & 0xff),
+            UInt8((value >> 24) & 0xff),
+            UInt8((value >> 16) & 0xff),
+            UInt8((value >> 8) & 0xff),
+            UInt8(value & 0xff)
+        ])
+    }
+    
+    private func _uint32BigEndian(_ value: UInt32) -> Data {
+        Data([
+            UInt8((value >> 24) & 0xff),
+            UInt8((value >> 16) & 0xff),
+            UInt8((value >> 8) & 0xff),
+            UInt8(value & 0xff)
+        ])
     }
 }