iidrak-analytics-react 1.5.0 → 1.6.0

package/README.md

@@ -5,7 +5,9 @@ A powerful, offline-first analytics SDK for React Native applications that inclu
 ## Features
 
 - 📊 **Event Tracking**: Log custom events with arbitrary parameters.
+- 🚀 **Optimized Bandwidth**: Uses a Minimal Payload architecture for auto-clicks to save battery, data, and database costs, only sending full telemetry on session starts.
 - 🎥 **Session Replay**: Record screen interactions and touch events for playback analysis.
+- 🎯 **Advanced Touch Context**: Automatically maps React Fiber tree to extract clicked text, component paths (e.g. `TouchableOpacity > Text`), and testing IDs without manual instrumentation.
 - 🛒 **Cart Management**: Built-in shopping cart state management.
 - 📴 **Offline Support**: Automatically queues events when offline and flushes them when connection is restored.
 - 🆔 **User & Session Management**: Auto-generates session IDs and supports user identification.

package/documentation.md

@@ -0,0 +1,39 @@
+# MetaStreamIO (iidrak-analytics-react) Documentation
+
+## Overview
+`iidrak-analytics-react` is a robust, offline-capable React Native analytics and session recording SDK. It is designed to capture user behavior smoothly without bloated payloads or manual developer instrumentation.
+
+## Key Architecture Concepts
+
+### 1. Minimal Payload Optimization
+Traditional analytics tools drain user battery and network bandwidth by repeatedly sending static parameters (like the phone model, app version, and network status) on every single button tap.
+
+Our SDK is heavily optimized. It sends a **Full Payload** only when a user initiates a session (`session_start`). For all subsequent thousands of interactions (like screen taps, swiping, or custom events), the SDK dynamically strips out these static properties and transmits a **Minimal Payload**. 
+
+This allows you to link all data backend via the unique `Session ID` while processing millions of events per second with virtually zero bandwidth overhead.
+
+### 2. Auto Component Mapping
+By wrapping your application in the `MetaStreamProvider`, the SDK hooks directly into the React Native rendering engine (the Fiber Tree). When a user taps the screen, the SDK crawls up the UI tree in milliseconds to discover context.
+
+This means a raw X/Y tap instantly becomes:
+- **`component_type`**: E.g., `Text`, `TextInput`, `Image`.
+- **`text_content`**: The literal word the user tapped on (e.g. `Add to Cart`).
+- **`component_path`**: The ancestry tree of where this tap occurred (`Text > TouchableOpacity > ScrollViewContainer`).
+
+### 3. Queue Strategy
+The SDK contains a powerful offline-first buffering engine. 
+- All interactions are serialized into models and placed into a robust internal device queue.
+- If the device drops offline, the queue enters sleep mode.
+- The moment the device connection is restored, the queue securely processes and flushes the backlog to your collector endpoints.
+
+## Example Backend Ingestion Strategy
+
+Since payloads arrive in `MINIMAL` formats, it is up to your analytics backend to enrich the clickstream.
+
+**Example ingestion:**
+1. A `session_start` event arrives: INSERT to `Sessions` table. (Contains device height, memory, version).
+2. A `login_success` minimal event arrives: INSERT to `Events` table, linking via `session_id`.
+3. An `auto_click` minimal event arrives: INSERT to `Interactions` table. Your dashboard runs a `JOIN` on the `Sessions` table using the `session_id` to build heatmaps segmented by the user's specific screen size.
+
+---
+*Generated automatically by MetaStream SDK documentation builder.*

package/metastreamio/metastreamio.interface.js

@@ -197,6 +197,14 @@ class MetaStreamIO {
         });
         // Update recorder session ID
         if (this.recorder) this.recorder.setSessionId(this.session.session.id);
