腾讯云可观测平台 SDK 初始化

本文将为您介绍如何初始化用户体验监控微信小程序 SDK。
操作步骤
1. 引入 SDK 后，创建配置对象并启动 SDK。必须在业务 Page / Component 注册之前执行，否则录制 Hook 无法覆盖已声明的页面；推荐放在 app.js / app.ts 最顶部。
import TDEM from 'tdem-mp-sdk';
﻿
const tdem = TDEM.init({
  projectKey: 'YOUR_PROJECT_KEY',       // 必填：项目标识，对应 project_key
  endpoint: 'https://dem.rumt-zh.com',  // 建议显式传入：采集服务基地址（国内站）
  sessionReplay: {
    enabled: true,
    // bundleHash: 'a1b2c3d4e5f67890', // 可选；不传则回放页可回退到该应用最新 ready 包
  },
  struggleMonitor: { enabled: true },   // 可选：挣扎事件检测
});
﻿
// 应用版本号不能随 TDEM.init 传入（该字段不被解析），
// 需初始化后补写，否则上报体 app.version 为空，版本维度聚合失效
tdem.setConfig({ version: '1.0.0' });
﻿
App({
  onLaunch() {
    // 登录完成后再补用户标识，不会拆会话，也不会丢掉已发生的录制关联
    // tdem.setUser(userId);
  },
});
﻿
export default tdem;
2. 初始化后即自动产生可检索会话、结构化录制事件、错误 / 页面性能 / 接口测速等数据。
注意：
projectKey 为必填；endpoint 建议显式传入。endpoint 填采集服务基地址即可，不要带 /api/v1/collect/... 路径，SDK 会自行拼接。该字段缺失不会中断初始化，但会静默回落到默认域名（国内站）、无任何告警，务必按项目所在地域填写。
userId 建议传入，缺失不会导致初始化失败，但会使控制台无法按用户维度聚合；可在登录后通过 tdem.setUser() 补写。
version 需通过 tdem.setConfig({ version }) 或 new TDEM({ version }) 传入，TDEM.init 不解析该字段；未生效时上报体 app.version 为空字符串，版本维度聚合失效。
TDEM.init 未传 sessionReplay 时默认关闭回放（仍要过远程配置闸门）。本地显式 sessionReplay: false 或 { enabled: false } 则不上报回放，即使远程允许。
采集失败不会 wx.showToast，也不会抛给业务。
建议在用户授权个人信息保护规则后再初始化 SDK。
切勿把真实 project key、采集凭证或生产环境地址提交进代码仓库。
上报域名
请根据项目所在地域选择对应的上报域名。不同站点的数据相互隔离，跨站填写会导致数据无法入库。
站点
上报域名
国内站
https://dem.rumt-zh.com
新加坡站
https://dem.rumt-sg.com
美国站
https://dem.rumt-us.com
接入时填写站点根地址即可，无需拼接路径，SDK 会自行拼接具体协议端点。同时需把该域名加入小程序 request 合法域名，详见 SDK 集成。
重要：
未配置 request 合法域名时，配置拉取会失败，SDK 会保守地关闭回放上报。这是默认策略，不是接入失败。
补写用户标识
初始化时可以带 userId 或 uin（同时存在时优先 userId）。登录完成后可再调用：
tdem.setUser('biz-user-id');
中途补写只更新后续录制与事件上的用户字段，不会新开会话。
上传源码包（画面回放必需）
要在会话回放页还原画面，需在 TDEM 控制台上传当前发版对应的小程序源码 zip（含 app.json、页面、自定义组件；可带 miniprogram_npm，不要带 node_modules）。
上传后状态为 compiling，成功变为 ready 并得到 bundleHash：
有录制事件 + 有 ready 回放包：会话回放页可播放。
只有录制事件、没有回放包：时间轴仍可看，画面会给出不可播放说明。
可在 sessionReplay.bundleHash 绑定本次发版；不传则回放页可回退到该应用最新 ready 包。
会话如何切分
时机
行为
冷启动、进程被回收后再进入
新 session_id。
后台间隔 > 30分钟再回到前台
新开会话。
后台间隔 ≤ 30分钟再回到前台
续上原会话。
同一存活期内的页面跳转、返回、Tab 切换、onShow / onHide
不新开。
中途 setUser
不新开。
会话标识形如 mp_ + 32位 hex，存在本地 storage（tdem_mp_session_v1）。
远程配置如何生效
启动时请求 POST {endpoint}/api/v1/config，body 为 { "project_key": "<projectKey>" }。结果写入本地，TTL 10分钟。
最终是否上报回放：
effectiveReplay =
  本地 sessionReplay.enabled
  AND 远程 enabled
  AND sample(远程 replay_sample_rate)   // 0–100；缺键视为 100
