@bytem/bytem-tracker-app 0.0.3 → 0.0.7

package/README.md

@@ -1,41 +1,66 @@
-# @bytem/bytem-tracker
+# Bytem Tracker SDK (React Native)
 
-ByteM 埋点 SDK（React Native / Expo）
+This is the official Bytem Tracker SDK for React Native applications.
 
-> 本 SDK 为 Flutter `bytem_tracker.dart` 的 **1:1 行为迁移版本**  
-> 字段、默认值、payload 结构完全一致，后端无需任何改动
+## 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
-rm -rf dist
-yarn install
-yarn build
+yarn add @bytem/bytem-tracker-app @react-native-async-storage/async-storage react-native-device-info uuid
 ```
 
----
+### iOS Setup
+Don't forget to install pods for iOS:
+```bash
+cd ios && pod install
+```
+
+## Development
+
+This project uses **Yarn** for dependency management.
 
-## ✨ 特性
+### Setup
 
-- ✅ React Native / Expo 通用
-- ✅ 行为 100% 对齐 Flutter SDK
-- ✅ 单例模式
-- ✅ 自动 deviceId / visitorId 管理
-- ✅ TypeScript 支持
-- ❌ 不支持 Web（刻意限制，避免误用）
+```bash
+yarn install
+```
 
----
+### Running Tests
 
-## 📦 安装
+```bash
+yarn test
+```
 
-### React Native CLI
+### Build
 
 ```bash
-yarn add @bytem/bytem-tracker
-yarn add @react-native-async-storage/async-storage
+yarn build
 ```
 
-### Expo
+## Release & Publish
+
+Automate version bump and publish via npm scripts:
+
 ```bash
-expo install @react-native-async-storage/async-storage
-yarn add @bytem/bytem-tracker
-```
+# Patch release (1.0.0 -> 1.0.1)
+npm run release:patch
+
+# Minor release (1.0.0 -> 1.1.0)
+npm run release:minor
+
+# Major release (1.0.0 -> 2.0.0)
+npm run release:major
+
+# Beta prerelease (1.0.0 -> 1.0.1-beta.0)
+npm run release:beta
+```
+
+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.

package/dist/src/BytemTracker.d.ts

@@ -0,0 +1,58 @@
+import { TrackerConfig, Product, Order, UserTraits } from './types';
+declare class BytemTracker {
+    private static instance;
+    private readonly SDK_NAME;
+    private readonly SDK_VERSION;
+    private readonly DEFAULT_ENDPOINT;
+    private readonly DEFAULT_API_PATH;
+    private appKey;
+    private baseUrl;
+    private debug;
+    private visitorId;
+    private deviceIdType;
+    private appScheme;
+    private apiPath;
+    private isInitialized;
+    private sessionStarted;
+    private useSessionCookie;
+    private sessionCookieTimeout;
+    private lastBeat;
+    private trackTime;
+    private storedDuration;
+    private lastViewTime;
+    private lastViewStoredDuration;
+    private constructor();
+    static getInstance(): BytemTracker;
+    init(config: TrackerConfig): Promise<void>;
+    private ensureInitialized;
+    beginSession(force?: boolean): Promise<void>;
+    sessionDuration(sec: number): Promise<void>;
+    endSession(sec?: number, force?: boolean): Promise<void>;
+    trackSessions(): Promise<void>;
+    startTime(): void;
+    stopTime(): void;
+    trackEvent(eventKey: string, segmentation?: Record<string, any>, count?: number, sum?: number, duration?: number): Promise<void>;
+    trackPageview(current: string, referrer?: string): Promise<void>;
+    trackGoodsClick(params: {
+        gid?: string;
+        skuid?: string;
+        url: string;
+        source?: string;
+        position?: string;
+        current?: string;
+        referrer?: string;
+    }): Promise<void>;
+    private reportViewDuration;
+    private getRealDeviceId;
+    private getMetrics;
+    private buildBaseRequestParams;
+    private extendSession;
+    private sendRequest;
+    trackViewProduct(product: Product): Promise<void>;
+    trackCheckOutOrder(order: Order): Promise<void>;
+    trackPayOrder(order: Order): Promise<void>;
+    trackUser(userId: string, traits?: UserTraits): Promise<void>;
+    private sendUserDetails;
+}
+declare const _default: BytemTracker;
+export default _default;

