Iidrak Analytics (React Web)

A powerful, offline-first analytics SDK for React Web applications that includes Session Replay. Track events, manage shopping carts, record user sessions (DOM mutations & interactions), and persist data reliably even when the network is down.

Features

• 🖱️ Zero-Code Auto Capture: Automatically captures every click, touch, and interaction across your entire application without manual tagging.
• 📊 Custom Event Tracking: Log specific business events, conversions, or user actions with flexible parameters.
• 🚀 Optimized Bandwidth: Uses a Minimal Payload architecture for auto-clicks to save network requests and database costs, only sending full browser/device telemetry on session starts.
• 🎥 Session Replay: Record DOM interactions and mouse/touch events for playback analysis without heavy video streaming.
• 🎯 Deep Context Discovery: Automatically extracts text content, component paths (e.g. DIV.card > BUTTON), and testing IDs for every interaction natively.
• 🛒 Cart Management: Built-in shopping cart state management.
• 📴 Offline Support: Automatically queues events in localStorage when offline and flushes them when connection is restored.
• 🆔 User & Session Management: Auto-generates session IDs and supports user identification.
• ⚡ Lightweight: Minimal performance overhead, optimized for web browsers.

Installation

This package relies on several dependencies for DOM capture and data formatting. It is designed specifically for standard React web applications.

npm install iidrak-analytics-react-web

Note: This package strictly uses html2canvas for cross-browser web screenshots. Do not use this package for React Native mobile apps (use iidrak-analytics-react instead).

Getting Started

1. Initialize the SDK

Create an instance of MetaStreamIO with your configuration. This is usually done in your root component file (e.g., App.jsx or App.js).

Configuration Payload Format:

import { MetaStreamIO, MetaStreamProvider } from 'iidrak-analytics-react-web';

const iidrakConfig = {
  // Application Details
  app: {
    id: "your-app-id",           // Required: Unique ID for your app
    channel: "web",              // Set to 'web'
    environment: "production",   // Optional: 'dev', 'staging', 'production'
    endpoints: ["https://your-analytics-collector.com/collect"], // Analytics Endpoint
    headers: {},                 // Optional: Custom headers for requests
  },

  // SDK Configuration
  config: {
    appName: "your-web-app",

    // Session Replay Endpoint (Required to enable automatic capture)
    recordingEndpoint: "https://your-replay-server.com", 
    
    logging: true,               // Enable console logs
    loggingLevel: 'INFO',        // 'INFO', 'WARN', 'ERROR'
    silentMode: false,           // Disables all logging if true
    sessionLength: 1800,         // Session timeout in seconds (e.g. 30 mins)
    quality: 0.7,                // Recording quality scale (higher = sharper, larger payload)
    fps: 2,                      // Frames Per Second for capture polling
  },

  user: {
    guestMode: true,             // Start as guest
    user_id: "user_123",         // Optional: Known user ID
    country: "US",
  },
};

// Initialize the tracker
const tracker = new MetaStreamIO(iidrakConfig);

2. Wrap Your App

To enable Session Replay and auto-capture of interactions, wrap your entire application with the MetaStreamProvider. Pass the initialized tracker instance to it.

function App() {
  return (
    <MetaStreamProvider tracker={tracker}>
       {/* Your Web App Components */}
       <YourRouterRoot />
    </MetaStreamProvider>
  );
}

Usage

1. Starting a Session

Call this when your app loads or when a user logs in. If recordingEndpoint is configured, this will also start the Session Replay recorder.

tracker.start_session({
    user_id: "user_123",  // Update user ID
});

2. Tracking Events

You can track any custom event. The payload requires an eventName and optional eventParameters.

tracker.trackEvent({
  eventName: "add_to_cart",
  eventParameters: [
    { key: "product_id", value: "prod_999" },
    { key: "price", value: 29.99 },
    { key: "category", value: "shoes" }
  ]
});

3. Screen Tracking

Though MetaStreamProvider captures the DOM state, you can manually log screen views for standard analytics dashboards:

tracker.screen("Dashboard", {});

4. Privacy & Redaction

To protect sensitive user data (PII) like passwords or credit card numbers during session replay, wrap your sensitive HTML components with the <Redact> component.

import { Redact } from 'iidrak-analytics-react-web';

<Redact>
  <input
    type="password"
    placeholder="Enter Password"
    onChange={(e) => setPassword(e.target.value)}
  />
</Redact>

This ensures the wrapped area is covered by a privacy mask in the recorded video playback, while remaining fully functional for the actual user in the browser.

5. Suppressing Auto-Capture

By default, the SDK captures every click on the application. To prevent the SDK from sending an auto_click event for a specific element (for example, when you are already manually tracking a custom event on that same button), add the data-auto-track="false" attribute.

Example:

// This button will trigger 'login_success' but will NOT trigger a redundant 'auto_click'
<button 
  onClick={handleLogin} 
  data-auto-track="false"
>
  Sign In
</button>

This ensures your server doesn't receive duplicate data for the same user interaction.

Troubleshooting

"CORS policy blocked access"

Browsers enforce Strict Object Request policies. Ensure your Analytics and Replay Servers emit the Access-Control-Allow-Origin: * headers for endpoints responding to your React front-end.

License

MIT