Web SDK 接入指南

GoWind UBA 的 Web 数据采集 SDK（@go-wind-uba/uba-sdk），用于浏览器 / Node 环境，把用户行为与风险事件上报到 Collector 服务。

适用：网页端埋点。游戏 / Unity / Godot 客户端请用 C# SDK。 源码：frontend/sdk/web/uba/。

一、能力概览

• 应用级鉴权：appId + appSecret 放请求体，无需 token。
• 批量上报：本地缓冲，定时 / 定量自动 flush。
• 高层 API：track / trackRisk / identify / setSuperProperties / flush。
• 自动补全：设备 / 会话 / 时间 / 平台信息。
• 重试与降级：指数退避，401 不重试，溢出丢弃以限制内存。
• 卸载兜底：pagehide / beforeunload 用 sendBeacon 兜底。

二、安装与构建

cd frontend/sdk/web/uba
npm install      # 安装 typescript
npm run build    # 构建 dist/

三、初始化与上报

import { UbaClient } from '@go-wind-uba/uba-sdk';

// 初始化（单例，appId/appSecret 在管理后台「应用管理」创建应用后获得）
const uba = UbaClient.init({
  appId: 'your_app_id',
  appSecret: 'your_app_secret',
  endpoint: 'http://localhost:5700', // collector 服务地址
});

// 设置公共属性（后续每条事件自动携带）
uba.setSuperProperties({ platform: 'web', version: '1.0.0' });

// 行为事件（最常用）
uba.track('click', { button: 'buy' }, {
  objectType: 'button',
  objectId: 'btn_buy',
});

// 风险事件
uba.trackRisk('abnormal_click', {
  riskType: 'device_anomaly',
  riskLevel: 'HIGH',
  riskScore: 85,
  description: '短时间内频繁点击，疑似机器操作',
});

// 登录绑定用户（后续事件自动带 userId）
uba.identify(1001);

// 关键转化节点，立即上报
uba.track('purchase', { orderId: 'ORD-001' });
await uba.flush();

四、配置选项

五、API 一览（UbaClient）

六、自动补全字段与自动采集

SDK 自动补全字段（每条事件都带）

自动采集事件（autotrack）

开启 autoTrack（默认 true）后，SDK 在 document 捕获阶段监听 click，自动上报一条名为 click 的行为事件，并填充热力图字段：

⚠️ 当前 autotrack 仅采集 click，没有 PV / pageView 自动采集、没有路由监听。页面浏览埋点需自行调用 track('page_view', ...)。

七、上报协议契约

对接 collector 统一接口 POST /uba/v1/report。

鉴权

• appId + appSecret 放请求体（非 Header），无 Authorization token。
• 鉴权失败返回 401，SDK 不重试（避免无限刷错误请求）。

请求体结构

{
  "appId": "your_app_id",
  "appSecret": "your_app_secret",
  "clientInfo": { "userAgent": "...", "referer": "..." },
  "events": [
    {
      "eventId": "uuid",
      "eventName": "click",
      "eventTime": "RFC3339",
      "deviceId": "...",
      "sessionId": "...",
      "platform": "web",
      "userId": 1001,
      "properties": { "button": "buy" },
      "behavior": { "objectType": "button", "objectId": "btn_buy" }
    }
  ]
}

响应约定

• HTTP 200 也可能含部分失败：响应体 failedCount > 0 或 errorsByType 非空时，SDK 记录 warn。
• 错误码：400 校验失败、401 鉴权失败（不重试）、500 服务端错误（重试）。
• 字段命名一律 camelCase（与后端 proto 契约对齐）。tenantId 不上报，服务端按 appId 权威覆盖。

完整事件字段全集见 后端 API 契约 · 上报服务。

八、联调与排错

# 启动本地 collector（默认监听 5700）
cd backend
go run ./app/collector/service/cmd/server/ -c ./app/collector/service/configs

1. cd frontend/sdk/web/uba && npm run build 生成 dist/。
2. 修改 test.html 里的 appId / appSecret / endpoint。
3. 浏览器打开，点击按钮触发上报，观察 Network 面板与 Console。

常见问题

九、进阶用法

公共属性（super properties）

适合放 appVersion / channel / 渠道号等每条事件都需要的字段：

uba.setSuperProperties({ appVersion: '1.2.0', channel: 'appstore' });
uba.clearSuperProperties();

计时事件（手动测时长）

const t0 = Date.now();
// ... 用户操作 ...
uba.track('level_play', { level: '1-1' }, { durationMs: Date.now() - t0 });

批量与节流调优

十、相关文档

• 产品介绍
• C# SDK 接入
• 后端 API 契约 · 上报服务
• 系统架构