iidrak-analytics-react 1.2.4

package/README.md

@@ -0,0 +1,170 @@
+# Iidrak Analytics (React Native)
+
+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.
+- 🎥 **Session Replay**: Record screen interactions and touch events for playback analysis.
+- 🛒 **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.
+
+## Installation
+
+This package relies on several peer dependencies for device info, storage, and screen capture. You must install them in your project.
+
+```bash
+npm install iidrak-analytics-react
+
+# Install required peer dependencies
+npm install @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-view-shot
+```
+
+**iOS Users**: after installing, remember to run:
+```bash
+cd ios && pod install
+```
+
+**Android Users**: ensuring linking works may require a clean build:
+```bash
+cd android && ./gradlew clean
+```
+
+## 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.tsx` or `App.js`).
+
+**Configuration Payload Format:**
+The configuration object requires strict structure for `app`, `config`, and `user` keys.
+
+```javascript
+import { MetaStreamIO, MetaStreamProvider } from 'iidrak-analytics-react';
+
+const iidrakConfig = {
+  // Application Details
+  app: {
+    id: "your-app-id",           // Required: Unique ID for your app
+    channel: "mobile",           // Optional: 'mobile', 'web', etc.
+    environment: "production",   // Optional: 'dev', 'staging', 'production'
+    endpoints: ["https://your-analytics-collector.com/collect"], // Analytics Server URL
+    headers: {                   // Optional: Custom headers for requests
+        "Authorization": "Bearer token" 
+    },
+  },
+
+  // SDK Configuration
+  config: {
+    // Session Replay Endpoint (Required to enable recording)
+    recordingEndpoint: "https://your-replay-server.com", 
+    
+    logging: true,               // Enable console logs
+    loggingLevel: 'INFO',        // 'INFO', 'WARN', 'ERROR'
+    silentMode: false,           // If true, disables all logging
+    sessionLength: 1800,         // Session timeout in seconds (e.g. 30 mins)
+    quality: 0.5,                // Recording quality (0.1 - 1.0)
+    fps: 2,                      // Frames Per Second for recording
+  },
+
+  // Initial User Info
+  user: {
+    guestMode: true,             // Start as guest?
+    user_id: "user_123",         // Optional: Known user ID
+    country: "US",               // Optional
+  },
+};
+
+// 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.
+
+```javascript
+function App() {
+  return (
+    <MetaStreamProvider tracker={tracker}>
+       {/* Your App Components */}
+       <YourNavigationRoot />
+    </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.
+
+```javascript
+tracker.start_session({
+    user_id: "user_123",  // Optional: Update user ID
+    // ...other user traits
+});
+```
+
+### 2. Tracking Events
+
+You can track any custom event. The payload requires an `eventName` and optional `eventParameters`.
+
+**Event Payload Format:**
+```javascript
+tracker.trackEvent({
+  eventName: "add_to_cart",
+  eventParameters: [
+    { key: "product_id", value: "prod_999" },
+    { key: "price", value: 29.99 },
+    { key: "category", value: "shoes" }
+  ]
+});
+```
+*Note: `eventParameters` creates a flexible dictionary of data associated with the event.*
+
+### 3. Screen Tracking
+
+Though `MetaStreamProvider` captures the video, you can manually log screen views for analytics:
+
+```javascript
+tracker.screen("HomeScreen", {});
+```
+
+### 4. Shopping Cart
+
+Manage a persistent shopping cart state:
+
+```javascript
+// Add Item
+tracker.cart.add({
+  id: "prod_001",
+  name: "Cool Sneakers",
+  price: 99.99,
+  quantity: 1
+});
+
+// Remove Item
+tracker.cart.remove("prod_001");
+
+// Clear Cart
+tracker.cart.clear();
+```
+
+## Troubleshooting
+
+### "DeviceInfo could not be found"
+If you see this error, it means the native module `react-native-device-info` is not linked.
+1. Ensure you installed the peer dependency: `npm install react-native-device-info`
+2. Rebuild your native app: `cd android && ./gradlew clean && cd .. && npx react-native run-android`
+
+### "Cannot read property 'MetaStreamProvider' of undefined"
+Ensure you are importing correctly.
+Correct: `import { MetaStreamProvider } from 'iidrak-analytics-react';`
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1 @@
+declare module 'MetaStreamIO';

package/index.js

@@ -0,0 +1,4 @@
+import MetaStreamIO from "./metastreamio/metastreamio.interface.js";
+import { MetaStreamProvider } from "./metastreamio/metastreamio.provider.js";
+
+export { MetaStreamIO, MetaStreamProvider };

package/metastreamio/metastreamio.account.js

@@ -0,0 +1,65 @@
+"use strict";
+
+import { strf } from "./string.format.js";
+
+strf();
+
+import { AccountModel } from "./models/event.account.js";
+import { AccountBalanceModel } from "./models/event.account.balance.js";
+
+/*
+ *
+ * Log account data
+ *
+ */
+
+class MetaStreamIOAccountData {
+  constructor({ constants, logger, storage, utility } = {}) {
+    this.constant = constants;
+    this.logger = logger;
+    this.account = new AccountModel();
+    this.utility = utility;
+  }
+
+  reset() {
+    this.account = new AccountModel();
+  }
+
+  setType(account = null) {
+    if (account) {
+      this.account.type = account;
+      this.logger.log(
+        "account",
+        this.constant.MetaStreamIO_AccountTypeSet.format(this.account.type)
+      );
+    } else {
+      this.logger.log(
+        "account",
+        "setAccountType() could not set account type: " + err
+      );
+    }
+  }
+
+  setBalance({ account = null, balance = null } = {}) {
+    this.account.balances[account] = new AccountBalanceModel({
+      account: account,
+      balance: balance,
+    });
+    return this.account.balances[account];
+  }
+
+  setBalances(balances) {
+    try {
+      balances.forEach((balance) => {
+        this.setBalance({
+          account: balance.account,
+          balance: balance.balances,
+        });
+      });
+    } catch (err) {
+      this.logger.error("account", err);
+    }
+  }
+}
+
+export { MetaStreamIOAccountData };

package/metastreamio/metastreamio.cart.js

@@ -0,0 +1,192 @@
+"use strict";
+
+import { strf } from "./string.format.js";
+
+strf();
+
+import { CartModel } from "./models/event.cart";
+import { CartItemModel } from "./models/event.cartitem";
+
+/*
+ *
+ * Cart class for managing shopping cart
+ *
+ */
+
+class MetaStreamIOCart {
+  constructor({ constants, date, encryption, logger, storage, utility } = {}) {
+    // Extend functionality with other MetaStream classes
+    this.constant = constants;
+    this.date = date;
+    this.encryption = encryption;
+    this.logger = logger;
+    this.utility = utility;
+
+    // Initialise variables
+    this.reset();
+  }
+
+  reset() {
+    this.cart = new CartModel();
+    this.last_cart = {};
+  }
+
+  setCartId(id = null) {
+    if (!id) {
+      this.cart.id = this.utility.generateRandomId();
+    } else {
+      this.cart.id = id;
+    }
+    this.logger.log(
+      "cart",
+      this.constant.MetaStreamIO_Cart_CartIdSet.format(this.cart.id)
+    );
+  }
+
+  // Add items to the cart - expects an array so this can be multiple items at once
+
+  add(items = []) {
+    try {
+      for (let item in items) {
+        let _new_item = new CartItemModel({
+          price: items[item].price ? items[item].price : null,
+          id: items[item].id ? items[item].id : null,
+          name: items[item].name ? items[item].name : null,
+          type: items[item].type ? items[item].type : null,
+          validity: items[item].validity ? items[item].validity : null,
+          value: items[item].value ? items[item].value : null,
+          quantity: ((cart, item) => {
+            let _id = item.id;
+            try {
+              return cart[_id].quantity + item.quantity;
+            } catch (err) {
+              return item.quantity;
+            }
+          })(this.cart.items, items[item]),
+          recipients: items[item].recipients ? items[item].recipients : [],
+        }).json();
+        let _bid = items[item].id ? items[item].id : null;
+        this.cart.items = { ...this.cart.items, [_bid]: _new_item };
+        this.logger.log(
+          "cart",
+          this.constant.MetaStreamIO_Cart_AddedToCart.format(items[item].id)
+        );
+      }
+    } catch (err) {
+      this.logger.error(
+        "cart",
+        "addCartItem() error adding item to cart:",
+        err
+      );
+    }
+    this.logger.log(
+      "cart",
+      this.constant.MetaStreamIO_Cart_Cart.format(JSON.stringify(this.cart))
+    );
+    return this;
+  }
+
+  // Reduce the quantity of a specific item in the cart
+
+  reduce(id = null, quantity = null) {
+    let _quantity = quantity ? quantity : 1;
+    if (this.cart.items[id]) {
+      if (this.cart.items[id]["quantity"] > 0) {
+        this.cart.items[id]["quantity"] =
+          this.cart.items[id]["quantity"] - _quantity;
+        this.logger.log(
+          "cart",
+          this.constant.MetaStreamIO_Cart_QuantityReduced.format(
+            id,
+            this.cart.items[id]["quantity"]
+          )
+        );
+        this.logger.log(
+          "cart",
+          this.constant.MetaStreamIO_Cart_Cart.format(
+            JSON.stringify(this.cart.items)
+          )
+        );
+      } else {
+        this.logger.log(
+          "cart",
+          this.constant.MetaStreamIO_Cart_QuantityZero.format(id)
+        );
+        this.logger.log(
+          "cart",
+          this.constant.MetaStreamIO_Cart_Cart.format(
+            JSON.stringify(this.cart.items)
+          )
+        );
+      }
+    } else {
+      this.logger.log(
+        "cart",
+        this.constant.MetaStreamIO_Cart_BundleNotInCart.format(id)
+      );
+      this.logger.log(
+        "cart",
+        this.constant.MetaStreamIO_Cart_Cart.format(
+          JSON.stringify(this.cart.items)
+        )
+      );
+    }
+    return this;
+  }
+
+  delete(id = null) {
+    if (this.cart.items[id]) {
+      delete this.cart.items[id];
+    } else {
+      this.logger.log(
+        "cart",
+        this.constant.MetaStreamIO_Cart_BundleNotInCart.format(id)
+      );
+      this.logger.log(
+        "cart",
+        this.constant.MetaStreamIO_Cart_Cart.format(
+          JSON.stringify(this.cart.items)
+        )
+      );
+    }
+    return this;
+  }
+
+  // Remove all items from the cart and generate a new cart id
+
+  clear(cart_id = null) {
+    try {
+      this.cart = new CartModel({
+        id: cart_id !== null ? cart_id : this.utility.generateRandomId(),
+      });
+      this.logger.log("cart", this.constant.MetaStreamIO_Cart_RemoveAllItems);
+      this.logger.log(
+        "cart",
+        this.constant.MetaStreamIO_Cart_Cart.format(JSON.stringify(this.cart))
+      );
+    } catch (err) {
+      return this;
+    }
+
+    return this;
+  }
+
+  get lastCart() {
+    return this.last_cart;
+  }
+
+  set lastCart(input) {
+    this.last_cart = input;
+  }
+
+  // Convert cart object to a list of objects with the bundle id as the key for each
+  list(input = {}) {
+    let _return = [];
+    for (let id in input) {
+      _return.push(input[id]);
+    }
+    return _return;
+  }
+}
+
+export { MetaStreamIOCart };

package/metastreamio/metastreamio.constants.js

@@ -0,0 +1,256 @@
+"use strict";
+
+import { strf } from "./string.format.js";
+
+strf();
+
+/*
+ *
+ * Constants
+ *
+ */
+
+class MetaStreamIOConstants {
+  // MetaStreamIO constants
+  get MetaStreamIO_ValueNotSet() {
+    return "unassigned";
+  }
+  get MetaStreamIO_Unidentified() {
+    return "unidentified";
+  }
+  get MetaStreamIO_SessionLengthSeconds() {
+    return 1800;
+  }
+  get MetaStreamIO_SendOnceDefault() {
+    return false;
+  }
+
+  get MetaStreamIO_Endpoint_User() {
+    return "/user";
+  }
+
+  // Account
+  get MetaStreamIO_AccountTypeSet() {
+    return "account type set to  {0}";
+  }
+  get MetaStreamIO_AccountBalanceSet() {
+    return "account balance for {0} set to {1}";
+  }
+
+  get MetaStreamIO_AccountTypeNotSet() {
+    return "not set";
+  }
+
+  // AsyncStorage names
+  get MetaStreamIO_Async_ReadSuccess() {
+    return "AsyncStorage retrieval for {0} returned: {1}";
+  }
+  get MetaStreamIO_Async_ReadFail() {
+    return "AsyncStorage retrieval for {0} failed";
+  }
+  get MetaStreamIO_Async_WriteSuccess() {
+    return "AsyncStorage set {0} to {1}";
+  }
+  get MetaStreamIO_Async_WriteFail() {
+    return "AsyncStorage attempt to set {0} failed.";
+  }
+  get MetaStreamIO_Async_Cart() {
+    return "tracker_cart";
+  }
+  get MetaStreamIO_Async_CartId() {
+    return "tracker_cart_id";
+  }
+  get MetaStreamIO_Async_EventParameters() {
+    return "event_parameters";
+  }
+  get MetaStreamIO_Async_UserProperties() {
+    return "user_properties";
+  }
+  get MetaStreamIO_Async_UserId() {
+    return "user_id";
+  }
+
+  // Cart
+  get MetaStreamIO_Cart_AddedToCart() {
+    return "{0} added to cart";
+  }
+  get MetaStreamIO_Cart_Cart() {
+    return "cart: {0}";
+  }
+  get MetaStreamIO_Cart_CartIdSet() {
+    return "cart id set to {0}";
+  }
+  get MetaStreamIO_Cart_QuantityReduced() {
+    return "{0} quantity reduced to {1}";
+  }
+  get MetaStreamIO_Cart_QuantityZero() {
+    return "{0} quantity already zero";
+  }
+  get MetaStreamIO_Cart_BundleNotInCart() {
+    return "{0} not found in cart, not removed";
+  }
+  get MetaStreamIO_Cart_RemoveAllItems() {
+    return "all items removed from cart and new cart id assigned";
+  }
+
+  // Encryption suite
+  get MetaStreamIO_Encryption_SHA256Generated() {
+    return "sha256 hash generated: {0}";
+  }
+  get MetaStreamIO_Encryption_UUIDv4Generated() {
+    return "new uuid generated: {0}";
+  }
+
+  // Environment
+  get MetaStreamIO_Environment_AppInfo() {
+    return "app info: {0}";
+  }
+  get MetaStreamIO_Environment_AppPerformance() {
+    return "app performance: {0}";
+  }
+  get MetaStreamIO_Environment_Device() {
+    return "device: {0}";
+  }
+  get MetaStreamIO_Environment_Network() {
+    return "network: {0}";
+  }
+
+  // Events and user properties logs
+  get MetaStreamIO_Log_EventTracked() {
+    return "event tracked: {0}";
+  }
+  get MetaStreamIO_Log_EventTrackFailed() {
+    return "event track failed: {0}";
+  }
+  get MetaStreamIO_Log_EventParameters() {
+    return "event parameters: ";
+  }
+  get MetaStreamIO_Log_EventParameterSet() {
+    return "event parameter {0} set to {1}  with type {2}";
+  }
+  get MetaStreamIO_Log_SendOnce() {
+    return "send once enabled: event parameters cleared";
+  }
+  get MetaStreamIO_Log_RequestObject() {
+    return "request object >>";
+  }
+  get MetaStreamIO_Log_UserIdSet() {
+    return "user id set: {0}";
+  }
+  get MetaStreamIO_Log_CIAMIdSet() {
+    return "ciam id set: {0}";
+  }
+  get MetaStreamIO_Log_EmailIdSet() {
+    return "email id set: {0}";
+  }
+  get MetaStreamIO_Log_UserCountrySet() {
+    return "user country set: {0}";
+  }
+  get MetaStreamIO_Log_UserPropertySet() {
+    return "user property {0} set to {1}  with type {2}";
+  }
+  get MetaStreamIO_Log_PushDeviceTokenSet() {
+    return "device token set: {0}";
+  }
+
+  // Event names
+  get MetaStreamIO_EventName_Purchase() {
+    return "purchase";
+  }
+  get MetaStreamIO_EventName_SendAirtime() {
+    return "send_airtime";
+  }
+  get MetaStreamIO_EventName_QuickBuy() {
+    return "quick_buy";
+  }
+
+  // Logger
+  get MetaStreamIO_Logger_Prefix() {
+    return "[MetaStreamIO]";
+  }
+  get MetaStreamIO_Logger_MessageFormat() {
+    return "{0} {1} {2}";
+  }
+  get MetaStreamIO_Logger_Category_Success() {
+    return "success";
+  }
+  get MetaStreamIO_Logger_Category_Environment() {
+    return "environment";
+  }
+
+  // MetaStreamIO
+  get MetaStreamIO_IO_ProjectEnvironmentSet() {
+    return "project environment set to {0}";
+  }
+  get MetaStreamIO_IO_ProjectEnvironmentNotSet() {
+    return "project environment not set";
+  }
+  get MetaStreamIO_IO_ProjectIdSet() {
+    return "project id set to {0}";
+  }
+  get MetaStreamIO_IO_ProjectIdNotSet() {
+    return "no project id specified";
+  }
+
+  // Network
+  get MetaStreamIO_Network_GetDataIssue() {
+    return "getData issue: {0} [endpoint: {1}]";
+  }
+  get MetaStreamIO_Network_GetDataReturn() {
+    return "getData returned: {0}";
+  }
+  get MetaStreamIO_Network_PostDataIssue() {
+    return "postData issue: {0} [endpoint: {1}]";
+  }
+  get MetaStreamIO_Network_PostDataReturn() {
+    return "postData returned: {0}";
+  }
+  get MetaStreamIO_Network_SilentMode() {
+    return "silent mode enabled; no data sent";
+  }
+  get MetaStreamIO_Network_SilentModeEnabled() {
+    return "silent mode enabled";
+  }
+  get MetaStreamIO_Network_EndpointSet() {
+    return "endpoint set: {0}";
+  }
+  get MetaStreamIO_Network_EndpointTestFailed() {
+    return "endpoint test failed: {0}";
+  }
+
+  // Session
+  get MetaStreamIO_User_Guest() {
+    return "unidentified:guest";
+  }
+  get MetaStreamIO_Session_SourceNotSet() {
+    return "not set";
+  }
+  get MetaStreamIO_Session_SessionIdSet() {
+    return "session id generated: {0}";
+  }
+  get MetaStreamIO_Session_SessionStillValid() {
+    return "session still valid - check passed";
+  }
+  get MetaStreamIO_User_HashModeDefault() {
+    return true;
+  }
+  get MetaStreamIO_User_DoubleHashModeDefault() {
+    return false;
+  }
+  get MetaStreamIO_User_Base64Default() {
+    return false;
+  }
+  get MetaStreamIO_User_SecureEncryptionDefault() {
+    return false;
+  }
+
+  // Utility
+  get MetaStreamIO_Utility_ComparedArraysAreDifferent() {
+    return "evaluated arrays are different";
+  }
+  get MetaStreamIO_Utility_ComparedArraysAreIdentical() {
+    return "evaluated arrays are identical";
+  }
+}
+
+export { MetaStreamIOConstants };