远程状态
回放
拉取成功
写入缓存，按上式决定。
失败，且有未过期缓存
用缓存。
失败，且无可用缓存
关闭回放，避免无治理全量采集。
标准事件另受远程 enabled 与 tdem_sample_rate（0–100）闸门控制。远程 enabled: false 后新启动的会话，回放上报次数为0。
完整配置项说明
以下为 TDEM.init(config) 的配置项。其中 projectKey 必填，endpoint 建议显式传入，userId（或 uin）建议传入；其余为可选配置。注意 TDEM.init 不接受 version，应用版本号需通过 new TDEM 或初始化后的 setConfig 传入，详见下文 基础配置 与 构造函数进阶项。
基础配置
projectKey 与 userId（或 uin）需按要求传入。缺少 projectKey 时上报会被 SDK 静默丢弃；endpoint 缺失不会中断初始化，但会静默回落到默认域名（国内站），跨站会导致数据无法入库，因此请务必按项目所在地域显式传入。userId 缺失不影响 SDK 运行，但会导致控制台无法按用户维度聚合。aid 由 SDK 自动生成，无需配置。
配置项
说明
projectKey
必填。控制台项目标识，对应请求体 project_key。
endpoint
建议显式传入。采集基地址，不要带 /api/v1/collect/... 路径；缺失不会中断初始化，但会静默回落到默认域名（国内站），跨站会导致数据无法入库。
userId
建议传入。业务用户标识，对应上报体的用户字段；与 uin 同时存在时优先 userId。不填不影响 SDK 运行，但控制台无法按用户维度聚合，可在登录后通过 tdem.setUser() 补写。
uin
业务用户标识，可为字符串或数字；与 userId 同时存在时优先 userId。与 userId 二者至少传入其一。
version
应用版本号，对应上报体的 app.version，用于版本对比与版本分布分析。TDEM.init 不解析该字段，传入会被忽略；请改用 new TDEM({ version }) 构造，或初始化后调用 tdem.setConfig({ version }) 补写。未生效时上报体为空字符串，版本维度聚合失效。
aid
设备标识。无需配置，SDK 自动生成 UUID 并写入本地存储键 TDEM_ID，同一设备下复用以保持稳定的设备身份。清缓存会重新生成。
debug
SDK 诊断日志，默认 false。默认关闭，不打印 config / bean；仅 true 时在控制台输出初始化摘要。
会话回放（sessionReplay，默认关闭）
配置项
说明
enabled
本地回放开关，与远程 enabled 做 AND；对象形态且未写时默认 true。
bundleHash
绑定本次发版回放包；不传则服务端 / 回放页可补最新 ready 包。
debug
回放调试日志，默认 false。只打生命周期、队列、分片和请求状态，不打 data / detail 原文。与顶层 debug 独立。
脱敏（mask）
录制事件在入 buffer / 上报前就会遮罩，默认覆盖：
密码类字段与 password 输入（password / passwd / pwd 等）
11 位手机号（字段名或自由文本）
18 位校验通过的身份证号
接入方可按字段或路径补充或放宽非敏感区，但不能关掉底线规则，也没有「全明文」开关。试图用 allow 放行 password / phone / idcard 这类底线字段会被忽略。
配置项
说明
keys
额外按字段名遮罩，如 ['token', 'secret']。
fields
按 route.field 或 glob 指定字段，如 ['pages/order/index.remark']。
allow
放宽非敏感字段的启发式扫描，如 ['nickname']。
maskFn(value, ctx)
自定义遮罩函数，ctx 含 { route, path, key, eventType }。
WXML 上给输入框加 data-tdem-mask 也会按密码处理。SDK 侧脱敏不能替代服务端隐私处理。
挣扎监控（struggleMonitor，默认关闭）
会话里的点击 / 页面浏览默认只走录制通道。需要端侧挣扎检测时打开。
配置项
说明
enabled
总开关，传入对象时默认 true。
sampleRate
采样率（0 - 1），默认1。
throttleWindowMs
同类同目标节流窗口（ms），默认3000。
ruleVersion
挣扎规则版本号，默认 '1.0.0'，写入报告体的 rule_version 字段；自定义上报可逐条覆盖。
payloadAllowlist
挣扎事件 payload 的字段白名单，默认 []。与业务侧逐次传入的 payloadAllowlist 取并集；留空时 payload 不做字段过滤。
click.deadClickWindowMs
死点击窗口（ms），默认3000。
click.rageClickWindowMs
愤怒点击窗口（ms），默认1000。
click.rageClickCount
愤怒点击次数阈值，默认5。
click.errorClickWindowMs
错误点击判定窗口（ms），默认3000。点击后窗口内出现错误事件即判定为 error_click。
当前默认检测 rage_click（同一目标短时间连点）和 dead_click（点击后窗口内无 setData / 成功请求 / 翻页）。表单、慢页、返回前进默认关闭。
performance 子配置（慢页面检测，默认关闭）：
配置项
说明
performance.enabled
默认 false。
performance.slowPageThresholdMs
慢页面判定阈值（ms），默认3000。取 LCP / FCP / 首屏时间三者最大值，超过阈值上报 slow_page。
form 子配置（表单交互异常检测，默认关闭）：
配置项
说明
form.enabled
默认 false。
form.longFocusThresholdMs
长时间聚焦阈值（ms），默认20000。超出上报 long_focus_time。
form.incompleteMinFieldRatio
未完成表单的最小已填字段比例，默认0.3。低于该比例上报 uncompleted_form。
form.zigzagMinCount
表单来回切换最低次数，默认2。达到后上报 form_zigzag。
navigation 子配置（前进后退检测，默认关闭）：
配置项
说明
navigation.enabled
默认 false。
navigation.backForwardAsStruggle
默认 true。浏览器前进 / 后退上报 back_forward 类型的挣扎事件。
custom 子配置（自定义检测器，默认关闭）：
配置项
说明
custom.enabled
默认 false。
custom.detector
自定义检测函数，签名 ({ event, tdem }) => ReportStruggleParams | ReportStruggleParams[] | null | void。构建期校验 typeof detector === 'function'，非函数静默跳过。返回值自动补齐：
type 默认 custom_struggle。
ownerType 默认 app。
ownerKey 默认当前页面地址。
detectionSource 固定 custom。
ruleVersion / payloadAllowlist 在最终上报时继承顶层配置。
标准点击（behaviorMonitor，默认关闭）
仅当还要把 tap 再报一条标准 click 事件时才需要打开；会话分析不依赖它。
配置项
说明
enabled
总开关。不传该项时默认关闭；传入 true 或对象时开启，传入对象且未写 enabled 时为 true。
trackClick
是否额外上报标准 click，默认 true。
trackForm
是否上报表单事件（form_focus / form_blur / form_change / form_submit 等），默认 true。
trackNavigation
是否在页面浏览时附带导航信息（如 navigation_type），默认 true。
注意：
不要把 behaviorMonitor.trackClick 当成必开项。会话行为已经在录制通道里；trackClick 会再写一条标准 click，可能导致点击在分析里重复。
弱网与本地缓存
上报失败或无网时，未成功的录制段写入本地（tdem_mp_replay_buffer_v1）。回到前台或 wx.onNetworkStatusChange 发现联网后，按 segment_id 顺序补发，成功则删除。
项
默认
内存冲洗
满500条、满3MB，或20s 定时 / 切后台强制 flush。
持久化上限
2MB 或500条，先丢最旧。
存储 API 不可用
跳过缓存，尽力即时上报；失败丢弃，不抛给业务。
构造函数进阶项（new TDEM）
需要接口返回码修正、trace 注入、WebSocket 监控、setData 性能阈值时，可直接构造：
import TDEM from 'tdem-mp-sdk';
﻿
const tdem = new TDEM({
  projectKey: 'YOUR_PROJECT_KEY',
  endpoint: 'https://dem.rumt-zh.com',
  sessionReplay: { enabled: true },
  version: '1.2.3',
  api: {
    retCodeHandler(data, url) {
      try { data = JSON.parse(data); } catch (_e) {}
      return { isErr: data?.body?.code !== 200, code: String(data?.body?.code ?? '') };
    },
    injectTraceHeader: 'traceparent',
    injectTraceUrls: [/api\\.example\\.com/],
  },
  websocketHack: true,
  setDataReportConfig: {
    disabled: false,
    timeThreshold: 30,
    withDataPaths: true,
  },
  enableHttp2: false,
});
配置项
说明
api.retCodeHandler
(data, url, xhr) => { isErr, code }，修正业务返回码。
api.injectTraceHeader
'traceparent' | 'sw8' | 'b3' | 'sentry-trace'。
api.injectTraceUrls / injectTraceIgnoreUrls
注入白 / 黑名单，元素为 string 或 RegExp。
websocketHack
默认 false。为 true 时监控 WebSocket 错误。
setDataReportConfig
性能通道的 setData 耗时上报；与录制通道的 setData 事件不是一回事。
enableHttp2
上报请求是否带微信 enableHttp2。
eventReport.apiUrl / reportUrl / eventPath
标准事件地址；默认拼 /api/v1/collect/events。
注意：
页面性能（启动、注入、首屏、路由）依赖基础库 Performance API（建议 > 2.11.0）；不可用时静默跳过。setData 更新性能统计依赖 setUpdatePerformanceListener（建议 > 2.12.0）。
﻿