package/dist/src/BytemTracker.js

@@ -0,0 +1,474 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("./types");
+const storage_1 = require("./core/storage");
+const device_1 = require("./core/device");
+class BytemTracker {
+    constructor() {
+        // SDK Constants
+        this.SDK_NAME = 'react_native_bytem';
+        this.SDK_VERSION = '0.0.1'; // Should match package.json
+        this.DEFAULT_ENDPOINT = 'https://tracking.server.bytecon.com';
+        this.DEFAULT_API_PATH = '/i';
+        // Config
+        this.appKey = null;
+        this.baseUrl = this.DEFAULT_ENDPOINT;
+        this.debug = false;
+        this.visitorId = null;
+        this.deviceIdType = 1; // 1: Auto-generated
+        this.appScheme = null;
+        this.apiPath = this.DEFAULT_API_PATH;
+        this.isInitialized = false;
+        // Session Management
+        this.sessionStarted = false;
+        this.useSessionCookie = true;
+        this.sessionCookieTimeout = 30; // minutes
+        this.lastBeat = null;
+        this.trackTime = true;
+        this.storedDuration = 0;
+        this.lastViewTime = 0;
+        this.lastViewStoredDuration = 0;
+    }
+    static getInstance() {
+        if (!BytemTracker.instance) {
+            BytemTracker.instance = new BytemTracker();
+        }
+        return BytemTracker.instance;
+    }
+    async init(config) {
+        if (this.isInitialized) {
+            console.warn('[BytemTracker] Already initialized');
+            return;
+        }
+        this.appKey = config.appId;
+        if (config.endpoint) {
+            this.baseUrl = config.endpoint;
+        }
+        this.debug = !!config.debug;
+        this.appScheme = config.appScheme || null;
+        if (config.path) {
+            this.apiPath = config.path.startsWith('/') ? config.path : '/' + config.path;
+        }
+        // Initialize Visitor ID
+        if (config.visitorId) {
+            this.visitorId = config.visitorId;
+            await (0, storage_1.setItem)(storage_1.StorageKeys.VISITOR_ID, this.visitorId);
+            if (this.debug)
+                console.log(`[BytemTracker] Using provided visitor ID: ${this.visitorId}`);
+        }
+        else {
+            this.visitorId = await (0, storage_1.getItem)(storage_1.StorageKeys.VISITOR_ID);
+            if (!this.visitorId) {
+                this.visitorId = (0, device_1.generateUUID)();
+                await (0, storage_1.setItem)(storage_1.StorageKeys.VISITOR_ID, this.visitorId);
+                if (this.debug)
+                    console.log(`[BytemTracker] Generated new visitor ID: ${this.visitorId}`);
+            }
+            else {
+                if (this.debug)
+                    console.log(`[BytemTracker] Restored visitor ID: ${this.visitorId}`);
+            }
+        }
+        // Initialize Device ID type
+        if (config.deviceId) {
+            this.deviceIdType = 0; // Developer set
+            await (0, storage_1.setItem)(storage_1.StorageKeys.DEVICE_ID, config.deviceId);
+            if (this.debug)
+                console.log(`[BytemTracker] Using developer-set device ID: ${config.deviceId}`);
+        }
+        else {
+            this.deviceIdType = 1; // Auto generated (using visitor ID or platform ID logic)
+        }
+        this.isInitialized = true;
+        if (this.debug) {
+            console.log('[BytemTracker] Initialized ✅');
+            console.log(`  app_key: ${this.appKey}`);
+            console.log(`  base_url: ${this.baseUrl}`);
+            console.log(`  visitor_id: ${this.visitorId}`);
+            if (this.appScheme)
+                console.log(`  app_scheme: ${this.appScheme}`);
+        }
+        // Begin session
+        try {
+            await this.beginSession();
+        }
+        catch (e) {
+            if (this.debug) {
+                console.warn('[BytemTracker] Failed to begin session during init:', e);
+            }
+            this.sessionStarted = false;
+        }
+    }
+    ensureInitialized() {
+        if (!this.isInitialized) {
+            throw new Error('[BytemTracker] Not initialized. Call await init() first.');
+        }
+    }
+    async beginSession(force = false) {
+        this.ensureInitialized();
+        if (this.sessionStarted) {
+            if (this.debug)
+                console.log('[BytemTracker] Session already started, skipping');
+            return;
+        }
+        try {
+            this.sessionStarted = true;
+            this.lastBeat = Date.now();
+            // Check session cookie
+            const sessionKey = `${this.appKey}/cly_session`;
+            const expireTimestampStr = await (0, storage_1.getItem)(sessionKey);
+            const expireTimestamp = expireTimestampStr ? parseInt(expireTimestampStr, 10) : null;
+            const currentTimestamp = Date.now();
+            const shouldSendRequest = force ||
+                !this.useSessionCookie ||
+                expireTimestamp === null ||
+                expireTimestamp <= currentTimestamp;
+            if (!shouldSendRequest) {
+                if (this.debug)
+                    console.log('[BytemTracker] Session cookie still valid, skipping begin_session request');
+                // Update cookie
+                await (0, storage_1.setItem)(sessionKey, (currentTimestamp + this.sessionCookieTimeout * 60 * 1000).toString());
+                return;
+            }
+            const deviceId = await this.getRealDeviceId();
+            const metrics = await this.getMetrics();
+            const body = await this.buildBaseRequestParams(deviceId);
+            body['begin_session'] = '1';
+            body['metrics'] = JSON.stringify(metrics);
+            await this.sendRequest(this.apiPath, body, 'Begin Session');
+            await (0, storage_1.setItem)(sessionKey, (currentTimestamp + this.sessionCookieTimeout * 60 * 1000).toString());
+        }
+        catch (e) {
+            this.sessionStarted = false;
+            if (this.debug)
+                console.error('[BytemTracker] Error in beginSession:', e);
+        }
+    }
+    async sessionDuration(sec) {
+        this.ensureInitialized();
+        if (!this.sessionStarted) {
+            if (this.debug)
+                console.log('[BytemTracker] Session not started, skipping session_duration');
+            return;
+        }
+        const deviceId = await this.getRealDeviceId();
+        const body = await this.buildBaseRequestParams(deviceId);
+        body['session_duration'] = sec.toString();
+        await this.sendRequest(this.apiPath, body, 'Session Duration');
+        this.lastBeat = Date.now();
+        await this.extendSession();
+    }
+    async endSession(sec, force = false) {
+        this.ensureInitialized();
+        if (!this.sessionStarted) {
+            if (this.debug)
+                console.log('[BytemTracker] Session not started, skipping end_session');
+            return;
+        }
+        const currentTimestamp = Date.now();
+        const sessionSec = sec !== null && sec !== void 0 ? sec : (this.lastBeat ? (currentTimestamp - this.lastBeat) / 1000 : 0);
+        if (this.debug)
+            console.log(`[BytemTracker] Ending session with duration: ${sessionSec} seconds`);
+        if (this.useSessionCookie && !force) {
+            await this.sessionDuration(sessionSec);
+            this.sessionStarted = false;
+            return;
+        }
+        const deviceId = await this.getRealDeviceId();
+        const body = await this.buildBaseRequestParams(deviceId);
+        body['end_session'] = '1';
+        body['session_duration'] = sessionSec.toString();
+        await this.sendRequest(this.apiPath, body, 'End Session');
+        this.sessionStarted = false;
+    }
+    async trackSessions() {
+        this.ensureInitialized();
+        if (this.debug)
+            console.log('[BytemTracker] trackSessions called');
+        if (this.sessionStarted && this.lastBeat) {
+            const duration = (Date.now() - this.lastBeat) / 1000;
+            if (duration > 0) {
+                if (this.debug)
+                    console.log(`[BytemTracker] Session already started, sending session_duration: ${duration}s`);
+                await this.sessionDuration(duration);
+            }
+        }
+        else {
+            await this.beginSession();
+        }
+        this.startTime();
+        if (this.debug)
+            console.log('[BytemTracker] Session tracking started');
+    }
+    startTime() {
+        if (!this.trackTime) {
+            this.trackTime = true;
+            const now = Date.now();
+            if (this.lastBeat && this.storedDuration > 0) {
+                this.lastBeat = now - this.storedDuration;
+                this.storedDuration = 0;
+            }
+            else {
+                this.lastBeat = now;
+            }
+            if (this.lastViewStoredDuration > 0 && this.lastViewTime > 0) {
+                this.lastViewTime = now - this.lastViewStoredDuration;
+                this.lastViewStoredDuration = 0;
+            }
+            else {
+                this.lastViewTime = now;
+            }
+            if (this.debug)
+                console.log('[BytemTracker] Time tracking started');
+            this.extendSession();
+        }
+    }
+    stopTime() {
+        if (this.trackTime) {
+            this.trackTime = false;
+            const now = Date.now();
+            if (this.lastBeat) {
+                this.storedDuration = now - this.lastBeat;
+            }
+            if (this.lastViewTime > 0) {
+                this.lastViewStoredDuration = now - this.lastViewTime;
+            }
+            if (this.debug)
+                console.log('[BytemTracker] Time tracking stopped');
+        }
+    }
+    async trackEvent(eventKey, segmentation, count = 1, sum, duration) {
+        this.ensureInitialized();
+        const deviceId = await this.getRealDeviceId();
+        const now = new Date();
+        const event = {
+            key: eventKey,
+            count: count,
+            segmentation: segmentation,
+            timestamp: now.getTime(),
+            hour: now.getHours(),
+            dow: now.getDay() === 0 ? 0 : now.getDay(), // JS getDay: 0=Sun, Dart: 7=Sun but mapped to 0. 0-6.
+        };
+        if (sum !== undefined)
+            event.sum = sum;
+        if (duration !== undefined)
+            event.dur = duration;
+        const body = await this.buildBaseRequestParams(deviceId);
+        body['events'] = JSON.stringify([event]);
+        await this.sendRequest(this.apiPath, body, 'Event');
+    }
+    async trackPageview(current, referrer) {
+        await this.reportViewDuration();
+        const segmentation = {
+            name: current,
+            current: current,
+            referrer: '',
+        };
+        if (referrer)
+            segmentation.referrer = referrer;
+        let duration;
+        if (this.lastViewTime > 0) {
+            const now = Date.now();
+            duration = this.trackTime
+                ? (now - this.lastViewTime) / 1000
+                : this.lastViewStoredDuration / 1000;
+        }
+        this.lastViewTime = Date.now();
+        if (!this.trackTime) {
+            this.lastViewStoredDuration = 0;
+        }
+        await this.trackEvent(types_1.BytemEventKeys.view, segmentation, 1, undefined, duration);
+    }
+    async trackGoodsClick(params) {
+        this.ensureInitialized();
+        const segmentation = {
+            gid: params.gid || '',
+            skuid: params.skuid || '',
+            url: params.url,
+            current: params.current || '',
+            referrer: params.referrer || '',
+            visitor_id: this.visitorId || '',
+        };
+        if (this.appScheme)
+            segmentation.domain = this.appScheme;
+        if (params.source)
+            segmentation.source = params.source;
+        if (params.position)
+            segmentation.position = params.position;
+        await this.trackEvent('goods_click', segmentation); // Using string literal as Dart does in implementation
+    }
+    // --- Helpers ---
+    async reportViewDuration() {
+        if (this.lastViewTime === 0)
+            return;
+        const now = Date.now();
+        const duration = this.trackTime
+            ? (now - this.lastViewTime) / 1000
+            : this.lastViewStoredDuration / 1000;
+        if (duration > 0) {
+            if (this.debug)
+                console.log(`[BytemTracker] Last page duration: ${duration}s`);
+        }
+    }
+    async getRealDeviceId() {
+        // 1. Check developer set ID
+        if (this.deviceIdType === 0) {
+            const stored = await (0, storage_1.getItem)(storage_1.StorageKeys.DEVICE_ID);
+            if (stored)
+                return stored;
+        }
+        // 2. Use visitor ID
+        return this.visitorId || (0, device_1.generateUUID)();
+    }
+    async getMetrics() {
+        const metrics = {
+            _sdk_name: this.SDK_NAME,
+            _sdk_version: this.SDK_VERSION,
+        };
+        try {
+            const info = await (0, device_1.getDeviceInfo)();
+            metrics._platform_version = info.osVersion;
+            metrics._app_version = this.SDK_VERSION; // Or get actual app version if available
+            metrics._resolution = `${Math.round(info.screenWidth)}x${Math.round(info.screenHeight)}`;
+            metrics._locale = info.language;
+            // _density could be added if available in getDeviceInfo
+        }
+        catch (e) {
+            if (this.debug)
+                console.warn('[BytemTracker] Error getting metrics:', e);
+        }
+        return metrics;
+    }
+    async buildBaseRequestParams(deviceId) {
+        const now = new Date();
+        const visitorId = this.visitorId || (0, device_1.generateUUID)();
+        const params = {
+            app_key: this.appKey,
+            device_id: deviceId,
+            kid: visitorId,
+            visitor_id: visitorId,
+            sdk_name: this.SDK_NAME,
+            sdk_version: this.SDK_VERSION,
+            t: this.deviceIdType.toString(),
+            timestamp: now.getTime().toString(),
+            hour: now.getHours().toString(),
+            dow: (now.getDay() === 0 ? 0 : now.getDay()).toString(),
+        };
+        // Add location info if available (not implemented yet in this class properties)
+        return params;
+    }
+    async extendSession() {
+        if (!this.useSessionCookie)
+            return;
+        const sessionKey = `${this.appKey}/cly_session`;
+        const expireTimestampStr = await (0, storage_1.getItem)(sessionKey);
+        const currentTimestamp = Date.now();
+        const expireTimestamp = expireTimestampStr ? parseInt(expireTimestampStr, 10) : null;
+        if (expireTimestamp === null || expireTimestamp <= currentTimestamp) {
+            if (this.debug)
+                console.log('[BytemTracker] Session expired, restarting session');
+            this.sessionStarted = false;
+            await this.beginSession(true);
+        }
+        else {
+            await (0, storage_1.setItem)(sessionKey, (currentTimestamp + this.sessionCookieTimeout * 60 * 1000).toString());
+        }
+    }
+    async sendRequest(path, body, requestName) {
+        // Manually constructing URL and using fetch with urlencoded body
+        let requestUrl = this.baseUrl;
+        try {
+            // Handle endpoint/path logic
+            const urlObj = new URL(this.baseUrl);
+            if (path) {
+                if (path.startsWith('http')) {
+                    requestUrl = path;
+                }
+                else {
+                    // If base url has path, append or replace?
+                    // Dart implementation just concatenates: "$_baseUrl$path"
+                    // But _baseUrl usually has no trailing slash, and path starts with /
+                    const base = this.baseUrl.endsWith('/') ? this.baseUrl.slice(0, -1) : this.baseUrl;
+                    const endpointPath = path.startsWith('/') ? path : '/' + path;
+                    requestUrl = `${base}${endpointPath}`;
+                }
+            }
+        }
+        catch (e) {
+            requestUrl = this.baseUrl + path;
+        }
+        if (this.debug) {
+            console.log(`📤 [BytemTracker] Sending ${requestName}:`);
+            console.log(`  URL: ${requestUrl}`);
+            console.log(`  Body:`, body);
+        }
+        try {
+            // Convert body to urlencoded string
+            const formBody = Object.keys(body).map(key => encodeURIComponent(key) + '=' + encodeURIComponent(body[key])).join('&');
+            const response = await fetch(requestUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body: formBody,
+            });
+            if (this.debug) {
+                const resText = await response.text();
+                console.log(`📥 [BytemTracker] Response (${response.status}): ${resText}`);
+            }
+        }
+        catch (e) {
+            if (this.debug)
+                console.error(`❌ [BytemTracker] Error sending ${requestName}:`, e);
+        }
+    }
+    // Wrappers for Business methods to maintain compatibility or you can refactor them too
+    async trackViewProduct(product) {
+        // Map Product to segmentation
+        const segmentation = {
+            product_id: product.productId,
+            name: product.name,
+            price: product.price,
+            currency: product.currency,
+            category: product.category,
+        };
+        // In Dart, trackViewProduct sends "view_product" event.
+        await this.trackEvent('view_product', segmentation);
+    }
+    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.
+        };
+        await this.trackEvent('check_out_order', segmentation);
+    }
+    async trackPayOrder(order) {
+        const segmentation = {
+            order_id: order.orderId,
+            total: order.total,
+            currency: order.currency,
+        };
+        await this.trackEvent('pay_order', segmentation);
+    }
+    async trackUser(userId, traits) {
+        // Map to user_details
+        // This is a special request in Dart: "user_details" param
+        await this.sendUserDetails(userId, traits);
+    }
+    async sendUserDetails(userId, traits) {
+        this.ensureInitialized();
+        const deviceId = await this.getRealDeviceId();
+        const userData = Object.assign({}, traits);
+        if (userId) {
+            userData.custom = Object.assign(Object.assign({}, userData.custom), { user_id: userId, visitor_id: this.visitorId });
+        }
+        const body = await this.buildBaseRequestParams(deviceId);
+        body['user_details'] = JSON.stringify(userData);
+        await this.sendRequest(this.apiPath, body, 'User Details');
+    }
+}
+exports.default = BytemTracker.getInstance();

