209 lines
7.5 KiB
Markdown
209 lines
7.5 KiB
Markdown
|
||
# 事件跟踪接口说明
|
||
|
||
## 概述
|
||
该接口用于跟踪用户交互事件并将数据存储到 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
|