+        
+        // Push the full payload event to register the session
+        setTimeout(() => {
+          this.trackEvent({
+             eventName: "session_start",
+             eventParameters: [],
+          });
+        }, 1500); // Small delay to allow enriching device info before it queues
       }
     } catch (err) {
       errors.push("session");
@@ -365,35 +373,66 @@ class MetaStreamIO {
       ) {
         this.logger.log("event", this.constant.MetaStreamIO_Log_SendOnce);
       } else {
-        let e = new EventModel({
-          account_balances: this.utility.copyObject(
-            this.account.account.list()
-          ),
-          account_type: this.account.account.type,
-          app: this.app_id,
-          app_environment: this.app_environment,
-          app_info: null,
-          app_performance: null,
-          cart: cart,
-          cart_id: temporaryCart ? temporaryCart.id : this.cart.cart.id,
-          channel: this.channel,
-          ciam_id: this.user.ciam_id,
-          client_event_date: client_event_date,
-          client_event_timestamp: client_event_timestamp,
-          device: null,
-          device_token: this.user.device_token,
-          email_id: this.user.email_id,
-          event_name: eventName,
-          event_params: tempEventParameters,
-          network: null,
-          session: this.utility.copyObject(
-            this.session.logSession(this.previous.event_time)
-          ),
-          transaction_id: transactionId,
-          user_id: this.user.id,
-          user_country: this.user.country,
-          user_properties: this.utility.copyObject(this.userproperties.list()),
-        });
+        let e;
+        
+        if (eventName === 'auto_click') {
+          // MINIMAL PAYLOAD FOR AUTO CLICKS
+          e = new EventModel({
+            app: this.app_id,
+            app_environment: this.app_environment,
+            client_event_date: client_event_date,
+            client_event_timestamp: client_event_timestamp,
+            event_name: eventName,
+            event_params: tempEventParameters,
+            session: { id: this.session.session.id }, // Just pass session ID
+            user_id: this.user.id,
+            // Skip everything else to save bandwidth
+            device: null,
+            app_info: null,
+            app_performance: null,
+            network: null,
+            user_properties: null,
+            account_balances: null,
+            account_type: null,
+            cart: null,
+            user_country: null,
+            email_id: null,
+            device_token: null,
+            ciam_id: null,
+            channel: null
+          });
+        } else {
+          // FULL PAYLOAD FOR CUSTOM EVENTS & SESSION START
+          e = new EventModel({
+            account_balances: this.utility.copyObject(
+              this.account.account.list()
+            ),
+            account_type: this.account.account.type,
+            app: this.app_id,
+            app_environment: this.app_environment,
+            app_info: null,
+            app_performance: null,
+            cart: cart,
+            cart_id: temporaryCart ? temporaryCart.id : this.cart.cart.id,
+            channel: this.channel,
+            ciam_id: this.user.ciam_id,
+            client_event_date: client_event_date,
+            client_event_timestamp: client_event_timestamp,
+            device: null,
+            device_token: this.user.device_token,
+            email_id: this.user.email_id,
+            event_name: eventName,
+            event_params: tempEventParameters,
+            network: null,
+            session: this.utility.copyObject(
+              this.session.logSession(this.previous.event_time)
+            ),
+            transaction_id: transactionId,
+            user_id: this.user.id,
+            user_country: this.user.country,
+            user_properties: this.utility.copyObject(this.userproperties.list()),
+          });
+        }
 
         this.storeEventMeta({
           eventTimestamp: client_event_timestamp,
@@ -495,15 +534,17 @@ class MetaStreamIO {
   async runQueue() {
     return this.queue.run(
       async function (event) {
-        // Enrich
-        event.app_info = await this.environment.logAppInfo().catch(() => null);
-        event.app_performance = await this.environment
-          .logAppPerformance()
-          .catch(() => null);
-        event.device = await this.environment.logDevice().catch(() => null);
-        event.network = await this.environment
-          .logNetworkInfo()
-          .catch(() => null);
+        // Enrich only ONE time per session to save battery/bandwidth
+        if (event.event_name === 'session_start') {
+          event.app_info = await this.environment.logAppInfo().catch(() => null);
+          event.app_performance = await this.environment
+            .logAppPerformance()
+            .catch(() => null);
+          event.device = await this.environment.logDevice().catch(() => null);
+          event.network = await this.environment
+            .logNetworkInfo()
+            .catch(() => null);
+        }
 
         let response = await this.post_event(event.json())
           .then((res) => {

package/metastreamio/metastreamio.network.js

@@ -52,53 +52,35 @@ class MetaStreamIONetwork {
       }
     });
 
-    // Background heartbeat to auto-flush stuck events gracefully
     this._flushInterval = setInterval(() => {
       this.flushEvents();
-    }, 3000); // Poll every 3 seconds for perfect sync
+    }, 3000); // Reverted back to 3 seconds. (Locking guarantees safety)
   }
 
   reset() {
     this.endpoint = null;
+    this._testingPromise = null;
   }
 
   async testConnection() {
-    if (!this.endpoint || this.endpoint === null) {
+    if (this.endpoint) return Promise.resolve(this.endpoint);
+    if (this._testingPromise) return this._testingPromise;
+
+    this._testingPromise = (async () => {
       for (let _e in this.endpoints) {
-        this.endpoint = await this.getData({ endpoint: this.endpoints[_e] })
-          .then((data) => {
-            try {
-              if (data && data.status > 0) {
-                return this.endpoints[_e];
-              }
-              return false;
-            } catch (err) {
-              return false;
-            }
-          })
-          .catch(() => { return false; });
-        if (this.endpoint) {
-          this.logger.log(
-            "network",
-            this.constant.MetaStreamIO_Network_EndpointSet.format(this.endpoint)
-          );
+        let testEp = await this.getData({ endpoint: this.endpoints[_e] });
+        if (testEp && testEp.status > 0) {
+          this.logger.log("network", this.constant.MetaStreamIO_Network_EndpointSet.format(this.endpoints[_e]));
+          this.endpoint = this.endpoints[_e];
           break;
         } else {
-          this.logger.log(
-            "network",
-            this.constant.MetaStreamIO_Network_EndpointTestFailed.format(
-              this.endpoint
-            )
-          );
-          this.logger.log(
-            "network",
-            this.constant.MetaStreamIO_Network_SilentModeEnabled
-          );
+          this.logger.log("network", this.constant.MetaStreamIO_Network_EndpointTestFailed.format(this.endpoints[_e]));
         }
       }
-    }
-
-    return Promise.resolve(this.endpoint);
+      this._testingPromise = null;
+      return this.endpoint;
+    })();
+    return this._testingPromise;
   }
 
   async getData({ endpoint = this.endpoint } = {}) {
@@ -115,14 +97,16 @@ class MetaStreamIONetwork {
       get_config.headers = Object.assign(get_config.headers, this.headers);
     }
 
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 3000);
+    get_config.signal = controller.signal;
+
     try {
-      const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), 3000));
-      const response = await Promise.race([
-        fetch(endpoint, get_config),
-        timeoutPromise
-      ]);
+      const response = await fetch(endpoint, get_config);
+      clearTimeout(timeoutId);
       return { status: response.status, body: "OK" };
     } catch (err) {
+      clearTimeout(timeoutId);
       return { status: 0, body: String(err) };
     }
   }
@@ -229,13 +213,13 @@ class MetaStreamIONetwork {
       return { status: 200, body: "Stored offline" };
     }
 
-    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), 3000));
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 3000);
+    post_config.signal = controller.signal;
 
