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

本文将为您介绍如何初始化用户体验监控 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 会自行拼接具体协议端点。
完整配置项说明
基础配置
下表中 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，但仅用于设备明细，不会写入版本维度所在的主字段）；不填则版本维度聚合失效。
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 丢弃。
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。
multiStackMaxSamples
多堆栈最大采集次数，默认15，范围1 - 15。
multiStackMaxDurationMs
多堆栈总时长上限（ms），默认3000。
启动监控（launchPluginConfig，默认开启）
配置项
说明
enabled
是否启用，默认 true。启动监控通过 ASM 编译期插桩实现，早于 SDK 初始化执行。
manualEndEnabled
是否等待业务调用 TDEM.endLaunch() 才封口，默认 false（首个 Activity resume 后自动上报）。
warmStartThresholdMs
温启动判定阈值（ms），默认180000。
launchTimeoutMs
启动超时兜底（ms），默认60000。
网络监控（httpPluginConfig，默认开启）
配置项
说明
enabled
总开关，默认 true。
okHttpEnabled
OkHttp3 监控开关，默认 true。
urlConnectionEnabled
HttpURLConnection 监控开关，默认 true。
sseEnabled
SSE 监控开关，默认 true。
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，默认关闭）
配置项
说明
enabled
总开关，默认 false。
sessionSampleRate
全量会话采样率（0.0–1.0），默认 0.1。
onErrorSampleRate
错误触发采样率（0.0–1.0），默认 1.0。
quality
录制质量预设（LOW / MEDIUM / HIGH），默认 LOW。
maskAllText
是否遮罩所有文本内容，默认 false。
maskAllImages
是否遮罩所有图片内容，默认 false。
maskViewClasses
需要遮罩的 View 类全限定名集合（默认遮罩 WebView / VideoView / PlayerView / PreviewView 等媒体控件）。
unmaskViewClasses
不遮罩的 View 类全限定名集合。
需要针对个别控件调整遮罩时，可通过 TDEMPrivacyMetadata.setSensitive / setReplayMasking 主动声明，详见《API 说明》的「隐私标记」章节。
设备信息采集（devicePluginConfig，默认开启）
配置项
说明
enabled
是否启用设备信息采集，默认 true。

配置项	说明
`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`，但仅用于设备明细，不会写入版本维度所在的主字段）；不填则版本维度聚合失效。
`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` 丢弃。
`retryConfig`	重试配置，默认最大重试3次、初始间隔 1000ms、退避乘数2.0、最终失败丢弃（`DISCARD`）。

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

配置项	说明
`enabled`	总开关，默认 `true`。
`lagThresholdMs`	卡顿判定阈值（ms），默认1000，最低100。
`contextCollectEnabled`	是否收集 MQ 诊断和系统状态，默认 `true`。
`foregroundOnly`	是否仅在前台检测，默认 `true`。
`dedupWindowMs`	事件去重时间窗口（ms），默认60000。
`multiStackEnabled`	是否启用多堆栈采集，默认 `true`。
`multiStackIntervalMs`	多堆栈采集间隔（ms），默认200。
`multiStackMaxSamples`	多堆栈最大采集次数，默认15，范围1 - 15。
`multiStackMaxDurationMs`	多堆栈总时长上限（ms），默认3000。

配置项	说明
`enabled`	是否启用，默认 `true`。启动监控通过 ASM 编译期插桩实现，早于 SDK 初始化执行。
`manualEndEnabled`	是否等待业务调用 `TDEM.endLaunch()` 才封口，默认 `false`（首个 Activity resume 后自动上报）。
`warmStartThresholdMs`	温启动判定阈值（ms），默认180000。
`launchTimeoutMs`	启动超时兜底（ms），默认60000。

配置项	说明
`enabled`	总开关，默认 `true`。
`okHttpEnabled`	OkHttp3 监控开关，默认 `true`。
`urlConnectionEnabled`	HttpURLConnection 监控开关，默认 `true`。
`sseEnabled`	SSE 监控开关，默认 `true`。
`traceEnabled`	全链路追踪注入（W3C traceparent + SkyWalking sw8），默认 `false`。
`collectHeadersEnabled`	采集请求 / 响应头（白名单 + 黑名单过滤），默认 `true`。
`reportAllSuccessfulRequests`	是否上报全部成功请求，默认 `false`（仅慢成功与错误 / 取消上报）。
`slowThresholdMs`	慢请求阈值（ms），默认1000。
`urlFilter`	URL 过滤函数，返回 `false` 的 URL 不上报。
`sseStallThresholdMs`	SSE 停滞检测阈值（ms），默认60000。

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

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

SDK 初始化

本页目录：

操作步骤

上报域名

完整配置项说明

基础配置

崩溃监控（crashPluginConfig，默认开启）

ANR 监控（anrPluginConfig，默认开启）

卡顿监控（lagPluginConfig，默认开启）

启动监控（launchPluginConfig，默认开启）

网络监控（httpPluginConfig，默认开启）

用户行为监控（behaviorPluginConfig，默认关闭）

用户挣扎检测（strugglePluginConfig，默认开启）

Session Replay 会话录屏（replayPluginConfig，默认关闭）

设备信息采集（devicePluginConfig，默认开启）