Track 数据埋点

基于 uni-app x 的跨端埋点采集 SDK，支持 App / H5 / 微信小程序，自动采集标准事件、会话管理、批量可靠上报与远程埋点规则

当前版本：v0.2.1（协议版本 sdk_version 0.1.1）。

基于 uni-app x / UTS 实现的跨端埋点采集 SDK，支持 App（Android / iOS / HarmonyOS）、H5、微信小程序 三端统一接入。采集协议与 Web 版 @reglow/track 完全同源，同一后端可直接复用。

特性

协议同源：上报地址 POST {dsnHost}/analytics/collect、远程规则 GET {dsnHost}/rules，请求体字段与 Web 版 @reglow/track 严格一致。
标准事件自动采集：$app_start、$session_start、$page_view、$page_leave、$click、$exposure、$scroll（$ 前缀为自动事件）。
自动会话：30 分钟无事件自动换新会话并补发 $session_start，会话 ID / 设备 ID 本地持久化。
可靠上报：内存 + 持久化缓冲队列（上限 500 丢最旧），批量（默认 20）或定时（默认 5s）上报，失败指数退避重试，离线保留。
平台自动判定：H5 → h5、微信小程序 → mp-weixin、App → app。
隐私友好：optOut() 持久化标记后不再采集；不采集输入框内容。
远程埋点规则：syncRules() 拉取可视化圈选规则并按页面缓存。
治理配置（P4-B）：remoteGov 开启后初始化自动拉取 GET {dsnHost}/gov/config，端侧生效 collect 停发 / 默认采样率 / 隐私开关；采集响应 next_config.gov 始终实时生效（服务端优先）。
服务端动态配置（0.2.1）：采集响应 next_config 的顶层 sample_rate / flush_interval / batch_size 实时生效；采样优先级 gov.sample_rate → 顶层 sample_rate → 本地 sampleRate。
多租户与渠道（0.2.1）：tenantId 显式配置时采集请求体携带 tenant_id（SaaS 多租户轨，未配置则不发送，服务端缺省 1）；channel 写入 common.channel 用于渠道分布。
业务事件助手（0.2.1）：trackSearch（biz.search）、trackPreference（biz.favorite / like / share / rate / comment）、trackClickPoint（带坐标的 $click，用于坐标级热点图）。

安装

将 uni_modules/reglow-track 目录复制到项目的 uni_modules/ 下即可（HBuilderX 插件市场安装亦同）。

快速接入

1. 创建实例

在 App.uvue（或首个页面的 onLaunch / onLoad）中创建并初始化：

import { createTrack } from '@/uni_modules/reglow-track/utssdk/index.uts'

const track = createTrack({
  appId: 'your-app-id',
  // 上报地址前缀，默认 '/api/v1/analytics'
  // 上报地址 = dsnHost + '/analytics/collect'，规则地址 = dsnHost + '/rules'
  dsnHost: '/api/v1/analytics',
  // 可选：采样率 0~1（默认 1，仅作用于自定义事件）、flushInterval、batchSize、
  // autoPageView、pageVersion、remoteRules、remoteGov（治理配置自动拉取）等
  debug: true
})

创建时会自动上报 $app_start；若是新会话（首次或超时后），自动上报 $session_start。

2. 页面 onShow 上报 `$page_view`

在每个页面的 onShow 中调用：

onShow(() => {
  track.pageView('pages/index/index') // 传入页面路由作为 page_key
})

开启 autoPageView（默认 true）时，从上一页面切换过来会先自动补发上一页的 $page_leave（携带 stay_ms 停留时长）。不传参数时自动取当前页面栈路由：

onShow(() => {
  track.pageView()
})

页面隐藏时建议兜底上报（H5 使用 sendBeacon，其余平台走普通上报）：

onHide(() => {
  track.flushBeacon()
})

3. 业务自定义事件

track.track('demo.click', {
  source: 'home',
  count: 1
} as UTSJSONObject)

4. 点击 / 曝光助手与 `data-track-id` 约定

遵循 data-track-id / data-track-type 约定，点击与曝光事件自动携带 elem_id / elem_type：

// 点击
track.trackClick('btn-buy', 'button', {
  product_id: '1001'
} as UTSJSONObject)

// 曝光
track.trackExposure('card-sku-1', 'card', {
  index: 1
} as UTSJSONObject)

模板侧建议：

<view data-track-id="btn-buy" data-track-type="button" @click="onBuy">
  <text>购买</text>