-    await Promise.race([
-      fetch(endpoint, post_config),
-      timeoutPromise
-    ])
+    await fetch(endpoint, post_config)
       .then((response) => {
+        clearTimeout(timeoutId);
         rx.status = response.status;
         let _contentType = response.headers.get("content-type");
         if (!_contentType || !_contentType.includes("application/json")) {
@@ -252,6 +236,7 @@ class MetaStreamIONetwork {
         }
       })
       .catch(async (err) => {
+        clearTimeout(timeoutId);
         this.logger.warn("network", "fetch() error in post()", err.message || err);
         rx.status = 500;
         rx.body = "fetch error";
@@ -303,11 +288,18 @@ class MetaStreamIONetwork {
       // Pre-flight check: Do not spam the Native Bridge with 20 offline events if the server route is down
       const pingEndpoint = this.endpoint || (this.endpoints.length > 0 ? this.endpoints[0] : null);
       if (pingEndpoint) {
-        const pingTimeout = new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), 1500));
-        const routeValid = await Promise.race([
-          fetch(pingEndpoint, { method: "OPTIONS" }),
-          pingTimeout
-        ]).then(() => true).catch(() => false);
+        let routeValid = false;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 1500);
+
+        try {
+          await fetch(pingEndpoint, { method: "OPTIONS", signal: controller.signal });
+          routeValid = true;
+        } catch (err) {
+          routeValid = false;
+        } finally {
+          clearTimeout(timeoutId);
+        }
 
         if (!routeValid) {
           this.logger.log("network", "flushEvents aborted: Node route not fully established natively yet.");
@@ -322,17 +314,17 @@ class MetaStreamIONetwork {
         if (this.headers) {
           reqHeaders = Object.assign(reqHeaders, this.headers);
         }
-        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), 3000));
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 3000);
 
         try {
-          const response = await Promise.race([
-            fetch(e.endpoint, {
-              method: "POST",
-              headers: reqHeaders,
-              body: JSON.stringify(e.payload),
-            }),
-            timeoutPromise
-          ]);
+          const response = await fetch(e.endpoint, {
+            method: "POST",
+            headers: reqHeaders,
+            body: JSON.stringify(e.payload),
+            signal: controller.signal
+          });
+          clearTimeout(timeoutId);
 
           if (response.ok) {
             this.logger.log("network", "Retried & sent event successfully.");
@@ -340,6 +332,7 @@ class MetaStreamIONetwork {
             this.logger.warn("network", `Retry got non-OK status (${response.status}), dropping event.`);
           }
         } catch (err) {
+          clearTimeout(timeoutId);
           this.logger.log("network", "Retry failed (still offline or bad host), keeping event.", err.message);
           remainingEvents.push(e);
         }

package/metastreamio/metastreamio.provider.js

@@ -23,6 +23,69 @@ class MetaStreamProvider extends Component {
         if (this.tracker && this.tracker.recorder) {
             this.tracker.recorder.recordInteraction(type, e.nativeEvent);
         }
+
+        // Auto-capture all screen taps/clicks
+        if (type === 'touch_end' && this.tracker && typeof this.tracker.trackEvent === 'function') {
+            const { pageX, pageY, locationX, locationY, target, timestamp } = e.nativeEvent;
+            
+            let componentType = 'unknown';
+            let testID = 'none';
+            let accessibilityLabel = 'none';
+            let textContent = '';
+            let componentPath = [];
+            
+            // Traverse the React Fiber tree to extract component names, text, and testIDs
+            try {
+                let fiber = e._targetInst;
+                while (fiber) {
+                    if (fiber.memoizedProps) {
+                        if (testID === 'none' && fiber.memoizedProps.testID) testID = fiber.memoizedProps.testID;
+                        if (accessibilityLabel === 'none' && fiber.memoizedProps.accessibilityLabel) accessibilityLabel = fiber.memoizedProps.accessibilityLabel;
+                        
+                        // Extract text content if available
+                        let children = fiber.memoizedProps.children;
+                        if (!textContent && typeof children === 'string') {
+                            textContent = children;
+                        } else if (!textContent && Array.isArray(children)) {
+                            const stringChildren = children.filter(c => typeof c === 'string').join('');
+                            if (stringChildren) textContent = stringChildren;
+                        }
+                    }
+                    
+                    // Try to get the component's name (e.g., 'Text', 'RCTImageView', 'Button')
+                    if (fiber.elementType) {
+                        let name = typeof fiber.elementType === 'string' ? fiber.elementType : (fiber.elementType.name || fiber.elementType.displayName);
+                        if (name) {
+                            if (name !== 'View' && name !== 'RCTView' && componentType === 'unknown') {
+                                componentType = name;
+                            }
+                            // Build a path of component hierarchy (limit to nearest 5 interesting elements to avoid giant payload)
+                            if (name !== 'View' && name !== 'RCTView' && componentPath.length < 5) {
+                                componentPath.push(name);
+                            }
+                        }
+                    }
+                    fiber = fiber.return; // Traverse up the tree
+                }
+            } catch (err) {
+                // Ignore any errors if structure changes in future RN versions
+            }
+            
+            this.tracker.trackEvent({
+                eventName: 'auto_click',
+                eventParameters: [
+                    { key: 'x', value: Math.round(pageX || locationX || 0) },
+                    { key: 'y', value: Math.round(pageY || locationY || 0) },
+                    { key: 'target_node', value: target ? String(target) : 'unknown' },
+                    { key: 'component_type', value: String(componentType) },
+                    { key: 'component_path', value: componentPath.join(' > ') || 'unknown' },
+                    { key: 'text_content', value: textContent ? String(textContent) : 'none' },
+                    { key: 'test_id', value: String(testID) },
+                    { key: 'accessibility_label', value: String(accessibilityLabel) },
+                    { key: 'timestamp', value: timestamp || Date.now() }
+                ]
+            });
+        }
     }
 
     render() {

package/metastreamio/metastreamio.queue.js

@@ -57,12 +57,19 @@ Queue.prototype.peek = function () {
  * The MetaStreamIO SAUCE
  *
  */
-Queue.prototype.run = function (callback) {
-  while (this.size() > 0) {
-    callback(this.dequeue()).catch(err => {
-      console.error('<queue callback>', err);
-    });
+Queue.prototype.run = async function (callback) {
+  if (this._isRunning) return;
+  this._isRunning = true;
+
+  try {
+    while (this.size() > 0) {
+      await callback(this.dequeue()).catch(err => {
+        console.error('<queue callback>', err);
+      });
+    }
+  } finally {
+    this._isRunning = false;
   }
 };
 
-export {Queue};
+export { Queue };

package/metastreamio/metastreamio.recorder.js

@@ -139,9 +139,14 @@ class MetaStreamIORecorder {
             // Note: We use a separate fetch here because the payload format is different from standard analytics
             const url = `${this.endpoint}/api/apps/${this.app_id}/sessions`;
             this.logger.log("recorder", `Sending session creation request to: ${url}`);
+
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 3000);
+
             await fetch(url, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
+                signal: controller.signal,
                 body: JSON.stringify({
                     session_id: this.sessionId,
                     device_info: {
@@ -152,6 +157,7 @@ class MetaStreamIORecorder {
                     }
                 })
             }).then(async res => {
+                clearTimeout(timeoutId);
                 this.logger.log("recorder", "Session creation response status: " + res.status);
                 if (res.ok) {
                     const data = await res.json();
@@ -164,6 +170,7 @@ class MetaStreamIORecorder {
                     this.logger.error("recorder", "Failed to start session on recording server: " + res.status);
                 }
             }).catch(e => {
+                clearTimeout(timeoutId);
                 this.logger.error("recorder", "Connection error to recording server: " + e + " to " + url);
             });
 
@@ -200,6 +207,9 @@ class MetaStreamIORecorder {
         console.log("Starting loop");
         this.intervalId = setInterval(async () => {
             if (!viewRef.current) return;
+            if (this._isCapturing) return;
+
+            this._isCapturing = true;
 
             try {
                 // Capture as base64 for comparison and direct upload
@@ -241,13 +251,15 @@ class MetaStreamIORecorder {
                     // Measure privacy zones
                     const zones = await this.measurePrivacyZones(viewRef);
 
-                    console.log("DBG:: Uploading frame with " + zones.length + " privacy zones");
-                    this.uploadFrame(base64, isDuplicate, zones);
+                    // console.log("DBG:: Uploading frame with " + zones.length + " privacy zones");
+                    await this.uploadFrame(base64, isDuplicate, zones);
                     this.lastUploadTime = now;
                     this.lastBase64 = base64;
                 }
             } catch (e) {
                 // Silent fail on capture error to avoid log spam
+            } finally {
+                this._isCapturing = false;
             }
         }, intervalMs);
     }
@@ -277,13 +289,18 @@ class MetaStreamIORecorder {
         }
 
         try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 1500);
+
             await fetch(`${this.endpoint}/api/apps/${this.app_id}/sessions/${this.recorderSessionId}/screenshot`, {
                 method: 'POST',
                 body: formData,
                 headers: {
                     'Content-Type': 'multipart/form-data',
-                }
+                },
+                signal: controller.signal
             });
+            clearTimeout(timeoutId);
         } catch (e) {
             // Network error, drop frame
         }
@@ -304,11 +321,15 @@ class MetaStreamIORecorder {
         };
 
         try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 1500);
+
             fetch(`${this.endpoint}/api/apps/${this.app_id}/sessions/${this.recorderSessionId}/events`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify([event])
-            }).catch(() => { });
+                body: JSON.stringify([event]),
+                signal: controller.signal
+            }).then(() => clearTimeout(timeoutId)).catch(() => clearTimeout(timeoutId));
         } catch (e) { }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iidrak-analytics-react",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "react native client for metastreamio",
   "peerDependencies": {
     "react-native-mmkv": ">=4.0.0",