tdem-web-sdk

v1.0.12

Published

17 days ago

tdem sdk for web application

0High
0Medium
0Low

libinnlli

tdem-web-sdk

TDEM Web SDK 用于浏览器页面的体验采集，包括脚本错误、页面性能、Web Vitals，以及按需打开的接口、静态资源、点击、控制台、会话回放。

当前只支持 npm 接入。

安装

npm install tdem-web-sdk

快速开始

在页面脚本里尽早创建实例。id 使用控制台里的项目 ID，version 使用业务版本号。

import TDEM from 'tdem-web-sdk';

const tdem = new TDEM({
  id: 'your-project-id',
  url: 'https://dem.rumt-zh.com',
  version: '1.2.3',
  userId: 'user-123',
});

url 是采集域名，不要带 /api/v1/...。省略时使用 https://dem.rumt-zh.com。

省略 version 时，上报里的应用版本是字符串 1.0.0。

什么时候会有数据

创建实例后，SDK 会先请求 POST {url}/api/v1/config。控制台未打开采集、采样未命中，或这次请求失败且本地没有可用缓存时，后续插件不会启动，事件也不会发出。控制台会出现：

[TDEM] SDK disabled by remote config, skip initialization

采集打开后，事件发送到 POST {url}/api/v1/collect/events。

打开页面后在 Network 里确认两件事：config 返回的 enabled 为真，以及随后有 collect/events 请求。

默认会采集什么

下面这些能力在创建实例后就会打开。某一项传 false 可以关掉。

| 配置 | 默认 | 采集内容 | | --- | --- | --- | | onError | 开 | JS 错误、未处理的 Promise rejection | | pagePerformance | 开 | 页面加载性能 | | webVitals | 开 | Web Vitals | | lagMonitor | 开 | 主线程卡顿。依赖 Chromium 的 long-animation-frame，不支持时跳过 | | blankScreen | 开 | 白屏。一次连续白屏只上报一次 | | memoryMonitor | 开 | JS 堆。仅在浏览器提供 performance.memory 时运行 |

默认关闭，需要时再打开：

| 配置 | 打开方式 | | --- | --- | | spa | true 后监听路由变化并上报 PV | | api | true 或对象。同时采集普通 HTTP 和 SSE | | assets | 静态资源 | | click | 点击 | | console | 控制台日志 | | bridge | JSBridge | | websocket | WebSocket | | sessionReplay | 会话回放 | | struggleMonitor | 挣扎行为，例如愤怒点击、无效点击 | | reportRetry | 上报失败后的重试 |

初始化配置

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | id | string | - | 项目 ID，对应请求里的 project_key | | url | string | https://dem.rumt-zh.com | 采集域名 | | version | string \| number | 上报为 1.0.0 | 应用版本 | | userId | string | - | 业务用户 | | env | string | production | 见下方环境枚举。无法识别的值按 others 上报 | | defaultTags | Record<string, string> | {} | 合并进每条事件的标签 | | debug | boolean | false | 输出 SDK 诊断日志 | | delay | number | 1000 | 事件合并上报的等待时间，单位毫秒 | | repeat | number | 60 | 相同事件的重复上限 | | reportImmediately | boolean | true | 是否立即上报 | | beforeReport | Function | - | 返回 false 时丢弃这条事件 | | beforeRequest | Function | - | 请求发出前 | | afterRequest | Function | - | 请求完成后 |

lagMonitor、blankScreen、memoryMonitor 传对象时只覆盖写明的字段。卡顿默认超过 2000ms 上报，达到 5000ms 再记为无响应。白屏默认采样后按约 70% 空点判断，并在 2 秒后复检。

接口与 SSE

api: false 时，普通 HTTP 和 SSE 都不采集。api: true 或传入对象时，两者一起采集。SSE 覆盖 EventSource，以及响应 Content-Type 为 text/event-stream 的 fetch / XHR。同一次 SSE 连接只上报 sse_call，不会再报 api_call。SSE 不采集消息正文。

卡流阈值默认 60000ms：

new TDEM({
  id: 'your-project-id',
  url: 'https://dem.rumt-zh.com',
  version: '1.2.3',
  api: {
    sseStallThresholdMs: 60000,
    apiDetail: false,
  },
});

apiDetail: true 时会上报请求体，内容会被截断。需要按业务码判断失败时，提供 retCodeHandler，返回 { isErr, code }。