package/dist/src/business/index.d.ts

@@ -0,0 +1,4 @@
+export * from './trackViewProduct';
+export * from './trackCheckOutOrder';
+export * from './trackPayOrder';
+export * from './trackUser';

package/dist/src/business/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./trackViewProduct"), exports);
+__exportStar(require("./trackCheckOutOrder"), exports);
+__exportStar(require("./trackPayOrder"), exports);
+__exportStar(require("./trackUser"), exports);

package/dist/src/business/trackCheckOutOrder.d.ts

@@ -0,0 +1,2 @@
+import { EventPayload, Order } from '../types';
+export declare const trackCheckOutOrder: (order: Order) => EventPayload;

package/dist/src/business/trackCheckOutOrder.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackCheckOutOrder = void 0;
+const trackCheckOutOrder = (order) => {
+    return {
+        event: 'checkout_order',
+        params: {
+            order_id: order.orderId,
+            total: order.total,
+            currency: order.currency,
+            products: order.products.map((p) => ({
+                product_id: p.productId,
+                name: p.name,
+                price: p.price,
+                quantity: p.quantity,
+            })),
+        },
+    };
+};
+exports.trackCheckOutOrder = trackCheckOutOrder;

package/dist/src/business/trackPayOrder.d.ts

@@ -0,0 +1,2 @@
+import { EventPayload, Order } from '../types';
+export declare const trackPayOrder: (order: Order) => EventPayload;