@ccserv/event-tracker


Cocos Event Tracker SDK 是一个用于追踪和发送事件的 JavaScript/TypeScript SDK，具有内置的时间同步和重试机制。

特性

- 🚀 轻量级 - 小巧的包体积，无外部依赖
- 📊 高性能 - 支持批量发送和异步处理
- 🔄 自动重试 - 内置重试机制，确保数据可靠传输
- ⏰ 时间同步 - 自动与服务器时间同步，确保时间准确性
- 📦 多格式 - 支持 ESM、CommonJS 和 UMD 格式
- 🎯 TypeScript 支持 - 完整的类型定义
- 🌐 浏览器兼容 - 支持所有现代浏览器
- 🐛 调试模式 - 内置详细的调试日志

安装

$3

``bash
npm install @ccserv/event-tracker
`

$3

`bash
yarn add @ccserv/event-tracker
`

$3

`html

`

快速开始

$3

`javascript
import CocosEventTracker from '@ccserv/event-tracker';

const tracker = new CocosEventTracker({
apiEndpoint: 'https://your-api-domain.com/api/v1/events',
timestampEndpoint: 'https://your-api-domain.com/api/v1/timestamp',
appId: 'your-app-id as number',
bundle: 'your-app-bundle',
debug: true
});

await tracker.init('user123', 'session456');

await tracker.track('user.login', {
login_method: 'password',
success: true
});
`

$3

`javascript
const { CocosEventTracker } = require('@ccserv/event-tracker');

const tracker = new CocosEventTracker({
apiEndpoint: 'https://your-api-domain.com/api/v1/events',
appId: 'your-app-id as number',
bundle: 'your-app-bundle'
});

await tracker.init();
await tracker.track('page.view', { page: '/dashboard' });
`

$3

`html


`

配置选项

`typescript
interface CocosEventTrackerConfig {
apiEndpoint?: string; // 事件上报 API 地址，默认: '/api/v1/events'
timestampEndpoint?: string; // 时间戳同步 API 地址，默认: '/api/v1/timestamp'
appId?: number; // 应用 ID
bundle?: string; // 应用包名/域名，默认: 'unknown-app'
language?: string; // 语言代码，默认: 'zh-CN'
network?: string; // 网络类型，默认: 'unknown'
appVersion?: string; // 应用版本，默认: '1.0.0'
osVersion?: string; // 操作系统版本
enableAutoTimestamp?: boolean; // 启用自动时间同步，默认: true
enableRetry?: boolean; // 启用重试机制，默认: true
maxRetries?: number; // 最大重试次数，默认: 3
retryDelay?: number; // 重试延迟（毫秒），默认: 1000
batchSize?: number; // 批量发送大小，默认: 10
batchInterval?: number; // 批量发送间隔（毫秒），默认: 5000
enableBatching?: boolean; // 启用批量处理，默认: false
debug?: boolean; // 启用调试日志，默认: false
}
`

API 文档

$3

`typescript
new CocosEventTracker(config?: CocosEventTrackerConfig)
`

创建一个新的 CocosEventTracker 实例。

$3

初始化 SDK 并同步服务器时间。

参数:
- userId (string, optional): 用户 ID
- sessionId (string, optional): 会话 ID

返回值: Promise - 初始化是否成功

$3

发送单个事件。

参数:
- eventType (string): 事件类型
- fields (object, optional): 事件字段
- eventTimestamp (string, optional): 事件时间戳

返回值: Promise - 发送是否成功

$3

批量发送事件。

参数:
- events (EventInput[]): 事件数组

返回值: Promise - 发送是否成功

$3

设置当前用户信息。

参数:
- userId (string): 用户 ID
- sessionId (string, optional): 会话 ID

$3

获取 SDK 统计信息。

返回值: TrackerStats

$3

重置统计信息。

$3

立即发送队列中的所有事件。

返回值: Promise - 发送是否成功

$3

销毁 SDK 并清理资源。

批量处理

启用批量处理可以显著提高性能：

`javascript
const tracker = new CocosEventTracker({
apiEndpoint: '/api/v1/events',
appId: 123,
bundle: 'example.com',
enableBatching: true,
batchSize: 20, // 20 个事件一批
batchInterval: 5000 // 或每 5 秒一批
});

