帮你快速理解、总结文档立即下载

SDK 初始化

最近更新时间:2026-11-03 14:25:03
本文档已由 AI 辅助审校
我的收藏
本文将为您介绍如何初始化用户体验监控 Android SDK。

操作步骤

1. 在自定义 Application 的 onCreate 中创建配置对象并初始化。除 env、logLevel 外的配置项均为必填:id / url 缺失会导致初始化被直接跳过;userId / deviceId / version 缺失会导致控制台的用户、设备、版本维度无法聚合。
Kotlin
Java
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()

val config = TDEMConfiguration.Builder(this)
.id("your-project-key") // 必填:项目标识,对应 project_key
.url("https://dem.rumt-zh.com") // 必填:上报服务端基地址(国内站)
.userId("user-123") // 必填:业务用户标识(用户维度聚合)
.deviceId("deviceid-123") // 必填:设备标识(设备异常率统计)
.version("1.0.0") // 必填:应用版本号(版本对比与分布)
.env("production") // 可选:运行环境,默认 production
.logLevel(TDEM.LEVEL_DEBUG) // 可选:日志级别,默认 WARN
.build()
TDEM.init(config)
}
}
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();

TDEMConfiguration config = new TDEMConfiguration.Builder(this)
.id("your-project-key") // 必填:项目标识,对应 project_key
.url("https://dem.rumt-zh.com") // 必填:上报服务端基地址(国内站)
.userId("user-123") // 必填:业务用户标识(用户维度聚合)
.deviceId("deviceid-123") // 必填:设备标识(设备异常率统计)
.version("1.0.0") // 必填:应用版本号(版本对比与分布)
.env("production") // 可选:运行环境,默认 production
.logLevel(TDEM.LEVEL_DEBUG) // 可选:日志级别,默认 WARN
.build();
TDEM.init(config);
}
}
2. 初始化后即可自动采集崩溃、ANR、卡顿、启动、设备信息等数据,无需额外打点。用户行为(Behavior)默认关闭,需显式开启。
注意:
id 与 url 为必填,二者任一为空时 TDEM.init 会跳过初始化并返回空壳实例,不会上报任何数据。userId、deviceId、version 同为必填,缺失不会导致初始化失败,但会使控制台的用户、设备、版本维度无法聚合,务必一并传入。
SDK 初始化前会先请求 POST {url}/api/v1/config 拉取远程配置,仅在远程返回启用时才挂载各监控插件;拉取失败时沿用本地缓存,无缓存则偏保守(不上报)。
建议在用户授权个人信息保护规则后再初始化 SDK。
切勿把真实 project key、采集凭证或生产环境地址提交进代码仓库。

上报域名

请根据项目所在地域选择对应的上报域名。不同站点的数据相互隔离,跨站填写会导致数据无法入库。
站点
上报域名
国内站
https://dem.rumt-zh.com
新加坡站
https://dem.rumt-sg.com
美国站
https://dem.rumt-us.com
接入时填写站点根地址即可,无需拼接路径,SDK 会自行拼接具体协议端点。

完整配置项说明

插桩开关(tdem-plugin 配置块,编译期生效)

