shorturl-analytics/app/api/events/track/readme.md

事件跟踪接口说明

概述

该接口用于跟踪用户交互事件并将数据存储到 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)

{
  "success": true,
  "message": "Event tracked successfully",
  "event_id": "uuid-of-tracked-event"
}

错误响应

缺少必填字段 (400 Bad Request)

{
  "error": "Missing required field: event_type"
}

服务器错误 (500 Internal Server Error)

{
  "error": "Failed to track event",
  "details": "具体错误信息"
}

使用示例

基本事件跟踪请求

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'
  })
})

详细事件跟踪请求

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