配置项	说明
`projectKey`	必填。控制台项目标识，对应请求体 `project_key`。
`endpoint`	建议显式传入。采集基地址，不要带 `/api/v1/collect/...` 路径；缺失不会中断初始化，但会静默回落到默认域名（国内站），跨站会导致数据无法入库。
`userId`	建议传入。业务用户标识，对应上报体的用户字段；与 `uin` 同时存在时优先 `userId`。不填不影响 SDK 运行，但控制台无法按用户维度聚合，可在登录后通过 `tdem.setUser()` 补写。
`uin`	业务用户标识，可为字符串或数字；与 `userId` 同时存在时优先 `userId`。与 `userId` 二者至少传入其一。
`version`	应用版本号，对应上报体的 `app.version`，用于版本对比与版本分布分析。`TDEM.init` 不解析该字段，传入会被忽略；请改用 `new TDEM({ version })` 构造，或初始化后调用 `tdem.setConfig({ version })` 补写。未生效时上报体为空字符串，版本维度聚合失效。
`aid`	设备标识。无需配置，SDK 自动生成 UUID 并写入本地存储键 `TDEM_ID`，同一设备下复用以保持稳定的设备身份。清缓存会重新生成。
`debug`	SDK 诊断日志，默认 `false`。默认关闭，不打印 config / bean；仅 `true` 时在控制台输出初始化摘要。

