npm package: @fengju/tracking-sdk
Description: 轻量级 Tracking SDK - 自归因 + 埋点上报 + GTM 对接
Author: IAP Team
Latest version: 1.0.0

# 📊 Tracking SDK

轻量级 Tracking SDK - 自归因 + 埋点上报 + GTM 对接

## ✨ 特性

- 🎯 **自归因（Self Attribution）** - 自动解析 URL 参数，支持 UTM、广告平台参数等
- 📈 **统一埋点事件上报** - 自动补充标识符、归因数据，支持批量发送
- 🔗 **GTM dataLayer 输出** - 自动推送事件到 GTM，供 GA4/FB Tag 使用
- 🚀 **轻量级** - 体积 ≤ 30KB gzip，无第三方依赖
- 📦 **多格式支持** - 支持 ESM / CJS / UMD，支持 NPM 与 CDN 引入
- 🛡️ **SSR 兼容** - 自动检测 SSR 环境，不会报错
- 🔒 **隐私合规** - 支持隐私同意配置，符合 GDPR/CCPA 要求
- 🐛 **Debug 模式** - 详细的调试日志，方便开发调试

## 📦 安装

### NPM 安装

```bash
npm install @iap/tracking-sdk
# 或
pnpm add @iap/tracking-sdk
# 或
yarn add @iap/tracking-sdk
```

### CDN 引入

```html
<script src="https://cdn.example.com/tracking-sdk/index.umd.js"></script>
```

## 🚀 快速开始

### 1. 初始化 SDK

```typescript
import TrackingSDK from '@iap/tracking-sdk';

TrackingSDK.init({
  appId: 'your-app-id',
  endpoint: 'https://api.example.com/tracking',
  env: 'prod',
  debug: false,
  enableAttribution: true,
  enableTracking: true,
  enableGTM: true,
});
```

### 2. 追踪事件

```typescript
// 基础事件
TrackingSDK.track('page_view');

// 带属性的事件
TrackingSDK.track('purchase', {
  amount: 99.99,
  currency: 'USD',
  product_id: 'prod_123',
});
```

### 3. 设置用户 ID

```typescript
TrackingSDK.setUserId('user_123456');
```

### 4. 获取归因数据

```typescript
const attribution = TrackingSDK.getAttribution();
console.log(attribution);
// {
//   source: 'google',
//   medium: 'cpc',
//   campaign: 'summer_sale',
//   gclid: '123456',
//   timestamp: 1733200000000
// }
```

### 5. 隐私同意配置

```typescript
TrackingSDK.setConsent({
  analytics: true,  // 允许分析追踪
  ads: false,      // 禁止广告追踪
});
```

## 📖 API 文档

### `TrackingSDK.init(config)`

初始化 SDK。

**参数：**

```typescript
interface SDKConfig {
  appId: string;                       // 必填：应用 ID
  endpoint: string;                    // 必填：事件和归因上报路径
  env?: 'prod' | 'stage' | 'dev';     // 环境，默认 'prod'
  enableAttribution?: boolean;        // 启用归因，默认 true
  enableTracking?: boolean;           // 启用追踪，默认 true
  enableGTM?: boolean;                // 启用 GTM，默认 true
  debug?: boolean;                     // Debug 模式，默认 false
  attributionWindowDays?: number;    // 归因窗口天数，默认 30
  batch?: {
    enabled: boolean;                  // 批量发送，默认 false
    maxSize: number;                  // 批量大小，默认 10
    interval: number;                 // 批量间隔（ms），默认 3000
  };
  featureFlags?: Record<string, boolean>;
  attributionMap?: Record<string, string>; // 参数映射扩展
  sessionTimeoutMinutes?: number;     // 会话超时分钟数，默认 30
}
```

### `TrackingSDK.track(eventName, properties?)`

追踪事件。

**参数：**
- `eventName: string` - 事件名称
- `properties?: Record<string, any>` - 事件属性（可选）

**示例：**

```typescript
TrackingSDK.track('signup_submit', {
  method: 'email',
  plan: 'premium',
});
```

### `TrackingSDK.setUserId(userId)`

设置用户 ID。

**参数：**
- `userId: string` - 用户 ID

### `TrackingSDK.getAttribution()`

获取当前归因数据。

**返回：**
```typescript
AttributionData | null
```

### `TrackingSDK.setConsent(consent)`

设置隐私同意配置。

**参数：**
```typescript
interface ConsentConfig {
  analytics?: boolean;  // 分析追踪同意
  ads?: boolean;       // 广告追踪同意
}
```

## 🎯 协议支持

SDK 支持多种埋点协议：

- **112/113**：立即发送协议，用于重要事件
- **512**：延迟发送协议，定时批量上传（默认 1 分钟）
- **513**：普通发送协议，按批量配置发送

**使用方式：**

```typescript
// 使用默认协议号
TrackingSDK.track('page_view');

// 指定协议号
TrackingSDK.track('event_name', { src: 513 });

// 延迟协议（512）
TrackingSDK.track('user_behavior', { src: 512 });
```

详细说明请查看 [INTEGRATION.md](./INTEGRATION.md)。

## 🎯 自归因功能

SDK 自动从 URL 参数中解析归因信息，支持的参数包括：

