API REFERENCE
访客追踪 API
实时捕获访客行为数据，包括页面浏览、停留时长、滚动深度与互动事件
追踪事件类型
翠鸟追踪系统会自动采集以下事件，无需手动上报。如需扩展自定义事件，可通过 JavaScript SDK 或 API 主动推送。
| 事件名称 | 触发时机 | 说明 |
|---|---|---|
page_view | 访客打开内容页面 | 记录 URL、来源渠道、设备类型、IP归属地 |
dwell_time | 访客在页面停留期间（每30秒） | 累计停留时长，支持后台统计平均阅读时间 |
scroll_depth | 页面滚动到 25% / 50% / 75% / 100% | 评估内容完读率的核心指标 |
cta_view | CTA 组件进入视口 | 记录 CTA 曝光次数 |
cta_click | 访客点击 CTA 按钮 | 触发线索转化流程 |
form_submit | 访客提交留资表单 | 创建线索记录，触发后续 Webhook 事件 |
custom | 自定义触发 | 通过 SDK 手动上报，支持自定义属性 |
接入追踪脚本
翠鸟追踪脚本是一段轻量 JavaScript（压缩后约 8KB），异步加载，不影响页面性能。将以下代码添加到您内容页面的 <head> 标签内即可完成接入。
<!-- 翠鸟追踪脚本 -->
<script>
(function(c,u,i,n,i2,a,o){
c['CuiniaoObject']=i2;c[i2]=c[i2]||function(){
(c[i2].q=c[i2].q||[]).push(arguments)};
a=u.createElement(i);o=u.getElementsByTagName(i)[0];
a.async=1;a.src=n;o.parentNode.insertBefore(a,o)
})(window,document,'script',
'https://cdn.cuiniao.com/track/v2/cn.min.js','cn');
cn('init', 'YOUR_SITE_TOKEN');
cn('track', 'page_view');
</script>
将
YOUR_SITE_TOKEN 替换为翠鸟控制台 — 内容设置 — 追踪 中显示的 Site Token。每个内容资源有独立 Token，也可使用账号级全局 Token。手动上报自定义事件
// 上报自定义事件，附带属性
cn('track', 'custom', {
event_name: 'video_play',
resource_id: 'res_7fK2mPqLxNz',
properties: {
video_title: '产品演示视频',
duration_watched: 45 // 单位：秒
}
});
事件数据格式
通过 GET /v1/tracking/events 接口可查询指定内容资源的原始事件数据，支持时间范围过滤。
# 查询某资源最近7天的事件
curl "https://api.cuiniao.com/v1/tracking/events?resource_id=res_7fK2mPqLxNz&days=7" \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx"
事件对象结构
{
"event_id": "evt_3nRp7wQz",
"event_type": "scroll_depth",
"resource_id": "res_7fK2mPqLxNz",
"visitor_id": "vis_anon_Kx9mL", // 匿名访客ID（持久化至浏览器）
"session_id": "sess_Zq2pNr",
"occurred_at": "2024-03-15T09:12:33Z",
"properties": {
"depth_percent": 75,
"page_url": "https://c.cuiniao.com/r/7fK2mPqLxNz",
"referrer": "https://www.linkedin.com/",
"device_type": "desktop",
"country": "CN",
"city": "Shanghai"
}
}
隐私合规说明
翠鸟追踪系统在设计上遵循最小数据原则，帮助您在业务增长与用户隐私之间取得平衡。
- 默认不采集访客姓名、邮箱等个人识别信息（PII），仅采集匿名行为数据
- 访客 IP 地址在落库前经过脱敏处理，仅保留城市级地理位置
- 支持通过
cn('optout')实现访客自主退出追踪 - 数据存储在中国大陆数据中心，符合《个人信息保护法》相关要求
- 如需传递已识别访客身份，请使用
cn('identify', userId)并确保已获取用户同意
建议在您的隐私政策中说明使用翠鸟追踪技术，并在 Cookie 弹窗中为访客提供退出选项。