配置项	说明
`enabled`	本地回放开关，与远程 `enabled` 做 AND；对象形态且未写时默认 `true`。
`bundleHash`	绑定本次发版回放包；不传则服务端 / 回放页可补最新 ready 包。
`debug`	回放调试日志，默认 `false`。只打生命周期、队列、分片和请求状态，不打 data / detail 原文。与顶层 `debug` 独立。

配置项	说明
`keys`	额外按字段名遮罩，如 `['token', 'secret']`。
`fields`	按 `route.field` 或 glob 指定字段，如 `['pages/order/index.remark']`。
`allow`	放宽非敏感字段的启发式扫描，如 `['nickname']`。
`maskFn(value, ctx)`	自定义遮罩函数，`ctx` 含 `{ route, path, key, eventType }`。

配置项	说明
`enabled`	总开关，传入对象时默认 `true`。
`sampleRate`	采样率（0 - 1），默认`1`。
`throttleWindowMs`	同类同目标节流窗口（ms），默认3000。
`ruleVersion`	挣扎规则版本号，默认 `'1.0.0'`，写入报告体的 `rule_version` 字段；自定义上报可逐条覆盖。
`payloadAllowlist`	挣扎事件 `payload` 的字段白名单，默认 `[]`。与业务侧逐次传入的 `payloadAllowlist` 取并集；留空时 payload 不做字段过滤。
`click.deadClickWindowMs`	死点击窗口（ms），默认3000。
`click.rageClickWindowMs`	愤怒点击窗口（ms），默认1000。
`click.rageClickCount`	愤怒点击次数阈值，默认5。
`click.errorClickWindowMs`	错误点击判定窗口（ms），默认3000。点击后窗口内出现错误事件即判定为 `error_click`。

