更新记录

0.1.0（2026-10-14） 下载此版本

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

平台兼容性

uni-app x(5.31)

其他

reglow-track（uni-app x 埋点采集 SDK）

基于 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 始终实时生效（服务端优先）。

安装

将 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: UniClickEvent) {
  const dataset = e.currentTarget.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 实例方法

TrackConfig

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

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

{
  "app_id": "your-app-id",
  "sdk_version": "0.1.0",
  "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"
  },
  "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": {}
    }
  ]
}

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

远程规则端点：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 }
  }
}

治理策略端侧生效规则：

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

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

平台标识

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

隐私说明

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