# 事件跟踪接口说明

## 概述
该接口用于跟踪用户交互事件并将数据存储到 ClickHouse 数据库中。支持记录各种类型的事件，并可包含与链接、用户、团队、项目等相关的详细信息。

## 接口信息
- **URL**: `/api/events/track`
- **方法**: `POST`
- **Content-Type**: `application/json`

## 请求参数

### 必填字段
| 参数 | 类型 | 描述 |
|------|------|------|
| `event_type` | string | 事件类型，如 'click', 'view', 'conversion' |

### 核心事件字段
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `event_id` | string | 否 | 事件唯一标识符，不提供时自动生成UUID |
| `event_time` | string/Date | 否 | 事件发生时间，格式为ISO日期字符串，默认为当前时间 |
| `event_attributes` | object/string | 否 | 事件相关的其他属性，可以是JSON对象或JSON字符串 |

### 链接信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `link_id` | string | 否 | 短链接的唯一ID |
| `link_slug` | string | 否 | 短链接的slug部分 |
| `link_label` | string | 否 | 短链接的显示名称 |
| `link_title` | string | 否 | 短链接的标题 |
| `link_original_url` | string | 否 | 原始目标URL |
| `link_attributes` | object/string | 否 | 链接相关的额外属性 |
| `link_created_at` | string/Date | 否 | 链接创建时间 |
| `link_expires_at` | string/Date | 否 | 链接过期时间 |
| `link_tags` | array/string | 否 | 链接标签，可以是数组或JSON字符串 |

### 用户信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `user_id` | string | 否 | 用户ID |
| `user_name` | string | 否 | 用户名称 |
| `user_email` | string | 否 | 用户邮箱 |
| `user_attributes` | object/string | 否 | 用户相关的其他属性 |

### 团队和项目信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `team_id` | string | 否 | 团队ID |
| `team_name` | string | 否 | 团队名称 |
| `team_attributes` | object/string | 否 | 团队相关的其他属性 |
| `project_id` | string | 否 | 项目ID |
| `project_name` | string | 否 | 项目名称 |
| `project_attributes` | object/string | 否 | 项目相关的其他属性 |

### 二维码信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `qr_code_id` | string | 否 | 二维码ID |
| `qr_code_name` | string | 否 | 二维码名称 |
| `qr_code_attributes` | object/string | 否 | 二维码相关的其他属性 |

### 访问者信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `visitor_id` | string | 否 | 访问者唯一标识符，不提供时自动生成 |
| `session_id` | string | 否 | 会话ID，不提供时自动生成 |
| `ip_address` | string | 否 | 访问者IP地址，默认从请求头获取 |
| `country` | string | 否 | 访问者所在国家 |
| `city` | string | 否 | 访问者所在城市 |
| `device_type` | string | 否 | 设备类型 (如 desktop, mobile, tablet) |
| `browser` | string | 否 | 浏览器名称 |
| `os` | string | 否 | 操作系统 |
| `user_agent` | string | 否 | 用户代理字符串，默认从请求头获取 |

### 引荐来源信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `referrer` | string | 否 | 引荐URL，默认从请求头获取 |
| `utm_source` | string | 否 | UTM来源参数 |
| `utm_medium` | string | 否 | UTM媒介参数 |
| `utm_campaign` | string | 否 | UTM活动参数 |
| `utm_term` | string | 否 | UTM术语参数 |
| `utm_content` | string | 否 | UTM内容参数 |

### 交互信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `time_spent_sec` | number | 否 | 用户在页面上停留的时间（秒），默认0 |
| `is_bounce` | boolean | 否 | 是否是跳出（只访问一个页面），默认true |
| `is_qr_scan` | boolean | 否 | 是否来自二维码扫描，默认false |
| `conversion_type` | string | 否 | 转化类型 |
| `conversion_value` | number | 否 | 转化价值，默认0 |

## 响应格式

### 成功响应 (201 Created)
```json
{
  "success": true,
  "message": "Event tracked successfully",
  "event_id": "uuid-of-tracked-event"
}
```

### 错误响应

#### 缺少必填字段 (400 Bad Request)
```json
{
  "error": "Missing required field: event_type"
}
```

#### 服务器错误 (500 Internal Server Error)
```json
{
  "error": "Failed to track event",
  "details": "具体错误信息"
}
```

## 使用示例

### 基本事件跟踪请求
```javascript
fetch('/api/events/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_type: 'click',
    link_id: 'abc123',
    link_slug: 'promo-summer',
    link_original_url: 'https://example.com/summer-promotion'
  })
})
```

### 详细事件跟踪请求
```javascript
fetch('/api/events/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_type: 'conversion',
    link_id: 'abc123',
    link_slug: 'promo-summer',
    link_original_url: 'https://example.com/summer-promotion',
    event_attributes: {
      page: '/checkout',
      product_id: 'xyz789'
    },
    user_id: 'user123',
    team_id: 'team456',
    project_id: 'proj789',
    visitor_id: 'vis987',
    is_bounce: false,
    time_spent_sec: 120,
    conversion_type: 'purchase',
    conversion_value: 99.99,
    utm_source: 'email',
    utm_campaign: 'summer_sale'
  })
})
```

## 注意事项
- 所有对象类型的字段（如 `event_attributes`）可以作为对象或预先格式化的JSON字符串传递
- 如果不提供 `event_id`、`visitor_id` 或 `session_id`，系统将自动生成
- 时间戳字段接受ISO格式的日期字符串，并会被转换为ClickHouse兼容的格式


UTM 测试示例。1. 电子邮件营销链接
https://short.domain.com/summer?utm_source=newsletter&utm_medium=email&utm_campaign=summer_promo&utm_term=discount&utm_content=header
说明: 用于电子邮件营销活动，跟踪用户从邮件头部横幅点击的流量。

2. 社交媒体广告链接
https://short.domain.com/product?utm_source=instagram&utm_medium=social&utm_campaign=fall_collection&utm_content=story
说明: 用于 Instagram Story 广告，跟踪用户从社交媒体故事广告点击的情况。

3. 搜索引擎广告链接
https://short.domain.com/service?utm_source=google&utm_medium=cpc&utm_campaign=brand_terms&utm_term=service+name
说明: 用于 Google Ads 广告，跟踪用户从搜索引擎付费广告点击的流量，特别是针对特定搜索词。

4. QR 码链接
https://short.domain.com/event?utm_source=flyer&utm_medium=print&utm_campaign=local_event&utm_content=qr_code&source=qr
说明: 用于打印材料上的 QR 码，跟踪用户扫描实体宣传资料的情况。

5. 合作伙伴引荐链接
https://short.domain.com/partner?utm_source=affiliate&utm_medium=referral&utm_campaign=partner_program&utm_content=banner
说明: 用于合作伙伴网站上的推广横幅，跟踪来自联盟营销的转化率。


https://upj.to/5seaii?utm_source=newsletter&utm_medium=email&utm_campaign=summer_promo&utm_term=discount&utm_content=header

https://upj.to/5seaii?utm_source=instagram&utm_medium=social&utm_campaign=fall_collection&utm_content=story

https://upj.to/5seaii?utm_source=google&utm_medium=cpc&utm_campaign=brand_terms&utm_term=service+name


https://upj.to/5seaii?utm_source=flyer&utm_medium=print&utm_campaign=local_event&utm_content=qr_code&source=qr

https://upj.to/5seaii?utm_source=affiliate&utm_medium=referral&utm_campaign=partner_program&utm_content=banner