tdem {} 是 Gradle 插件 tdem-plugin 的配置块(插件坐标 com.tencent.tdemplugin:tdem-plugin),在模块级 build.gradle 中声明。它不是独立的功能模块,也不属于 TDEMConfiguration,而是下文各功能配置的前置开关:在编译期由插件读取,对 Class 字节码做插桩,决定「哪些监控走自动埋点」。因此它与各 xxxPluginConfig 是两层开关:本配置块决定编译期是否插桩,各功能小节里的 xxxPluginConfig 决定运行期是否采集,两层都开启才会产生数据。引入方式见 Android SDK 集成指引-应用插桩插件。
下列 5 个插桩开关与下文的功能小节相互对应,它们不新增能力,只是同一能力在编译期的前置条件:
能力
编译期开关(tdem {})
对应的运行期开关
OkHttp 请求
instrumentOkHttp
httpPluginConfig.okHttpEnabled
HttpURLConnection 请求
instrumentHUC
httpPluginConfig.urlConnectionEnabled
SSE 长连接
instrumentSSE
(无,sseEnabled 不参与采集判定)
启动(Application / Activity)
instrumentLaunch
launchPluginConfig.enabled
Compose Navigation 页面流转
instrumentComposeNavigation
behaviorPluginConfig.enabled
下表为 tdem {} 的全部配置项及默认值:
配置项
说明
enabled
插件总开关,默认 true。置为 false 时跳过全部插桩,编译期日志输出 tdem.enabled = false, skipping instrumentation。
instrumentOkHttp
OkHttp3 请求自动监控,默认 true。关闭后 OkHttp 请求不再自动产生 api_call / api_error。
instrumentHUC
HttpURLConnection 请求自动监控,默认 true。
instrumentSSE
SSE 长连接自动监控,默认 true。
instrumentLaunch
Application / Activity 启动埋点,默认 true。
instrumentComposeNavigation
Compose Navigation 页面流转插桩,默认 false。开启前须先引入 com.tencent.tdem:tdem-behavior-compose(版本与 tdem 一致),否则运行期 NoClassDefFoundError。该能力仅在行为监控开启时产生 page_view。
exclude
不参与插桩的类名列表,默认空。用于排除与 SDK 冲突或无需采集的类。
logLevel
插件自身日志级别,可选 NONE / SUMMARY / NORMAL / VERBOSE,默认 NORMAL。
appId
符号表上传使用的应用 ID,默认空。
mappingFile
符号表上传使用的 mapping 文件路径,默认空。
nativeDirectory
Native 符号所在目录,默认空。
symbolCli
符号表上传命令行工具名,默认 tdem-symbols。
uploadSymbols
构建后是否自动上传符号表,默认 false。
instrumentComposeNavigation 与 Kotlin 编译器插件的 tdemKotlinCompiler 配置块互不相干:前者负责 Compose Navigation 的页面流转,后者负责给 @Composable 函数注入组件标签。
instrumentSSE 只覆盖 SSE 长连接:关闭后仅 SSE 不再插桩,不影响 OkHttp / HttpURLConnection。
enabled = false 时插件整体跳过插桩,日志输出 [TDEMPlugin] tdem.enabled = false, skipping instrumentation。

基础配置

下表中 id / url / userId / deviceId / version 为必填,其余为可选(均有默认值或可不配置)。id 与 url 由 SDK 强制校验,缺失会直接跳过初始化;userId、deviceId、version 缺失虽不影响 SDK 运行,但会导致控制台对应的用户 / 设备 / 版本维度无法聚合。
配置项
说明
id
必填。项目标识,对应请求体中的 project_key。
url
必填。上报服务端基地址,SDK 会自行拼接具体协议端点(如 /api/v1/collect/events)。国内站填 https://dem.rumt-zh.com,详见「上报域名」。
userId
必填。业务用户标识,对应上报体的 context.user_id;不填时该字段不会写入上报体,控制台无法按用户维度聚合分析。
deviceId
必填。宿主提供的设备标识(String?)。由业务侧设置,SDK 不会读取系统设备标识(如 ANDROID_ID);未设置或传空白时,上报字面量 not_set,按设备维度的异常率统计会失真。也可在运行期通过 TDEM.getInstance() 调用 setDeviceId 设置、clearDeviceId() 清除。
version
必填。应用版本号,对应上报体的 app.version,用于版本对比与版本分布分析。该值是控制台版本维度的唯一来源,SDK 不会自动回填(插件虽会自行读取 versionName,但仅用于设备明细,不会写入版本维度所在的主字段);不填则版本维度聚合失效。
llmVersion
业务使用的 LLM 版本标识,可选,默认 unknown。用于控制台按模型版本聚合 SSE 指标(上报在 sse_call 的 model_version 字段)。传空或纯空白按 unknown 处理;超长值按 128 个码点截断(不会切坏代理对)。
env
运行环境标识,允许值 production / development / gray / pre / daily / local / test / others,默认 production;未知值(含 staging)归一为 others。
logLevel
日志级别,可选 TDEM.LEVEL_DEBUG / TDEM.LEVEL_INFO / TDEM.LEVEL_WARN / TDEM.LEVEL_ERROR,默认 WARN。
batchDelay
事件批量上报延迟(ms),自首个事件进入 buffer 后等待的最长时间,默认5000。
batchSize
事件批量上报大小上限,达到后立即 flush,默认50。
sampleRate
全局采样率(0.0 - 1.0),默认1.0。
beforeReport
事件上报前过滤回调,返回 true 放行、false 丢弃。
requestCapture
请求/响应报文落盘目录,可选,默认关闭。传入 File 即开启:网络插件把每次请求的请求体、响应体与元信息写入该目录(request-body.bin / response-body.bin / metadata.json),先写 .partial 临时目录再原子改名,供排查请求参数是否正确、响应内容是否符合预期。报文含业务敏感数据,仅建议在调试包中开启,并配合 disableRequestCapture() 关闭。
retryConfig
重试配置,默认最大重试3次、初始间隔 1000ms、退避乘数2.0、最终失败丢弃(DISCARD)。