### 通用参数

- `utm_source` - 来源
- `utm_medium` - 媒介
- `utm_campaign` - 活动
- `utm_term` - 关键词
- `utm_content` - 内容
- `qid` / `cuid` - 自定义 ID
- `aff_id` - 联盟 ID
- `sub1` - `sub5` - 子参数

### 广告平台参数

- **Google**: `gclid`, `gbraid`, `wbraid`
- **Facebook**: `fbclid`
- **TikTok**: `ttclid`
- **其他**: `click_id`, `clickid`, `af_click_id`

### 归因规则

1. **优先级**：点击 ID > UTM 参数 > Referrer
2. **归因窗口**：默认 30 天（可配置）
3. **Last Click**：窗口内再次点击会覆盖之前的归因

### 示例

访问 URL：
```
https://example.com/?utm_source=google&utm_medium=cpc&utm_campaign=test&gclid=123456
```

SDK 会自动解析并保存归因数据。

## 📊 自动埋点事件

SDK 会自动追踪以下事件：

| 事件名 | 触发条件 | 属性 |
|--------|---------|------|
| `page_view` | 页面加载/路由变更 | path, referrer, title, url |
| `session_start` | 新 session 生成 | sessionId |
| `session_end` | 页面关闭（尽力而为） | sessionId |

## 🔗 GTM 对接

SDK 会自动将所有事件推送到 GTM dataLayer：

```javascript
dataLayer.push({
  event: 'gg_event',        // 固定事件入口
  event_name: 'purchase',
  browser_id: 'xxx',
  session_id: 'yyy',
  user_id: 'uuu',
  attribution: {...},
  properties: {...}
});
```

### GTM 配置

在 GTM 中配置 Trigger 和 Tag：

1. **Trigger**: 事件名称为 `gg_event`
2. **Tag**: 使用 `{{event_name}}` 作为事件名，`{{properties}}` 作为事件参数

## 🛠️ 开发

### 构建

```bash
# 开发模式（watch）
pnpm dev

# 生产构建
pnpm build
```

**详细构建教程：** 查看 [BUILD.md](./BUILD.md)

### 测试

```bash
# 运行所有测试
pnpm test

# 测试覆盖率
pnpm test:coverage

# Watch 模式
pnpm test --watch
```

**详细测试文档：** 查看 [TESTING.md](./TESTING.md)

### Demo 和测试面板

- **基础 Demo**: 打开 `demo/index.html` 查看完整示例
- **测试面板**: 打开 `demo/test-panel.html` 使用功能完整的测试面板
  - 可视化配置 SDK
  - 实时查看标识符和归因数据
  - URL 参数构建器
  - 事件追踪测试
  - 日志输出和统计信息

## 📝 事件结构

所有事件都会自动补充以下字段：

```typescript
interface TrackEvent {
  event: string;              // 事件名称
  ts: number;                 // 时间戳（毫秒）
  browserId: string;          // 浏览器 ID（UUID）
  sessionId: string;          // 会话 ID（UUID）
  userId?: string;            // 用户 ID（可选）
  attribution?: AttributionData; // 归因数据（可选）
  properties?: Record<string, any>; // 自定义属性
  env?: string;               // 环境
}
```

## 🔒 隐私合规

SDK 支持隐私同意配置，当 `analytics: false` 时：
- 禁止发送所有事件
- 禁止写入归因数据

当 `ads: false` 时：
- 禁止写入广告相关参数（gclid, fbclid 等）
- 禁止推送 dataLayer

## 🐛 Debug 模式

启用 Debug 模式后，SDK 会在控制台输出：

- 归因解析结果
- 每条事件的完整结构
- 上报成功/失败原因
- dataLayer push 内容

**注意**：Debug 模式会自动过滤敏感字段（邮箱、手机号等）。

## 📦 构建产物

构建后会生成以下文件：

- `dist/index.esm.js` - ESM 格式
- `dist/index.cjs.js` - CJS 格式
- `dist/index.umd.js` - UMD 格式（CDN 使用）
- `dist/index.d.ts` - TypeScript 类型定义

## 🔧 配置示例

### 基础配置

```typescript
TrackingSDK.init({
  appId: 'my-app',
  endpoint: 'https://api.example.com/tracking',
});
```

### 完整配置

```typescript
TrackingSDK.init({
  appId: 'my-app',
  endpoint: 'https://api.example.com/tracking',
  env: 'prod',
  debug: false,
  enableAttribution: true,
  enableTracking: true,
  enableGTM: true,
  attributionWindowDays: 30,
  sessionTimeoutMinutes: 30,
  batch: {
    enabled: true,
    maxSize: 10,
    interval: 3000,
  },
  attributionMap: {
    'custom_param': 'custom_field', // URL 参数映射
  },
});
```

## 📚 相关文档

- [BUILD.md](./BUILD.md) - 详细的打包和构建教程
- [ARCHITECTURE.md](./ARCHITECTURE.md) - 架构说明和设计文档
- [INTEGRATION.md](./INTEGRATION.md) - **112/113 协议整合说明**（重要）
- [demo/test-panel.html](./demo/test-panel.html) - 功能完整的测试面板

## 📄 许可证

MIT

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！