操作步骤
步骤1：创建独立的初始化模块并置顶引入
启用用户行为采集（
behavior）时，必须在业务代码引入并绑定 ScrollView、FlatList、SectionList、TextInput 之前执行 new TDEM(config)，确保宿主组件包装生效。建议新建独立的 src/tdem.ts 模块，并在入口文件第一行引入。// src/tdem.ts：请在用户同意隐私政策后加载并创建全局复用的 SDK 实例import TDEM from 'tdem-rn-sdk';import {Platform} from 'react-native';export const tdem = new TDEM({id: 'YOUR_APP_ID',url: 'https://dem.rumt-zh.com',env: 'production',version: Platform.OS === 'ios' ? '1.0.0-ios' : '1.0.0-android',debug: false,onError: true,spa: true,api: true,behavior: true,crash: true,replay: true,struggle: true,});
在入口文件第一行引入该模块：
// index.js 或 App.tsx：必须写在其他业务组件 import 之前import './src/tdem';
注意：
spa、api、behavior 为 JS 侧采集开关，默认关闭，为便于验证数据上报，本示例将其设置为 true。onError 同属 JS 侧，默认开启，详见 JS 侧采集配置 。crash、replay、struggle 为原生侧采集开关，默认开启，详见 原生侧采集配置。完整默认值见 完整配置项说明。id 与 url 为必填项。请将 YOUR_APP_ID 替换为控制台创建应用后分配的项目标识（project_key）， url 替换为应用所属站点对应的上报域名，详见 上报域名。缺失 id 或 url 时请勿初始化 SDK。version 请传入字符串（string）并与符号表上传时的版本号保持一致。由于 Android 与 iOS 的 Hermes SourceMap 在归一化 Bundle 地址相同时可能共享制品键，建议为双端设置不同后缀（如 '1.0.0-android' 与 '1.0.0-ios'），避免互相覆盖。远程配置与采样闸门：原生层启动后会请求
POST {url}/api/v1/config 拉取远程配置，并向 JS 层回传 { enabled, started, tdemSampleRate, replaySampleRate }。仅当 started === true（远端启用、会话采样命中且原生运行时已启动）且对应本地开关开启时，JS 采集插件才会挂载。tdem.isNativeStarted() 仅表示原生初始化回调已执行，不能替代 tdem.canCollect()。切勿把真实项目标识、云 API 密钥或内部测试环境地址提交进公开代码仓库。
步骤2：在获得用户隐私授权后初始化
SDK 在初始化过程中可能采集设备与用户信息，请在用户同意个人信息保护规则后再加载初始化模块或创建
TDEM 实例。步骤3：全局复用同一实例并包裹根组件
上报域名
请根据应用在控制台所属的站点地域选择对应的上报域名。不同站点的数据相互隔离，跨站填写会导致数据无法入库。
站点 | 控制台地域标识 | url（上报域名） |
国内站 | ap-guangzhou | https://dem.rumt-zh.com |
新加坡站 | ap-singapore | https://dem.rumt-sg.com |
硅谷站（美西） | na-siliconvalley | https://dem.rumt-us.com |
接入时填写站点根地址即可，无需拼接
/api/v1/... 路径，SDK 会自行拼接具体协议端点。上报地域与 App 界面语言（中文 / 英文）相互独立，SDK 不会根据语言自动切换上报域名。完整配置项说明
基础配置
参数 | 类型 | 必填 | 默认值 | 说明 |
id | string | 是 | 无 | 项目标识，对应请求体中的 project_key，在控制台创建 React Native 应用后获取。 |
url | string | 是 | 无 | |
env | string | 否 | 不传 | 运行环境标识（如 production / test / development）。控制台默认筛选 production，其他环境需在控制台顶部切换。 |
version | string | 否 | 不传 | 推荐显式配置。应用版本号字符串（如 '1.0.0-android'），用于版本分布分析及 SourceMap 匹配（原生桥仅读取字符串类型，请勿传入数字）。 |
userId | string | 否 | 不传 | 业务用户标识，用于按用户维度聚合分析；也可在登录后调用 tdem.setUser(userId) 动态设置。 |
deviceId | string | 否 | 不传 | 宿主提供的设备标识，初始化时传给原生层。未传时原生上报 not_set；请勿在 JS 侧自行生成。也可在运行时调用 tdem.setDeviceId(deviceId) / tdem.clearDeviceId()。 |
debug | boolean | 否 | false | 调试日志开关，开启后 JS 层输出 [TDEM-ReactNative] 前缀日志，验证完成后建议关闭。 |
beforeReport | function | 否 | 无 | 公共事件过滤钩子，作用于经 reportTDEMEvent 发送的每条 JS 事件；返回事件对象则放行，返回 null / false / undefined 则拦截该事件。 |
JS 侧采集配置
JS 侧采集开关支持两种写法：
传入布尔值：
true 表示按默认子配置开启，false 表示关闭。传入细分配置对象：在开启对应能力的同时，覆盖下表中的子参数。
参数 | 类型 | 默认值 | 说明 |
onError | boolean 或 OnErrorConfig | true | JS 运行时错误与未处理的 Promise rejection 监控。 |
spa | boolean 或 SpaConfig | false | 路由页面浏览（PV）自动监控。需配合导航容器注册或手动页面接口使用。 |
api | boolean 或 ApiMonitorConfig | false | JS 层 fetch 与 XMLHttpRequest 接口测速与错误监控。 |
behavior | boolean 或 BehaviorConfig | false | RN 用户行为采集（点击、滑动、长按、表单交互）。开启时需使用 tdem.wrap(App) 包裹根组件。 |
onError 子配置
当
onError 传入 OnErrorConfig 对象时，可使用以下字段：参数 | 类型 | 默认值 | 说明 |
ignoreErrors | string[] | 空数组 | 错误 message 命中数组中任一子串时忽略该错误。未配置时不忽略。 |
spa 子配置
当
spa 传入 SpaConfig 对象时，可使用以下字段：参数 | 类型 | 默认值 | 说明 |
ignore | 字符串或正则表达式数组 | 空数组 | 跳过 page_view 上报的规则。字符串按路由名全等匹配（大小写敏感，不是子串）；正则使用 RegExp.test。例如 ignore: ['home'] 不会跳过 Home 或 /home。 |
api 子配置
当
api 传入 ApiMonitorConfig 对象时，可使用以下字段：参数 | 类型 | 默认值 | 说明 |
apiDetail | boolean | false | 是否在接口事件中附带请求体（最长截断为 1000 字符）。开启前请确认请求体不含敏感信息。 |
ret | string[] | ret、retcode、code、errcode、errorcode | 用于识别业务返回码的响应 JSON 顶层字段名名单。SDK 按响应对象自身的字段出现顺序，取第一个出现在该名单中的键，而不是按数组下标优先。例如 { "code": 1, "ret": 0 } 会命中 code。 |
retCodeHandler | function | 未设置 | 自定义业务码解析函数。签名为 (data, url, ctx, payload)，返回 { code, isErr }。配置后会替代默认解析规则；返回 null 或 undefined 时按 { code: "unknown", isErr: false } 处理。 |
reqParamHandler | function | 未设置 | 请求体脱敏或裁剪处理函数。需同时开启 apiDetail: true。签名为 (data, url, ctx)。 |
未配置
retCodeHandler 时，SDK 按以下默认规则判定业务状态：1. 若响应 JSON 顶层存在出现在
ret 名单中的字段，取第一个这样的字段；取值不为数字 0、字符串 "0" 或 "unknown" 时，判定为业务失败。2. 否则，若存在字符串字段
status，取值不为 ok 或 success 时判定为失败。SDK 自身的采集域名请求会自动排除，不会产生递归上报。
behavior 子配置
当
behavior 传入 BehaviorConfig 对象时，可使用以下字段。传入 behavior: true 等同于启用下表全部子开关。参数 | 类型 | 默认值 | 说明 |
scroll | boolean | true | 是否采集滑动事件。 |
longPress | boolean | true | 是否采集长按事件。 |
input | boolean | true | 是否采集表单焦点、变更、失焦与提交事件。 |
captureText | boolean | true | 是否采集交互目标的可见文案（ target_text）。 |
scrollThreshold | number | 10 | 判定为滑动手势的最小位移阈值，单位为 pt。 |
longPressMs | number | 500 | 判定为长按手势的最小按压时长，单位为 ms。 |
说明：
出于隐私保护，
TextInput 表单事件仅采集控件标识、字段类型及输入长度分桶（0 / 1_10 / 11_50 / 51_plus），不采集输入明文；密码框（secureTextEntry）自动标记为加密字段。交互目标可见文案（
target_text）最长保留 127 字符，命中手机号、邮箱或 Token 等内置敏感规则时自动过滤。原生侧采集配置
以下参数由 React Native 桥透传给 Android / iOS 原生 SDK：
参数 | 默认值 | Android 端作用 | iOS 端作用 |
crash | true | 开启 Java 与 Native 崩溃监控 | 开启 Mach / Signal / NSException / C++ 崩溃监控 |
replay | true | 开启原生 Session Replay 会话录屏 | 开启原生 Session Replay 会话录屏 |
struggle | true | 开启原生用户挣扎检测 | 开启原生用户挣扎检测 |
说明：
原生侧的自动点击采集由 RN SDK 内部固定关闭，点击与手势统一由 JS 层采集，避免双端重复计数。
replay 本地默认开启，但实际是否录制仍受控制台远程配置及回放采样率（replaySampleRate）控制。路由接入（React Navigation）
在根组件文件第一行引入
src/tdem.ts 中的 tdem 实例，将其与 React Navigation 的 NavigationContainer 绑定并用 tdem.wrap(App) 包裹根组件（示例中 RootNavigator 为业务导航组件）：import {tdem} from './src/tdem';import {NavigationContainer, createNavigationContainerRef} from '@react-navigation/native';import {createReactNavigationIntegration} from 'tdem-rn-sdk';const navigationRef = createNavigationContainerRef();const integration = createReactNavigationIntegration(tdem);function App() {return (<NavigationContainerref={navigationRef}onReady={() => integration.registerNavigationContainer(navigationRef)}><RootNavigator /></NavigationContainer>);}export default tdem.wrap(App);
说明：
registerNavigationContainer 会在导航就绪时自动读取当前叶子路由名并监听后续状态变化，无需对同一路由再次手动调用 reportPageView。请始终正常渲染业务导航容器，切勿等待
tdem.canCollect() 返回 true 或 getSessionId() 返回非空值后才挂载页面，确保未命中采样或离线场景下应用界面仍可正常打开。
