核心概念
了解 AntDock 的核心概念，帮助您更好地使用 SDK。
事件 (Event)
事件是 AntDock 的基本数据单元。每当用户执行某个操作，SDK 就会创建一个事件并发送到服务器。
事件结构
{
"type": "event",
"appId": "ws_xxx",
"sessionId": "sess_xxx",
"visitorId": "vis_xxx",
"userId": "user_123",
"url": "https://example.com/page",
"path": "/page",
"referrer": "https://google.com",
"data": {
"name": "button_click",
"button_id": "submit"
},
"timestamp": 1706265600000
}
事件类型
| 类型 | 说明 | 自动采集 |
|---|---|---|
pageview |
页面访问 | ✅ Web |
event |
自定义事件 | ❌ |
identify |
用户标识 | ❌ |
click |
点击事件 | ✅ Web (可选) |
error |
错误事件 | ✅ Web (可选) |
访客 (Visitor)
访客代表一个唯一的浏览器或设备。通过 Visitor ID 标识，存储在本地 (localStorage 或设备存储)。
Visitor ID: vis_abc123def456
├── Session 1 (2024-01-01)
│ ├── PageView: /home
│ ├── Event: button_click
│ └── PageView: /products
├── Session 2 (2024-01-03)
│ └── PageView: /checkout
└── Session 3 (2024-01-05)
└── Event: purchase
特点
- 持久化: 存储在本地，多次访问保持不变
- 匿名: 不包含任何个人身份信息
- 设备绑定: 一个设备 = 一个 Visitor ID
会话 (Session)
会话代表用户的一次连续访问。默认 30 分钟无活动后会话过期。
会话判定规则
新会话在以下情况创建：
- 首次访问 (无现有会话)
- 超过 30 分钟无活动
- 跨越午夜 (UTC)
- 来源发生变化 (referrer 不同)
时间线:
10:00 - 访问首页 → 会话 1 开始
10:05 - 浏览商品页 → 会话 1 继续
10:10 - 添加购物车 → 会话 1 继续
11:00 - 离开网站
13:00 - 再次访问 → 会话 2 开始 (超过 30 分钟)
用户 (User)
用户代表已登录或已标识的真实用户。通过 identify() 方法关联。
// 用户登录后
AntDockTracker.identify('user_123', {
email: 'user@example.com',
name: '张三',
plan: 'premium',
createdAt: '2024-01-01'
})
用户标识流程
匿名访客 已识别用户
┌─────────┐ ┌─────────┐
│ vis_xxx │ identify() │ user_123│
│ │ ─────────▶ │ vis_xxx │
│ 匿名 │ │ 张三 │
└─────────┘ └─────────┘
用户特征 (Traits)
用户特征是用户的属性信息：
{
email: 'user@example.com', // 邮箱
name: '张三', // 姓名
plan: 'premium', // 付费计划
company: 'Acme Inc', // 公司
createdAt: '2024-01-01' // 注册时间
}
属性 (Properties)
事件属性是附加在事件上的额外数据。
AntDockTracker.trackEvent('purchase', {
// 属性
order_id: 'ORD-12345',
amount: 99.99,
currency: 'CNY',
items: ['item_1', 'item_2'],
coupon: 'SAVE10'
})
属性最佳实践
| ✅ 推荐 | ❌ 避免 |
|---|---|
使用下划线命名: order_id |
使用空格: order id |
| 保持一致的命名 | 不同事件使用不同命名 |
| 使用有意义的名称 | 使用缩写: oid |
| 传递必要的数据 | 传递敏感数据 (密码等) |
页面和路径
URL vs 路径
- URL: 完整的页面地址，包含协议、域名、路径、查询参数
- 路径: URL 的路径部分，用于分组分析
URL: https://example.com/products/123?ref=home
路径: /products/123
路径规范化
SDK 会自动进行路径规范化：
// 输入
'/products/123?ref=home#section'
// 规范化后
'/products/123'
数据收集流程
┌─────────────────────────────────────────────────────────┐
│ 客户端 SDK │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 事件采集 │ → │ 事件队列 │ → │ 批量合并 │ → │ 网络发送 │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
POST /api/collect/batch
│
▼
┌─────────────────────────────────────────────────────────┐
│ 服务端 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ API 网关 │ → │ 数据处理 │ → │ClickHouse│ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────┘
批量上报
SDK 使用批量上报机制，提高性能并减少网络请求：
- 事件首先进入本地队列
- 队列满 (默认 10 条) 或定时器触发 (默认 5 秒) 时批量发送
- 页面关闭时使用
sendBeacon确保数据发送