</view>

function onBuy(e: UniPointerEvent) {
  // currentTarget 可空，需先判空
  const target = e.currentTarget
  if (target == null) {
    return
  }
  const dataset = target.dataset
  const trackId = dataset['trackId']
  const trackType = dataset['trackType']
  track.trackClick(
    typeof trackId == 'string' ? trackId : '',
    typeof trackType == 'string' ? trackType : 'view'
  )
}

API

`createTrack(config: TrackConfig): Track`

创建并初始化采集器。返回 Track 实例。

`Track` 实例方法

方法	说明
`track(code: string, props?: UTSJSONObject): Track`	上报自定义事件；`code` 以 `$` 开头时按自动事件处理
`trackClick(elemId, elemType?, props?): Track`	`$click` 助手，自动填充 `elem_id` / `elem_type`
`trackExposure(elemId, elemType?, props?): Track`	`$exposure` 助手，自动填充 `elem_id` / `elem_type`
`trackSearch(query, opts?): Track`	`biz.search` 助手，`opts`：`is_zero_result` / `clicked_rank` / `converted`；空串不上报
`trackPreference(action, opts?): Track`	`biz.favorite` / `biz.like` / `biz.share` / `biz.rate` / `biz.comment`；`opts`：`target_type` / `target_id` / `score`
`trackClickPoint(elemId, elemType, x, y, props?): Track`	带坐标的 `$click`（相对页面左上角 px），用于坐标级热点图
`pageView(pageKey?: string): Track`	上报 `$page_view`，切换页面时自动补发上一页 `$page_leave`
`identify(userId: string): Track`	登录后绑定用户 ID，后续事件携带 `user_id`
`setSuperProps(obj: UTSJSONObject): Track`	设置全局超级属性，合并进每条事件的 `props`
`flush(): void`	手动触发一次上报
`flushBeacon(): void`	页面隐藏 / 卸载场景兜底上报（H5 使用 `sendBeacon`）
`optOut(): Track`	退出采集：持久化标记并清空队列，后续不再采集
`optIn(): Track`	恢复采集
`syncRules(pageKey?: string): void`	手动拉取远程埋点规则并按页面缓存（不依赖 `remoteRules` 开关）
`syncGov(): Promise<void>`	手动拉取治理配置（远程策略）并应用（不依赖 `remoteGov` 开关，失败静默）
`getGov(): GovConfig`	查询当前治理配置（只读快照）
`getDeviceId(): string`	访客唯一 ID
`getSessionId(): string`	当前会话 ID
`getUserId(): string \| null`	当前登录用户 ID
`getPlatform(): string`	平台标识（`h5` / `mp-weixin` / `app`）
`getRules(): Array<RemoteRule>`	已缓存的远程埋点规则

`TrackConfig`

字段	类型	默认值	说明
`appId`	`string`	必填	应用 ID，对应协议 `app_id`
`dsnHost`	`string`	`/api/v1/analytics`	上报 / 规则地址前缀
`platform`	`string`	自动判定	`h5` / `mp-weixin` / `app`
`appVersion`	`string`	`1.0.0`	应用版本，对应协议 `common.app_version`
`tenantId`	`number`	`0`	租户 ID（SaaS 多租户轨）；大于 0 时采集请求体携带 `tenant_id`，不传则由服务端缺省 1
`channel`	`string`	`''`	渠道标识，写入 `common.channel`（渠道分布）
`sampleRate`	`number`	`1`	采样率 0~1，仅作用于自定义事件
`flushInterval`	`number`	`5000`	定时上报间隔（ms）
`batchSize`	`number`	`20`	批量阈值，达到立即上报
`maxQueueSize`	`number`	`500`	队列上限，超限丢最旧
`sessionTimeout`	`number`	`30 * 60 * 1000`	会话超时（ms）
`autoPageView`	`boolean`	`true`	页面浏览自动补发上一页 `$page_leave`
`pageVersion`	`string`	`''`	页面版本，附加到事件的 `props.page_version`
`remoteRules`	`boolean`	`false`	初始化 / `pageView` 时自动拉取远程规则
`remoteGov`	`boolean`	`false`	初始化时自动拉取治理配置（collect 停发 / 采样 / 隐私开关）；采集响应 `next_config.gov` 始终生效
`debug`	`boolean`	`false`	是否输出 debug 日志

采集协议（与 Web 版 `@reglow/track` 一致）

上报端点：POST {dsnHost}/analytics/collect