崩溃监控(crashPluginConfig,默认开启)

配置项
说明
enabled
总开关,默认 true。开启时同时捕获 Java 与 Native 崩溃。

ANR 监控(anrPluginConfig,默认开启)

配置项
说明
enabled
总开关,默认 true。
captureAllInitializedProcesses
覆盖所有初始化了 SDK 的进程,默认 true。
dedupeWindowMs
重复 ANR 抑制窗口(ms)。
javaThreadDumpEnabled
Java 多线程堆栈采集,默认 true。
signalMonitorEnabled
Native SIGQUIT 监控,默认 true。
messageQueueDumpEnabled
主线程消息队列现场采集,默认 true。
foregroundStateEnabled
前后台状态采集,默认 true。
resourceLoadEnabled
CPU / 内存 / IO 负载采集,默认 true。
maxMessageScan
消息队列采集扫描条数上限。

卡顿监控(lagPluginConfig,默认开启)

配置项
说明
enabled
总开关,默认 true。
lagThresholdMs
卡顿判定阈值(ms),默认1000,最低100。
contextCollectEnabled
是否收集 MQ 诊断和系统状态,默认 true。
foregroundOnly
是否仅在前台检测,默认 true。
dedupWindowMs
事件去重时间窗口(ms),默认60000。
multiStackEnabled
是否启用多堆栈采集,默认 true。
multiStackIntervalMs
多堆栈采集间隔(ms),默认200。
multiStackMaxConsecutiveFailures
多堆栈连续失败熔断阈值,默认2,范围1 - 5。连续失败达到该次数后停止本次多堆栈采集,避免在抓不到栈的设备上反复重试。
multiStackMaxSamples
多堆栈最大采集次数,默认15,范围1 - 15。
multiStackMaxDurationMs
多堆栈总时长上限(ms),默认3000。

启动监控(launchPluginConfig,默认开启)

配置项
说明
enabled
是否启用,默认 true。启动监控通过 ASM 编译期插桩实现,早于 SDK 初始化执行。
manualEndEnabled
是否等待业务调用 TDEM.endLaunch() 才封口,默认 false(首个 Activity resume 后自动上报)。
warmStartThresholdMs
温启动判定阈值(ms),默认180000。
launchTimeoutMs
启动超时兜底(ms),默认60000。
dirtyThresholdMs
脏数据判定阈值(ms),默认30000。启动事件从开始到上报的间隔超过该值视为「脏数据」直接丢弃,避免把用户隔夜打开、长时间驻留的场景算成一次启动。
prependTimeoutMs
前置数据等待超时(ms),默认5000。启动事件在等待前置数据(如冷启动期间的网络请求)超过该时长后即按「准备开始」上报,不再继续等待。

网络监控(httpPluginConfig,默认开启)

