iidrak-analytics-react 1.5.1 → 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.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/package.json

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