@bytem/bytem-tracker-app 0.0.7 → 0.0.9

package/README.md

@@ -2,16 +2,12 @@
 
 This is the official Bytem Tracker SDK for React Native applications.
 
-## Documentation
-
-- [Usage Guide](docs/USAGE.md): Detailed instructions on initialization, event tracking, and API usage.
-
 ## Installation
 
 Install the package and its peer dependencies using Yarn:
 
 ```bash
-yarn add @bytem/bytem-tracker-app @react-native-async-storage/async-storage react-native-device-info uuid
+yarn add @bytem/bytem-tracker-app
 ```
 
 ### iOS Setup
@@ -20,47 +16,95 @@ Don't forget to install pods for iOS:
 cd ios && pod install
 ```
 
-## Development
+## Usage
 
-This project uses **Yarn** for dependency management.
+### Initialization
+Initialize the tracker in your app entry point (e.g., `App.tsx` or `index.js`). Note that `init` is asynchronous.
 
-### Setup
+```typescript
+import React, { useEffect } from 'react';
+import BytemTracker from '@bytem/bytem-tracker-app';
 
-```bash
-yarn install
-```
+const App = () => {
+  useEffect(() => {
+    const initTracker = async () => {
+      await BytemTracker.init({
+        appId: 'your-app-id',
+        endpoint: 'https://api.bytem.com/track',
+        debug: __DEV__, // Enable debug logs in development
+      });
+    };
 
-### Running Tests
+    initTracker();
+  }, []);
 
-```bash
-yarn test
+  return <YourApp />;
+};
 ```
 
-### Build
+### Tracking Events
 
-```bash
-yarn build
-```
+#### Identify User
+Track user identification when a user logs in or updates their profile.
 
-## Release & Publish
+```typescript
+// Signature: trackUser(userId: string, traits?: object)
+await BytemTracker.trackUser('user_12345', {
+  email: 'user@example.com',
+  age: 25,
+  membership: 'gold'
+});
+```
 
-Automate version bump and publish via npm scripts:
+#### View Product
+Track when a user views a product details page.
+
+```typescript
+await BytemTracker.trackViewProduct({
+  productId: 'prod_001',
+  name: 'Awesome Gadget',
+  price: 99.99,
+  currency: 'USD',
+  category: 'Electronics'
+});
+```
 
-```bash
-# Patch release (1.0.0 -> 1.0.1)
-npm run release:patch
+#### Checkout Order
+Track when a user initiates checkout.
+
+```typescript
+await BytemTracker.trackCheckOutOrder({
+  orderId: 'order_abc123',
+  total: 150.00,
+  currency: 'USD',
+  products: [
+    { productId: 'prod_001', price: 99.99, quantity: 1 },
+    { productId: 'prod_002', price: 50.01, quantity: 1 }
+  ]
+});
+```
 
-# Minor release (1.0.0 -> 1.1.0)
-npm run release:minor
+#### Pay Order
+Track when a user completes a payment.
+
+```typescript
+await BytemTracker.trackPayOrder({
+  orderId: 'order_abc123',
+  total: 150.00,
+  currency: 'USD',
+  products: [
+    { productId: 'prod_001', price: 99.99, quantity: 1 },
+    { productId: 'prod_002', price: 50.01, quantity: 1 }
+  ]
+});
+```
 
-# Major release (1.0.0 -> 2.0.0)
-npm run release:major
+## Platform Compatibility
 
-# Beta prerelease (1.0.0 -> 1.0.1-beta.0)
-npm run release:beta
-```
+This SDK is designed for **React Native** and supports:
+- iOS
+- Android
 
-Notes:
-- These scripts bump package.json version and publish to npm.
-- `prepublishOnly` builds the package before publishing.
-- Configure auth via user-level `~/.npmrc`. Do not commit tokens in the repo.
+It relies on:
+- `@react-native-async-storage/async-storage`: For persisting session and visitor IDs.
+- `react-native-device-info`: For capturing device metrics (model, OS version, etc.).

package/dist/src/BytemTracker.d.ts

@@ -23,16 +23,72 @@ declare class BytemTracker {
     private lastViewStoredDuration;
     private constructor();
     static getInstance(): BytemTracker;
+    /**
+     * Initializes the BytemTracker SDK with the provided configuration.
+     * This method must be called before any other tracking methods.
+     *
+     * @param config - The configuration object for the tracker.
+     * @returns A promise that resolves when initialization is complete.
+     */
     init(config: TrackerConfig): Promise<void>;
     private ensureInitialized;
+    /**
+     * Begins a new user session.
+     * Handles session cookie logic to prevent excessive session starts if one is already active.
+     *
+     * @param force - If true, forces a new session start request even if the session cookie is valid.
+     */
     beginSession(force?: boolean): Promise<void>;
+    /**
+     * Reports session duration to the server.
+     * Usually called internally or when app state changes.
+     *
+     * @param sec - The duration in seconds to report.
+     */
     sessionDuration(sec: number): Promise<void>;
+    /**
+     * Ends the current user session.
+     *
+     * @param sec - Optional duration of the session in seconds. If not provided, it's calculated from the last beat.
+     * @param force - If true, forces the end session request even if using session cookies.
+     */
     endSession(sec?: number, force?: boolean): Promise<void>;
+    /**
+     * Manually tracks or extends a session.
+     * If a session is active, it reports duration. If not, it begins a new session.
+     */
     trackSessions(): Promise<void>;
+    /**
+     * Resumes time tracking for session duration.
+     */
     startTime(): void;
+    /**
+     * Pauses time tracking for session duration.
+     */
     stopTime(): void;
+    /**
+     * Tracks a custom event.
+     *
+     * @param eventKey - The unique key/name for the event.
+     * @param segmentation - Optional key-value pairs to attach to the event.
+     * @param count - The number of times this event occurred (default: 1).
+     * @param sum - Optional numeric value associated with the event (e.g., purchase amount).
+     * @param duration - Optional duration associated with the event.
+     */
     trackEvent(eventKey: string, segmentation?: Record<string, any>, count?: number, sum?: number, duration?: number): Promise<void>;
+    /**
+     * Tracks a page view.
+     * Automatically handles reporting the duration of the previous page view.
+     *
+     * @param current - The name or path of the current page.
+     * @param referrer - Optional name or path of the previous page.
+     */
     trackPageview(current: string, referrer?: string): Promise<void>;
+    /**
+     * Tracks a click on a product/goods item.
+     *
+     * @param params - The parameters for the goods click event.
+     */
     trackGoodsClick(params: {
         gid?: string;
         skuid?: string;
@@ -48,9 +104,34 @@ declare class BytemTracker {
     private buildBaseRequestParams;
     private extendSession;
     private sendRequest;
+    /**
+     * Tracks a product view event.
+     * Maps the product details to a 'view_product' event.
+     *
+     * @param product - The product object to track.
+     */
     trackViewProduct(product: Product): Promise<void>;
+    /**
+     * Tracks a checkout order event.
+     * Automatically splits product lists into parallel arrays (gids, prices, quantities)
+     * to match the backend requirement.
+     *
+     * @param order - The order object containing products to checkout.
+     */
     trackCheckOutOrder(order: Order): Promise<void>;
+    /**
+     * Tracks a payment order event.
+     * Maps product list to a 'goods' array structure expected by the backend.
+     *
+     * @param order - The order object that was paid for.
+     */
     trackPayOrder(order: Order): Promise<void>;
+    /**
+     * Tracks user details/profile updates.
+     *
+     * @param userId - The unique identifier for the user.
+     * @param traits - Additional user properties (email, name, custom fields).
+     */
     trackUser(userId: string, traits?: UserTraits): Promise<void>;
     private sendUserDetails;
 }

package/dist/src/BytemTracker.js

@@ -35,6 +35,13 @@ class BytemTracker {
         }
         return BytemTracker.instance;
     }
+    /**
+     * Initializes the BytemTracker SDK with the provided configuration.
+     * This method must be called before any other tracking methods.
+     *
+     * @param config - The configuration object for the tracker.
+     * @returns A promise that resolves when initialization is complete.
+     */
     async init(config) {
         if (this.isInitialized) {
             console.warn('[BytemTracker] Already initialized');
@@ -49,7 +56,10 @@ class BytemTracker {
         if (config.path) {
             this.apiPath = config.path.startsWith('/') ? config.path : '/' + config.path;
         }
-        // Initialize Visitor ID
+        // Initialize Visitor ID logic:
+        // 1. If provided in config, use it.
+        // 2. If not, try to retrieve from storage.
+        // 3. If not in storage, generate a new UUID.
         if (config.visitorId) {
             this.visitorId = config.visitorId;
             await (0, storage_1.setItem)(storage_1.StorageKeys.VISITOR_ID, this.visitorId);
@@ -69,7 +79,9 @@ class BytemTracker {
                     console.log(`[BytemTracker] Restored visitor ID: ${this.visitorId}`);
             }
         }
-        // Initialize Device ID type
+        // Initialize Device ID type logic:
+        // 0: Developer supplied
+        // 1: SDK generated (default)
         if (config.deviceId) {
             this.deviceIdType = 0; // Developer set
             await (0, storage_1.setItem)(storage_1.StorageKeys.DEVICE_ID, config.deviceId);
@@ -88,7 +100,7 @@ class BytemTracker {
             if (this.appScheme)
                 console.log(`  app_scheme: ${this.appScheme}`);
         }
-        // Begin session
+        // Attempt to begin a session automatically on init
         try {
             await this.beginSession();
         }
@@ -104,6 +116,12 @@ class BytemTracker {
             throw new Error('[BytemTracker] Not initialized. Call await init() first.');
         }
     }
+    /**
+     * Begins a new user session.
+     * Handles session cookie logic to prevent excessive session starts if one is already active.
+     *
+     * @param force - If true, forces a new session start request even if the session cookie is valid.
+     */
     async beginSession(force = false) {
         this.ensureInitialized();
         if (this.sessionStarted) {
@@ -114,7 +132,7 @@ class BytemTracker {
         try {
             this.sessionStarted = true;
             this.lastBeat = Date.now();
-            // Check session cookie
+            // Check session cookie to avoid duplicate session starts
             const sessionKey = `${this.appKey}/cly_session`;
             const expireTimestampStr = await (0, storage_1.getItem)(sessionKey);
             const expireTimestamp = expireTimestampStr ? parseInt(expireTimestampStr, 10) : null;
@@ -126,7 +144,7 @@ class BytemTracker {
             if (!shouldSendRequest) {
                 if (this.debug)
                     console.log('[BytemTracker] Session cookie still valid, skipping begin_session request');
-                // Update cookie
+                // Extend the cookie validity
                 await (0, storage_1.setItem)(sessionKey, (currentTimestamp + this.sessionCookieTimeout * 60 * 1000).toString());
                 return;
             }
@@ -144,6 +162,12 @@ class BytemTracker {
                 console.error('[BytemTracker] Error in beginSession:', e);
         }
     }
+    /**
+     * Reports session duration to the server.
+     * Usually called internally or when app state changes.
+     *
+     * @param sec - The duration in seconds to report.
+     */
     async sessionDuration(sec) {
         this.ensureInitialized();
         if (!this.sessionStarted) {
@@ -158,6 +182,12 @@ class BytemTracker {
         this.lastBeat = Date.now();
         await this.extendSession();
     }
+    /**
+     * Ends the current user session.
+     *
+     * @param sec - Optional duration of the session in seconds. If not provided, it's calculated from the last beat.
+     * @param force - If true, forces the end session request even if using session cookies.
+     */
     async endSession(sec, force = false) {
         this.ensureInitialized();
         if (!this.sessionStarted) {
@@ -181,6 +211,10 @@ class BytemTracker {
         await this.sendRequest(this.apiPath, body, 'End Session');
         this.sessionStarted = false;
     }
+    /**
+     * Manually tracks or extends a session.
+     * If a session is active, it reports duration. If not, it begins a new session.
+     */
     async trackSessions() {
         this.ensureInitialized();
         if (this.debug)
@@ -200,6 +234,9 @@ class BytemTracker {
         if (this.debug)
             console.log('[BytemTracker] Session tracking started');
     }
+    /**
+     * Resumes time tracking for session duration.
+     */
     startTime() {
         if (!this.trackTime) {
             this.trackTime = true;
@@ -223,6 +260,9 @@ class BytemTracker {
             this.extendSession();
         }
     }
+    /**
+     * Pauses time tracking for session duration.
+     */
     stopTime() {
         if (this.trackTime) {
             this.trackTime = false;
@@ -237,6 +277,15 @@ class BytemTracker {
                 console.log('[BytemTracker] Time tracking stopped');
         }
     }
+    /**
+     * Tracks a custom event.
+     *
+     * @param eventKey - The unique key/name for the event.
+     * @param segmentation - Optional key-value pairs to attach to the event.
+     * @param count - The number of times this event occurred (default: 1).
+     * @param sum - Optional numeric value associated with the event (e.g., purchase amount).
+     * @param duration - Optional duration associated with the event.
+     */
     async trackEvent(eventKey, segmentation, count = 1, sum, duration) {
         this.ensureInitialized();
         const deviceId = await this.getRealDeviceId();
@@ -257,6 +306,13 @@ class BytemTracker {
         body['events'] = JSON.stringify([event]);
         await this.sendRequest(this.apiPath, body, 'Event');
     }
+    /**
+     * Tracks a page view.
+     * Automatically handles reporting the duration of the previous page view.
+     *
+     * @param current - The name or path of the current page.
+     * @param referrer - Optional name or path of the previous page.
+     */
     async trackPageview(current, referrer) {
         await this.reportViewDuration();
         const segmentation = {
@@ -279,6 +335,11 @@ class BytemTracker {
         }
         await this.trackEvent(types_1.BytemEventKeys.view, segmentation, 1, undefined, duration);
     }
+    /**
+     * Tracks a click on a product/goods item.
+     *
+     * @param params - The parameters for the goods click event.
+     */
     async trackGoodsClick(params) {
         this.ensureInitialized();
         const segmentation = {
@@ -423,6 +484,12 @@ class BytemTracker {
         }
     }
     // Wrappers for Business methods to maintain compatibility or you can refactor them too
+    /**
+     * Tracks a product view event.
+     * Maps the product details to a 'view_product' event.
+     *
+     * @param product - The product object to track.
+     */
     async trackViewProduct(product) {
         // Map Product to segmentation
         const segmentation = {
@@ -435,25 +502,58 @@ class BytemTracker {
         // In Dart, trackViewProduct sends "view_product" event.
         await this.trackEvent('view_product', segmentation);
     }
+    /**
+     * Tracks a checkout order event.
+     * Automatically splits product lists into parallel arrays (gids, prices, quantities)
+     * to match the backend requirement.
+     *
+     * @param order - The order object containing products to checkout.
+     */
     async trackCheckOutOrder(order) {
         // Map Order to segmentation
         const segmentation = {
             order_id: order.orderId,
             total: order.total,
             currency: order.currency,
-            // products need to be handled. Dart sends lists of gids, etc.
-            // This is a simplification. Ideally we replicate trackCheckOutOrder logic fully.
         };
+        if (order.products && order.products.length > 0) {
+            segmentation.gids = order.products.map(p => p.productId);
+            segmentation.prices = order.products.map(p => p.price);
+            segmentation.quantity = order.products.map(p => p.quantity || 1);
+            // Optional: skuids if available in Product type, currently not in interface but good to handle if extended
+            // segmentation.skuids = ... 
+        }
         await this.trackEvent('check_out_order', segmentation);
     }
+    /**
+     * Tracks a payment order event.
+     * Maps product list to a 'goods' array structure expected by the backend.
+     *
+     * @param order - The order object that was paid for.
+     */
     async trackPayOrder(order) {
         const segmentation = {
             order_id: order.orderId,
             total: order.total,
             currency: order.currency,
         };
+        if (order.products && order.products.length > 0) {
+            // Dart maps this to a list of maps called "goods"
+            segmentation.goods = order.products.map(p => ({
+                gid: p.productId,
+                name: p.name,
+                price: p.price,
+                quantity: p.quantity || 1,
+            }));
+        }
         await this.trackEvent('pay_order', segmentation);
     }
+    /**
+     * Tracks user details/profile updates.
+     *
+     * @param userId - The unique identifier for the user.
+     * @param traits - Additional user properties (email, name, custom fields).
+     */
     async trackUser(userId, traits) {
         // Map to user_details
         // This is a special request in Dart: "user_details" param

package/dist/src/types.d.ts

@@ -1,12 +1,25 @@
+/**
+ * Configuration for initializing the BytemTracker.
+ */
 export interface TrackerConfig {
+    /** The unique application ID provided by Bytem. */
     appId: string;
+    /** Custom endpoint URL for tracking requests. */
     endpoint?: string;
+    /** Custom path for the API endpoint (default: '/i'). */
     path?: string;
+    /** Enable debug logging for development. */
     debug?: boolean;
+    /** Optional: Manually set a visitor ID. */
     visitorId?: string;
+    /** Optional: Manually set a device ID. */
     deviceId?: string;
+    /** Optional: App scheme for domain field in tracking. */
     appScheme?: string;
 }
+/**
+ * Predefined event keys used internally by the SDK.
+ */
 export declare const BytemEventKeys: {
     nps: string;
     survey: string;
@@ -16,6 +29,9 @@ export declare const BytemEventKeys: {
     pushAction: string;
     action: string;
 };
+/**
+ * Structure containing device information collected by the SDK.
+ */
 export interface DeviceInfo {
     platform: string;
     os: string;
@@ -44,9 +60,15 @@ export interface BaseParams {
     screen_height: number;
     user_agent: string;
 }
+/**
+ * Arbitrary key-value pairs for user properties.
+ */
 export interface UserTraits {
     [key: string]: any;
 }
+/**
+ * Represents a product in the system.
+ */
 export interface Product {
     productId: string;
     name?: string;
@@ -55,6 +77,9 @@ export interface Product {
     category?: string;
     quantity?: number;
 }
+/**
+ * Represents an order (checkout or payment).
+ */
 export interface Order {
     orderId: string;
     total: number;

package/dist/src/types.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BytemEventKeys = void 0;
+/**
+ * Predefined event keys used internally by the SDK.
+ */
 exports.BytemEventKeys = {
     nps: "[CLY]_nps",
     survey: "[CLY]_survey",

package/dist/test/BytemTracker.test.js

@@ -223,7 +223,10 @@ describe('BytemTracker SDK', () => {
             expect(events[0].segmentation).toMatchObject({
                 order_id: 'order_123',
                 total: 99.99,
-                currency: 'USD'
+                currency: 'USD',
+                gids: ['prod_1', 'prod_2'],
+                prices: [50, 49.99],
+                quantity: [1, 1]
             });
         });
         it('should track pay order', async () => {
@@ -231,7 +234,10 @@ describe('BytemTracker SDK', () => {
                 orderId: 'order_123',
                 total: 99.99,
                 currency: 'USD',
-                products: []
+                products: [
+                    { productId: 'prod_1', name: 'Product 1', price: 50, quantity: 1 },
+                    { productId: 'prod_2', name: 'Product 2', price: 49.99, quantity: 2 }
+                ]
             };
             await BytemTracker_1.default.trackPayOrder(order);
             const calls = global.fetch.mock.calls;
@@ -241,7 +247,11 @@ describe('BytemTracker SDK', () => {
             expect(events[0].segmentation).toMatchObject({
                 order_id: 'order_123',
                 total: 99.99,
-                currency: 'USD'
+                currency: 'USD',
+                goods: [
+                    { gid: 'prod_1', name: 'Product 1', price: 50, quantity: 1 },
+                    { gid: 'prod_2', name: 'Product 2', price: 49.99, quantity: 2 }
+                ]
             });
         });
     });

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@bytem/bytem-tracker-app",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Bytem Tracker SDK for React Native",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
   "files": [
     "dist"
   ],
@@ -25,13 +25,13 @@
   "author": "Barry",
   "license": "ISC",
   "peerDependencies": {
-    "@react-native-async-storage/async-storage": "^1.0.0",
     "react": ">=16.8.0",
-    "react-native": ">=0.60.0",
-    "react-native-device-info": "^10.0.0"
+    "react-native": ">=0.60.0"
   },
   "dependencies": {
-    "uuid": "^9.0.0"
+    "uuid": "^9.0.0",
+    "@react-native-async-storage/async-storage": "^1.19.0",
+    "react-native-device-info": "^10.8.0"
   },
   "devDependencies": {
     "@react-native-async-storage/async-storage": "^1.19.0",