配置项
说明
enabled
总开关,默认 true。
okHttpEnabled
OkHttp3 监控开关,默认 true。
urlConnectionEnabled
HttpURLConnection 监控开关,默认 true。
urlConnectionEnableSsl
是否启用 HttpsURLConnection 的 SSL 握手耗时采集,默认 false。开启后 SDK 会替换连接使用的 SSLSocketFactory 以记录握手起止时间;仅在排查 TLS 握手慢时开启。
sseEnabled
SSE 运行期开关,默认 true。当前版本仅在网络插件初始化时输出一条状态日志,不参与采集判定,是否采集由编译期 instrumentSSE 决定。
traceEnabled
全链路追踪注入(W3C traceparent + SkyWalking sw8),默认 false。
collectHeadersEnabled
采集请求 / 响应头(白名单 + 黑名单过滤),默认 true。
reportAllSuccessfulRequests
是否上报全部成功请求,默认 false(仅慢成功与错误 / 取消上报)。
slowThresholdMs
慢请求阈值(ms),默认1000。
urlFilter
URL 过滤函数,返回 false 的 URL 不上报。
sseStallThresholdMs
SSE 停滞检测阈值(ms),默认60000。

用户行为监控(behaviorPluginConfig,默认关闭)

配置项
说明
enabled
总开关,默认 false(合规整改起默认 opt-in,需显式开启)。开启后采集 page_view / click / double_tap / long_press / scroll / pinch_zoom / key_press / screen_toggle / screen_rotation / text_input 等行为事件。

用户挣扎检测(strugglePluginConfig,默认开启)

配置项
说明
enabled
总开关,默认 true。
clickRulesEnabled
是否检测 rage / dead / error click,默认 true。
formRulesEnabled
是否检测 long focus,默认 true。
navigationRulesEnabled
是否检测 back-forward,默认 true。
deadClickIgnoredViewIds
精确忽略的 resource-id 列表(Android 特有)。
ignoreDeadClickSelectors
子串匹配 id / class,批量忽略 dead click(Android 特有)。
规则阈值(rage 1s/5次、dead/error 3s、long focus 20s、back-forward 10s/3次)内部写死,对齐 iOS,接入方不可修改。

Session Replay 会话录屏(replayPluginConfig,默认关闭)

当前版本对单个控件的遮罩调整只支持下表各配置项的类级方式(maskViewClasses / unmaskViewClasses)与 maskAllText / maskAllImages 两个全局开关,未开放按 View 实例逐个声明的接口。
配置项
说明
enabled
总开关,默认 false。
sessionSampleRate
全量会话采样率(0.0–1.0),默认 0.1。
onErrorSampleRate
错误触发采样率(0.0–1.0),默认 1.0。
quality
录制质量预设(LOW / MEDIUM / HIGH),默认 LOW。
注意:
该参数的枚举类型位于内部包(当前版本为 com.tencent.tdem.internal.z7),且只有 d = LOW 保留了静态常量字段;MEDIUM / HIGH 需通过 z7.valueOf("MEDIUM") / z7.valueOf("HIGH") 取值。跨版本升级时类名与常量名可能变化,不需要调优时建议直接用默认值。
screenshotStrategy
截图实现策略,默认 PIXEL_COPY(像素拷贝,兼容性最好)。另一取值 CANVAS 走 Canvas 绘制路径,maskAllText 在该路径下统一处理。
注意:
该参数的枚举类型位于内部包(当前版本为 com.tencent.tdem.internal.f9,常量 a = PIXEL_COPY、b = CANVAS)。Kotlin 与 Java 都需按当前版本的实际类名与常量名引用,跨版本升级时可能失效;不需要该能力时建议直接用默认值。
maskAllText
是否遮罩所有文本内容,默认 false。
maskAllImages
是否遮罩所有图片内容,默认 false。
maskViewClasses
需要遮罩的 View 类全限定名集合(默认遮罩 WebView / VideoView / PlayerView / PreviewView 等媒体控件)。
unmaskViewClasses
不遮罩的 View 类全限定名集合。

设备信息采集(devicePluginConfig,默认开启)

配置项
说明
enabled
是否启用设备信息采集,默认 true。