await tracker.init();

// 事件会被自动批量发送
await tracker.track('user.click', { button: 'signup' });
await tracker.track('page.view', { page: '/dashboard' });
await tracker.track('user.action', { action: 'scroll' });
`

错误处理

`javascript
const tracker = new CocosEventTracker({
apiEndpoint: '/api/v1/events',
appId: 123,
bundle: 'example.com',
debug: true
});

const success = await tracker.init();
if (!success) {
console.error('SDK 初始化失败');
return;
}

const result = await tracker.track('user.login', {
method: 'password'
});

if (!result) {
const stats = tracker.getStats();
console.error('事件发送失败', stats);
}
`

统计信息

`javascript
const stats = tracker.getStats();
console.log('发送统计:', {
总发送数: stats.totalSent,
成功数: stats.successCount,
失败数: stats.errorCount,
平均响应时间: stats.avgResponseTime + 'ms',
队列大小: stats.queueSize,
已初始化: stats.isInitialized
});
`

生命周期管理

`javascript
// 页面加载时初始化
let tracker;

async function initializeApp() {
tracker = new CocosEventTracker({
apiEndpoint: '/api/v1/events',
appId: 123,
bundle: 'example.com'
});

await tracker.init();
}

// 页面卸载时清理
window.addEventListener('beforeunload', () => {
if (tracker) {
tracker.destroy();
}
});
`

完整示例

`javascript
import CocosEventTracker from '@ccserv/event-tracker';

class AppAnalytics {
constructor() {
this.tracker = new CocosEventTracker({
apiEndpoint: 'https://api.example.com/v1/events',
timestampEndpoint: 'https://api.example.com/v1/timestamp',
appId: 618115551,
bundle: 'app.example.com',
appVersion: '1.0.0',
language: 'zh-CN',
enableBatching: true,
batchSize: 10,
batchInterval: 3000,
debug: process.env.NODE_ENV === 'development'
});
}

async initialize(userId, sessionId) {
try {
const success = await this.tracker.init(userId, sessionId);
if (!success) {
throw new Error('SDK 初始化失败');
}

// 追踪应用启动
await this.trackAppStartup();

// 追踪页面访问
this.trackPageView();

} catch (error) {
console.error('Analytics 初始化失败:', error);
}
}

async trackAppStartup() {
const startTime = performance.now();
await this.tracker.track('timing.app_startup', {
startup_time: Math.round(startTime / 1000),
initialization_time: Math.round(startTime * 0.3 / 1000),
resource_load_time: Math.round(startTime * 0.7 / 1000),
success: true
});
}

trackPageView(page = window.location.pathname) {
this.tracker.track('page.view', {
page: page,
title: document.title,
referrer: document.referrer,
timestamp: new Date().toISOString()
});
}

trackUserAction(action, properties = {}) {
this.tracker.track('user.action', {
action: action,
...properties,
timestamp: new Date().toISOString()
});
}

trackError(error, context = {}) {
this.tracker.track('error.javascript', {
error_message: error.message,
error_stack: error.stack,
context: context,
timestamp: new Date().toISOString()
});
}

destroy() {
if (this.tracker) {
this.tracker.destroy();
}
}
}

// 使用示例
const analytics = new AppAnalytics();

// 应用启动时初始化
analytics.initialize('user123', 'session456');

// 追踪各种事件
analytics.trackUserAction('button_click', { button: 'signup' });
analytics.trackUserAction('form_submit', { form: 'login' });

// 页面卸载时清理
window.addEventListener('beforeunload', () => {
analytics.destroy();
});
`

开发

$3

- Node.js: v22.17.1+
- npm: v10.9.2+
- TypeScript: v5.3.3+

$3

`bash


安装依赖

npm install

开发模式

npm run dev

构建

npm run build

测试

npm test

复制到开发环境

npm run copy:dev
``

许可证

MIT License

支持

如有问题或建议，请联系开发团队。