帮你快速理解、总结文档立即下载
文档中心>腾讯云可观测平台>用户体验监控>接入指南>微信小程序 SDK 接入指引>API 说明

API 说明

最近更新时间：2026-09-30 17:29:02
我的收藏

本页目录：

本文详细介绍用户体验监控微信小程序 SDK 的各功能接口，帮助您更灵活、深度地使用 SDK。

初始化

推荐使用 TDEM.init(config) 初始化，返回的实例继承 core 上报 API。完整配置项见 SDK 初始化。
import TDEM from 'tdem-mp-sdk';

const tdem = TDEM.init({
  projectKey: 'YOUR_PROJECT_KEY',
  endpoint: 'https://dem.rumt-zh.com',
});

用户标识管理

// 初始化时通过 userId / uin 传入，或登录后补写
tdem.setUser('user-123');

// 登出时清除用户标识
tdem.clearUser();
中途 setUser 只更新后续录制与事件上的用户字段，不会主动新开会话；若此时不存在有效会话（冷启动、本地缓存被清），或距上次前后台切换已超过30分钟，则会随会话重建一并生效。clearUser() 清空 userId 与 uin，用于登出后解除用户维度关联。

全局标签管理

tdem.setTags({ channel: 'mp-weixin' });   // 设置/追加标签
tdem.removeTags('channel');               // 移除指定标签（支持字符串或数组）
tdem.clearTags();                         // 清空所有标签

自定义事件

tdem.track('pay_start', {
  tags: { source: 'banner' },
  properties: { amount: 99 },
});
name 须为非空字符串；
tags / properties 分别落到 data.tags 与 data.event_properties，值会被转为字符串，单个值最长1024字符。

自定义测速

// 使用计时器
tdem.startMeasure('checkout');
tdem.endMeasure('checkout');

// 或直接上报耗时（毫秒）
tdem.measure('onload', 1200);

日志上报

tdem.captureMessage('checkout retry', { level: 'warn' });

异常上报

tdem.captureException(new Error('支付失败'), {
  tags: { module: 'pay' },
});

页面管理

// 手动上报 PV
tdem.reportPageView('/pages/checkout/index', { pageTitle: '结算页' });

// 虚拟页面（弹窗、Tab 等）
tdem.setPage('/modal/confirm', { pageTitle: '确认弹窗' });
// 弹窗关闭后恢复
tdem.leavePage();
reportPageView(pageUrl?, options?)：上报一次页面浏览（event_type = page_view）。
不传 pageUrl 时取当前页面地址；
options 支持 pageTitle / referrer / navigationType / fromPage / toPage / isFirstVisit / isFirstLoad / deviceType / replayId / tags / properties。
setPage(pageUrl, options?)：声明进入一个虚拟页面，内部以 navigationType = push 上报一次 PV，后续事件归到该页面下；
pageUrl 必填且须为非空字符串，否则调用被忽略；
options 支持 pageTitle / pageGroup。
leavePage()：退出虚拟页面，恢复到真实页面地址。
MP 端已自动接管页面 onLoad / onShow 生命周期，常规路由跳转无需手动调用；仅在弹窗、Tab 切换等无路由变化的场景使用。

挣扎事件上报

tdem.trackStruggle('payment_declined', {
  severity: 'high',              // 可选：low | medium | high，默认 medium
  tags: { channel: 'checkout' },
  properties: { reason: 'risk_rejected' },
});
name 须为非空字符串且不超过 128 字符，否则本次上报被丢弃。
severity 仅接受 low / medium / high，传其他值本次上报被丢弃；对应权重分别为1/3/5。
无需也不能填写 owner 与规则元信息，这些属 SDK 实现细节，不由公开 API 接受。
上报通道与自动检测的挣扎事件一致：event_type = struggle、event_category = behavior，具体类型落在 data.event_name（此处为 custom_struggle）。详见数据上报验证中的 挣扎事件。

表单提交结果上报

tdem.reportFormSubmitResult({
  status: 'success',                 // 必填：success | fail
  eventName: 'form_submit',          // 可选：事件名
  formId: 'register-form',           // 可选：表单标识
  fieldId: 'email',                  // 可选：字段标识
  validationCode: 'E001',            // 可选：校验码
  validationMessage: '邮箱格式错误',  // 可选：校验信息（最长 256 字符）
});
status 必填，缺失时本次调用被忽略；eventName 不传时默认按 form_submit_${status} 命名。
validationMessage 超过256字符会被截断。

原始事件上报

// 直接上报 TDEMEvent 格式的事件（高级用法）
tdem.reportTDEMEvent({
  event_id: 'evt_xxx',
  event_type: 'custom',
  event_category: 'custom',
  timestamp: Date.now(),
  page_url: '/pages/index/index',
  data: { event_name: 'my_event', tags: { key: 'value' } },
});
支持传入单个事件对象或事件数组。
SDK 会统一补齐 page_url、replay_id，并把 defaultTags 合并进事件 tags。属高级用法，常规业务建议优先使用 track / measure / captureMessage / captureException。

扩展设备信息（Bean）

tdem.extendBean('customKey', 'customValue');   // 追加自定义键值到公共 Bean
const bean = tdem.getBean();                   // 读取 Bean 查询串
extendBean(key, value)：向公共 Bean 追加自定义键值，随上报请求的查询串一并带出。SDK 内部亦通过该机制写入 platform / model / vp / sr / netType / sessionId / replayId / referer 等公共字段。
getBean()：返回形如 id=xxx&uin=yyy&from=zzz 的查询串，便于本地排查上报参数。

配置修改与销毁

tdem.setConfig({ version: '1.2.3', env: 'production' });
tdem.destroy();
注意：
env 非 production 时，控制台默认筛选可能看不到数据。合法取值为 production / development / gray / pre / daily / local / test / others，传入其他值会回落到 others。

构造函数进阶项

需要接口返回码修正、trace 注入、WebSocket 监控、setData 性能阈值时，可直接 new TDEM(config) 构造，详见 SDK 初始化中的 构造函数进阶项。此时 projectKey 与 endpoint 之外，还可传 id / hostUrl / version / api / websocketHack / setDataReportConfig / enableHttp2 / eventReport（apiUrl / reportUrl / eventPath）等字段。

静默降级

基础库过低、部分 Hook 失败：只上报仍能拿到的事件，不打断宿主。
远程配置失败且无缓存：关闭回放。
存储不可用：不写缓存，失败丢弃。
采集错误不对用户展示。
未知运行时平台：初始化直接停止。
注意：
aid（设备标识）写在 storage 键 TDEM_ID，清缓存会换新 aid。
中国站