iidrak-analytics-react 1.5.1 → 1.7.0

package/README.md

@@ -1,15 +1,21 @@
 # Iidrak Analytics (React Native)
 
+**NPM Package**: [iidrak-analytics-react](https://www.npmjs.com/package/iidrak-analytics-react)
+
+
 A powerful, offline-first analytics SDK for React Native applications that includes **Session Replay**. Track events, manage shopping carts, record user sessions (screens & touches), and persist data reliably even when the network is down.
 
 ## Features
 
 - 📊 **Event Tracking**: Log custom events with arbitrary parameters.
+- ⚡ **Automatic Interaction Tracking**: All screen taps/clicks are automatically captured with zero manual instrumentation.
+- 🚀 **Optimized Bandwidth**: Uses a Minimal Payload architecture for auto-clicks to save battery, data, and database costs, only sending full telemetry on session starts and custom events.
 - 🎥 **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.
 - 🛒 **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.
-- ⚡ **Lightweight**: Minimal performance overhead.
+- ⚡ **Zero Performance Impact**: Minimal overhead due to payload optimization and background processing.
 
 ## Installation
 
@@ -152,7 +158,20 @@ tracker.trackEvent({
 ```
 *Note: `eventParameters` creates a flexible dictionary of data associated with the event.*
 
-### 3. Screen Tracking
+### 3. Automatic Event Tracking (Zero Config)
+
+The SDK automatically tracks all user interactions (clicks/taps) without any manual coding. When a user interacts with the app, the SDK captures:
+
+- **Component Path**: The hierarchy of the clicked element (e.g., `TouchableOpacity > View > Text`).
+- **Text Content**: Any text visible within the clicked element.
+- **Test ID**: The `testID` prop, if defined (ideal for automated testing analysis).
+- **Coordinates**: The exact `x, y` position of the tap.
+- **Metadata**: Component type, accessibility labels, and timestamps.
+
+**Performance Optimization (Minimal Payload):**
+To ensure high performance and low data usage, `auto_click` events use a "Minimal Payload" architecture. They omit redundant device and application metadata, which is instead captured once during the `session_start` event.
+
+### 4. Screen Tracking
 
 Though `MetaStreamProvider` captures the video, you can manually log screen views for analytics:
 
@@ -160,7 +179,7 @@ Though `MetaStreamProvider` captures the video, you can manually log screen view
 tracker.screen("HomeScreen", {});
 ```
 
-### 4. Privacy & Redaction
+### 5. Privacy & Redaction
 
 To protect sensitive user data (PII) like passwords or credit card numbers during session replay, wrap your sensitive components with the `<Redact>` component.
 
@@ -178,7 +197,29 @@ import { Redact } from 'iidrak-analytics-react';
 
 This ensures the wrapped area is covered by a privacy mask in the recorded video, while remaining fully functional for the user.
 
-### 5. Shopping Cart
+### 6. Suppressing Auto-Capture
+
+By default, the SDK captures every tap on the application as an `auto_click` event. To prevent this for a specific component (e.g., when you are already manually tracking a custom event on that button), add the `autoTrack={false}` prop.
+
+**Example:**
+
+```javascript
+/* 
+   This button will trigger 'login_success' but will NOT trigger 
+   a redundant 'auto_click' event.
+*/
+<TouchableOpacity 
+  onPress={handleLogin} 
+  autoTrack={false}
+>
+  <Text>Sign In</Text>
+</TouchableOpacity>
+```
+
+This ensures your server doesn't receive duplicate data for the same interaction.
+
+
+### 6. Shopping Cart
 
 Manage a persistent shopping cart state:
 

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,94 @@ 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
+            let suppressAutoClick = false;
+            try {
+                let fiber = e._targetInst;
+                while (fiber) {
+                    const name = typeof fiber.elementType === 'string' ? fiber.elementType : (fiber.elementType?.name || fiber.elementType?.displayName || fiber.type?.name || 'Unknown');
+                    
+                    const p1 = fiber.memoizedProps || {};
+                    const p2 = fiber.pendingProps || {};
+                    
+                    const suppressValue = 
+                        p1['autoTrack'] ?? p1['auto-track'] ?? p1['data-auto-track'] ??
+                        p2['autoTrack'] ?? p2['auto-track'] ?? p2['data-auto-track'];
+
+                    if (suppressValue !== undefined) {
+                        if (String(suppressValue) === 'false' || suppressValue === false) {
+                            suppressAutoClick = true;
+                        }
+                    }
+
+                    if (fiber.memoizedProps) {
+                        const tid = fiber.memoizedProps.testID || fiber.memoizedProps.accessibilityLabel;
+                        if (testID === 'none' && tid) testID = tid;
+                        
+                        // FAIL-SAFE: If we see 'no-track' in the testID or Label, suppress it!
+                        if (typeof tid === 'string' && tid.toLowerCase().includes('no-track')) {
+                            suppressAutoClick = true;
+                        }
+                        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) {
+                        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
+            }
+            
+            if (suppressAutoClick) {
+                return;
+            }
+            
+            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.7.0",
   "description": "react native client for metastreamio",
   "peerDependencies": {
     "react-native-mmkv": ">=4.0.0",