会话回放

sessionReplay 省略或为 false 时不录制。设为 true 或对象后，还要同时满足控制台的采集开关和回放采样。

| 字段 | 默认 | 说明 | | --- | --- | --- | | sessionSampleRate | 0.1 | 体验流采样，范围 0 到 1。控制台的 replay_sample_rate（0 到 100）会覆盖它 | | errorTraceback | true | 未抽中体验流时，是否允许在发生错误后补报这段回放 | | errorSampleRate | 1 | 错误回溯的命中率，仅 errorTraceback: true 时有效 |

| 用法 | 配置 | | --- | --- | | 只在出错时回放 | sessionSampleRate: 0，保持 errorTraceback: true | | 体验流和错误回放都要 | sessionSampleRate 大于 0，保持 errorTraceback: true | | 只看抽中的体验流 | errorTraceback: false |

未抽中体验流且开了错误回溯时，SDK 先把录制放在内存里。这段访问没有错误，就不会因为页面关闭把回放发出去。

隐私默认遮罩页面文本和输入内容，密码框不录入。可以用这些标记补充：

.tdem-mask 或 data-tdem-mask：遮罩
.tdem-block 或 data-tdem-block：整块不录

也可以在 sessionReplay.privacy 里改 maskAllText、maskAllInputs，或追加 mask / block 选择器。

实例方法

tdem.track('button_click', {
  tags: { button_id: 'submit' },
  properties: { page: '/checkout' },
});

tdem.trackStruggle('repeat_submit', {
  severity: 'high',
  tags: { step: 'pay' },
});

tdem.measure('api_latency', 320, {
  tags: { api: '/user/info' },
});
tdem.startMeasure('render');
tdem.endMeasure('render');

tdem.captureMessage('用户完成注册', {
  level: 'info',
  tags: { step: 'register' },
});

try {
  riskyOperation();
} catch (error) {
  tdem.captureException(error, {
    tags: { module: 'payment' },
  });
}

tdem.setUser('user-456');
tdem.clearUser();

tdem.setTags({ role: 'admin' });
tdem.removeTags(['role']);
tdem.clearTags();

tdem.reportPageView('/checkout', { pageTitle: '结算页' });
tdem.setPage('/modal/confirm', { pageTitle: '确认弹窗' });
tdem.leavePage();

tdem.setConfig({ env: 'gray', version: '1.2.4' });
tdem.destroy();

trackStruggle 的 severity 为 low、medium 或 high，默认 medium。captureMessage 的 level 为 info、warn 或 error。endMeasure 找不到对应的 startMeasure 时会忽略。

协议说明

远程配置（Web 规则化采样权威）：POST {url}/api/v1/sample-config（snake_case event / replay.experience_sample_rate）
旧配置（非 Web / 兼容）：POST {url}/api/v1/config
事件上报：POST {url}/api/v1/collect/events

所有事件统一走 TDEM Event 协议，请求体结构：

{
  "protocol_version": 2,
  "project_key": "your-project-id",
  "sdk": { "name": "tdem-web-sdk", "version": "x.x.x" },
  "app": { "version": "1.0.0" },
  "context": {
    "session_id": "...",
    "user_id": "...",
    "platform": "web",
    "user_agent": "...",
    "screen_resolution": "1920x1080",
    "language": "zh-CN"
  },
  "events": [
    {
      "event_id": "evt_xxx",
      "event_type": "js_error",
      "event_category": "error",
      "timestamp": 1713800000000,
      "page_url": "https://example.com/page",
      "data": { ... }
    }
  ]
}

环境枚举

TDEM.environment.production
TDEM.environment.development
TDEM.environment.gray
TDEM.environment.pre
TDEM.environment.daily
TDEM.environment.local
TDEM.environment.test
TDEM.environment.others

看不到数据时

确认 id 是控制台项目 ID，url 是采集域名。
确认控制台已打开采集，并且采样率不是 0。
看 Network 里的 /api/v1/config。失败且没有本地缓存时，这次访问不会上报。
把 debug 设为 true，查看初始化日志。
非 production 环境可能被控制台的默认筛选挡住，换环境条件再查。

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

tdem-web-sdk

安装

快速开始

什么时候会有数据

默认会采集什么

初始化配置

接口与 SSE

会话回放

实例方法

协议说明

环境枚举

看不到数据时

License