{
  "app_id": "your-app-id",
  "sdk_version": "0.1.1",
  "platform": "h5",
  "common": {
    "device_id": "d_xxx",
    "session_id": "s_xxx",
    "user_id": null,
    "app_version": "1.0.0",
    "platform": "h5",
    "is_first_visit": true,
    "brand": "HUAWEI",
    "model": "P50",
    "os": "HarmonyOS 4.0",
    "language": "zh_CN",
    "screen": "390x844",
    "network_type": "wifi",
    "channel": ""
  },
  "events": [
    {
      "event_uid": "d_xxx-1728000000000-1",
      "code": "$page_view",
      "type": "auto",
      "ts": 1728000000000,
      "page_key": "pages/index/index",
      "elem_id": null,
      "elem_type": null,
      "user_id": null,
      "device_id": "d_xxx",
      "session_id": "s_xxx",
      "props": {}
    }
  ]
}

标准事件（$ 前缀为自动事件）：

事件	触发时机
`$app_start`	创建 `Track` 时
`$session_start`	新会话开始（首次 / 30 分钟超时后）
`$page_view`	`pageView()` 调用
`$page_leave`	切换页面时自动补发，携带 `stay_ms`
`$click`	`trackClick()` / 业务调用
`$exposure`	`trackExposure()` / 业务调用
`$scroll`	业务调用（如页面滚动事件中）

远程规则端点：GET {dsnHost}/rules?app_id=&page_key=

{
  "code": 0,
  "success": true,
  "data": [
    {
      "selector": "#btn-buy",
      "elem_id": "btn-buy",
      "elem_type": "button",
      "events": "click,exposure",
      "page_key": "pages/index/index"
    }
  ]
}

治理配置端点（P4-B）：GET {dsnHost}/gov/config?app_id=

remoteGov 开启时初始化自动拉取；syncGov() 可手动拉取。黑名单明细不下发：

{
  "code": 0,
  "success": true,
  "data": {
    "collect": true,
    "sample_rate": 1,
    "switches": { "text_excerpt": true, "ip_collect": true, "snapshot": true },
    "retention": { "event_days": 90, "agg_months": 24 }
  }
}

治理策略端侧生效规则：

策略	生效逻辑
`collect: false`	停发：`track()` 等入口事件直接丢弃不入队，已入队队列清空
`sample_rate`	采样率仅作用于自定义事件（非 `$` 前缀）；服务端未下发（-1）时回退本地配置 `sampleRate`
`switches.text_excerpt: false`	剥离事件 `props.text`（禁文本摘录）
`switches.snapshot: false`	剥离事件 `props.page_version`（禁页面快照）
`switches.ip_collect`	信息性字段（IP 由服务端采集侧决定），客户端不消费
`retention`	信息性字段（保留策略由服务端清理执行），客户端不消费

无论 remoteGov 是否开启，每次采集上报的响应 data.next_config.gov（同结构）都会实时合并生效，服务端优先。

next_config 顶层还支持 sample_rate / flush_interval / batch_size 动态调整（0.2.1）：采样优先级为 gov.sample_rate → 顶层 sample_rate → 本地 sampleRate；响应格式不符或字段缺失时静默保留现有配置。

采集请求体：显式配置 tenantId（> 0）时会携带顶层 tenant_id，用于 SaaS 多租户轨；单租户轨不发送，由服务端缺省为 1。

端差异：治理配置拉取走 uni.request（GET，超时 10s），三端（App / H5 / 微信小程序）一致；拉取失败或响应格式不符时静默保留现有策略，不影响采集。

平台标识

平台	取值
H5	`h5`
微信小程序	`mp-weixin`
App（Android / iOS / HarmonyOS）	`app`

未在 TrackConfig.platform 中指定时自动判定。

隐私说明

optOut() 会持久化退出标记并清空队列，此后不再采集任何事件；optIn() 恢复。
SDK 不采集输入框内容等敏感信息；data-track-id 之外的自动文本截取策略由业务侧控制。

CsSdk 智能客服

智能客服 SDK（带界面版）：提供 <re-cs-chat /> 开箱即用组件与无 UI 核心层 createCsSdk，支持 SSE 流式对话、转人工、满意度评价与 WebSocket 坐席推送

更新日志

ReView 移动端组件库版本更新记录

内容锚点

特性
安装
快速接入
API
采集协议（与 Web 版 @reglow/track 一致）
平台标识
隐私说明