RLTracer SDK 使用文档

RLTracer 是一个轻量级的前端行为埋点 SDK，支持自动采集点击、曝光以及自定义事件。

安装

可以通过 npm 安装或直接饮用构建产物。

NPM

npm install rl-tracer

CDN / Script Tag

<script src="path/to/dist/rl-tracer.iife.js"></script>

初始化 (Initialization)

在应用启动时初始化 SDK：

import RLTracer from 'rl-tracer';

const tracker = new RLTracer({
  endpoint: 'https://your-collector.com/api/track', // 上报接口地址
  session_id: 'user-session-123', // 可选，会话ID
  debug: true, // 开启调试模式，会在控制台输出日志
  batch_size: 5, // 批量上报阈值 (默认 5)
  batch_timeout: 5000 // 批量上报超时时间 (毫秒, 默认 5000)
});

如果使用 Script Tag 方式，RLTracer 会挂载在 window 对象上。

功能特性 (Features)

1. 自动点击采集 (Click Tracking)

为元素添加 data-clk-id 属性即可自动采集点击事件。SDK 会将该 ID 作为 selector 上报。

<button data-clk-id="btn-confirm" data-tracer-data-btn-type="primary">
  确认提交
</button>

点击该按钮会上报：

• Event Name: $action (click)
• Selector: btn-confirm
• Data: { btnType: "primary" }

2. 元素曝光采集 (Impression Tracking)

为元素添加 data-exp-id 属性，SDK 会利用 IntersectionObserver 监听该元素进入视口，并自动上报曝光事件。

<div data-exp-id="banner-promo-summer" data-tracer-data-id="12345">
  夏季大促广告
</div>

元素展示时会上报：

• Event Name: $exposure
• Selector: banner-promo-summer
• Data: { id: "12345" }

3. 自定义数据合并 (Data Attributes)

在任何被采集的元素（点击或曝光）上，可以通过 data-tracer-data-* 属性附加自定义数据。 SDK 会自动提取这些数据并合并到上报的 Payload 中。

命名规则：

• data-tracer-data-key-name="value" -> { keyName: "value" }
• 驼峰命名会自动处理：data-tracer-data-user-id -> { userId: "..." }

4. 手动埋点 (Manual Tracking)

对于无法自动采集的场景，可以使用 track 方法手动上报。

tracker.track('custom_event', {
  foo: 'bar',
  score: 100
});

5. 页面浏览 (Page View)

SDK 默认会自动采集页面浏览事件 ($pageview)，支持：

• 初始加载
• History API 变更 (pushState, replaceState)
• popstate (前进/后退)

配置选项 (Configuration)

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | endpoint | string | 是 | - | 上报数据的后端接口地址 | | session_id | string | 否 | - | 会话标识 | | debug | boolean | 否 | false | 是否开启控制台日志 | | batch_size | number | 否 | 5 | 累积多少条日志触发上报 | | batch_timeout | number | 否 | 5000 | 距离上次上报多久后触发自动上报 (ms) |

数据格式 (Data Format)

上报的数据格式如下：

{
  "meta": {
    "session_id": "xxx"
  },
  "events": [
    {
      "type": "$action", // 或 $pageview, $exposure, $custom
      "name": "click",
      "time": 1712345678900,
      "seq": 1,
      "data": {
        "selector": "btn-id",
        "url": "...",
        // ...其他自定义数据
      }
    }
  ]
}