配置项	说明
`performance.enabled`	默认 `false`。
`performance.slowPageThresholdMs`	慢页面判定阈值（ms），默认3000。取 LCP / FCP / 首屏时间三者最大值，超过阈值上报 `slow_page`。

SDK 初始化

本页目录：

操作步骤

上报域名

补写用户标识

上传源码包（画面回放必需）

会话如何切分

远程配置如何生效

完整配置项说明

基础配置

会话回放（`sessionReplay`，默认关闭）

脱敏（`mask`）

挣扎监控（`struggleMonitor`，默认关闭）

标准点击（`behaviorMonitor`，默认关闭）

弱网与本地缓存

构造函数进阶项（`new TDEM`）

站点	上报域名
国内站	`https://dem.rumt-zh.com`
新加坡站	`https://dem.rumt-sg.com`
美国站	`https://dem.rumt-us.com`

时机	行为
冷启动、进程被回收后再进入	新 `session_id`。
后台间隔 > 30分钟再回到前台	新开会话。
后台间隔 ≤ 30分钟再回到前台	续上原会话。
同一存活期内的页面跳转、返回、Tab 切换、`onShow` / `onHide`	不新开。
中途 `setUser`	不新开。

远程状态	回放
拉取成功	写入缓存，按上式决定。
失败，且有未过期缓存	用缓存。
失败，且无可用缓存	关闭回放，避免无治理全量采集。

配置项	说明
`form.enabled`	默认 `false`。
`form.longFocusThresholdMs`	长时间聚焦阈值（ms），默认20000。超出上报 `long_focus_time`。
`form.incompleteMinFieldRatio`	未完成表单的最小已填字段比例，默认0.3。低于该比例上报 `uncompleted_form`。
`form.zigzagMinCount`	表单来回切换最低次数，默认2。达到后上报 `form_zigzag`。

配置项	说明
`navigation.enabled`	默认 `false`。
`navigation.backForwardAsStruggle`	默认 `true`。浏览器前进 / 后退上报 `back_forward` 类型的挣扎事件。

配置项	说明
`custom.enabled`	默认 `false`。
`custom.detector`	自定义检测函数，签名 `({ event, tdem }) => ReportStruggleParams \| ReportStruggleParams[] \| null \| void`。构建期校验 `typeof detector === 'function'`，非函数静默跳过。返回值自动补齐： `type` 默认 `custom_struggle`。 `ownerType` 默认 `app`。 `ownerKey` 默认当前页面地址。 `detectionSource` 固定 `custom`。 `ruleVersion` / `payloadAllowlist` 在最终上报时继承顶层配置。

项	默认
内存冲洗	满500条、满3MB，或20s 定时 / 切后台强制 flush。
持久化上限	2MB 或500条，先丢最旧。
存储 API 不可用	跳过缓存，尽力即时上报；失败丢弃，不抛给业务。

配置项	说明
`api.retCodeHandler`	`(data, url, xhr) => { isErr, code }`，修正业务返回码。
`api.injectTraceHeader`	`'traceparent' \| 'sw8' \| 'b3' \| 'sentry-trace'`。
`api.injectTraceUrls` / `injectTraceIgnoreUrls`	注入白 / 黑名单，元素为 string 或 RegExp。
`websocketHack`	默认 `false`。为 `true` 时监控 WebSocket 错误。
`setDataReportConfig`	性能通道的 setData 耗时上报；与录制通道的 `setData` 事件不是一回事。
`enableHttp2`	上报请求是否带微信 `enableHttp2`。
`eventReport.apiUrl` / `reportUrl` / `eventPath`	标准事件地址；默认拼 `/api/v1/collect/events`。