SDK 初始化¶
本文用于承载 React Native SDK 初始化与运行时能力相关内容。
导入 SDK¶
现在在您的代码中,您可以使用:
import {
FTMobileReactNative,
FTReactNativeLog,
FTReactNativeTrace,
FTReactNativeRUM,
FTMobileConfig,
FTLogConfig,
FTTraceConfig,
FTRUMConfig,
ErrorMonitorType,
DeviceMetricsMonitorType,
DetectFrequency,
TraceType,
FTLogStatus,
EnvType,
} from '@cloudcare/react-native-mobile';
基础配置¶
// 本地环境部署、Datakit 部署
let config: FTMobileConfig = {
datakitUrl: datakitUrl,
};
// 使用公网 DataWay
let config: FTMobileConfig = {
datawayUrl: datawayUrl,
clientToken: clientToken,
};
await FTMobileReactNative.sdkConfig(config);
| 字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
| datakitUrl | string | 是 | 本地环境部署(Datakit)上报 URL 地址,例子:http://10.0.0.1:9529,端口默认 9529,安装 SDK 设备需能访问该地址。注意:datakitUrl 和 datawayUrl 配置两者二选一 |
| datawayUrl | string | 是 | 公网 Dataway 上报 URL 地址,从 [用户访问监测] 应用中获取,例子:https://open.dataway.url,安装 SDK 设备需能访问这地址。注意:datakitUrl 和 datawayUrl 配置两者二选一 |
| clientToken | string | 是 | 认证 token,需要与 datawayUrl 同时使用 |
| debug | boolean | 否 | 设置是否允许打印日志,默认 false |
| env | string | 否 | 环境配置,默认 prod,任意字符,建议使用单个单词,例如 test 等 |
| envType | enum EnvType | 否 | 环境配置,默认 EnvType.prod。注:env 与 envType 只需配置一个 |
| service | string | 否 | 设置所属业务或服务的名称,影响 Log 和 RUM 中 service 字段数据。默认:df_rum_ios、df_rum_android |
| autoSync | boolean | 否 | 是否在采集数据后自动同步到服务器,默认 true。当为 false 时使用 FTMobileReactNative.flushSyncData() 自行管理数据同步 |
| syncPageSize | number | 否 | 设置同步请求条目数。范围 [5,),注意:请求条目数越大,代表数据同步占用更大的计算资源 |
| syncSleepTime | number | 否 | 设置同步间歇时间。范围 [0,5000],默认不设置 |
| enableDataIntegerCompatible | boolean | 否 | 需要与 web 数据共存情况下,建议开启。此配置用于处理 web 数据类型存储兼容问题。0.3.12 以后版本默认开启 |
| globalContext | object | 否 | 添加自定义标签。添加规则请查阅此处 |
| compressIntakeRequests | boolean | 否 | 对上传同步数据进行 deflate 压缩,默认关闭 |
| enableLimitWithDbSize | boolean | 否 | 开启使用 DB 限制数据大小,默认 100MB,单位 Byte,数据库越大,磁盘压力越大,默认不开启。注意:开启之后 Log 配置 logCacheLimitCount 及 RUM 配置 rumCacheLimitCount 将失效。SDK 0.3.10 以上版本支持该参数 |
| dbCacheLimit | number | 否 | DB 缓存限制大小。范围 [30MB,),默认 100MB,单位 byte,SDK 0.3.10 以上版本支持该参数 |
| dbDiscardStrategy | string | 否 | 设置数据库中数据丢弃规则。丢弃策略:FTDBCacheDiscard.discard 丢弃新数据(默认)、FTDBCacheDiscard.discardOldest 丢弃旧数据。SDK 0.3.10 以上版本支持该参数 |
| dataModifier | object | 否 | 对单个字段进行更改。SDK 0.3.14 以上支持,使用示例请看 数据采集脱敏 |
| lineDataModifier | object | 否 | 对单条数据进行更改。SDK 0.3.14 以上支持,使用示例请看 数据采集脱敏 |
| enableDataFilter | boolean | 否 | 是否开启 SDK 侧黑名单过滤,默认 true。支持过滤 Log 和 RUM 数据,SDK 0.4.2 以上版本支持,使用示例请看黑名单过滤 |
| dataFilters | Record |
否 | 配置应用内黑名单规则,支持 logging 和 rum 两类数据。SDK 0.4.2 以上版本支持,规则语法请看规则语法 |
| remoteConfiguration | boolean | 否 | 是否开启数据采集的远程配置功能,默认不开启。开启之后,SDK 初始化或应用热启动会触发数据更新。SDK 0.3.16 以上支持。 可配置参数 |
| remoteConfigMiniUpdateInterval | number | 否 | 设置远程动态配置最小更新间隔,单位秒,默认 12 小时。SDK 0.3.16 以上支持 |
| remoteConfigOverrideRules | Array |
否 | 设置远程配置覆盖规则,可在应用远程配置前进行自定义调整。SDK 0.3.16 以上支持,使用示例请看 这里 |
黑名单过滤¶
React Native SDK 0.4.2 以上版本支持在数据写入本地缓存前过滤 RUM 与 Log 数据。该能力默认开启,可以通过 enableDataFilter: false 关闭 SDK 侧过滤。
黑名单规则可以在观测云工作空间的黑名单中统一配置,由 SDK 从 DataKit 或 DataWay 自动拉取;也可以通过 FTMobileConfig.dataFilters 在应用内配置。两种方式对应同一套黑名单过滤能力,可以同时使用,任一规则命中后该条数据都会被丢弃。
黑名单过滤在 lineDataModifier 之后、本地缓存写入之前执行。如果同时配置了 lineDataModifier 和黑名单过滤,过滤规则会基于修改后的数据进行判断。
enableDataFilter仅控制 SDK 侧的规则拉取与过滤。设置为false后,SDK 不再应用dataFilters或拉取工作空间规则;使用 DataKit 上报时,工作空间黑名单仍可能在 DataKit 端执行。Data Filter 作用于 SDK 数据写入链路。规则过多或正则表达式过于复杂时,可能影响数据写入性能,建议仅配置必要规则。
let config: FTMobileConfig = {
datawayUrl: datawayUrl,
clientToken: clientToken,
enableDataFilter: true,
dataFilters: {
logging: [
"{ `source` in [ 'df_rum_ios_log' , 'df_rum_android_log' ] and `message` match [ 'timeout' ] }",
],
rum: [
"{ `resource_status` match [ '5..' ] }",
],
},
};
await FTMobileReactNative.sdkConfig(config);
SDK 初始化时会立即拉取工作空间黑名单规则,后续拉取间隔以服务端返回的 pull_interval 为准;服务端未返回有效值时,SDK 使用 10 秒作为兜底间隔。pull_interval 支持秒数或带单位的字符串,例如 10、30s、2m、1h。
规则语法¶
Data Filter 规则语法与黑名单过滤规则基本一致,完整语法说明可参考 黑名单过滤规则。
dataFilters 的 key 表示数据分类,目前 SDK 支持:
| 分类 | 说明 |
|---|---|
logging |
Log 数据 |
rum |
RUM 数据 |
每条规则使用 { 条件 } 表示,命中任意一条规则即过滤该分类下的数据。规则中可以使用数据的 tag、field 字段以及 source、measurement 数据类型标识字段。
字段值格式和操作符语义可参考黑名单过滤规则中的 字段值格式说明 和 操作符说明。
SDK 规则字符串中的字段值建议使用数组格式。反向操作符支持 not in、not match,同时兼容服务端下发规则使用的 notin、notmatch 以及 not_in。
用户信息绑定与解绑¶
使用方法¶
/**
* 绑定用户。
* @param userId 用户 ID。
* @param userName 用户姓名。
* @param userEmail 用户邮箱。
* @param extra 用户的额外信息。
*/
bindRUMUserData(userId: string, userName?: string, userEmail?: string, extra?: object): Promise<void>;
/**
* 解绑用户。
*/
unbindRUMUserData(): Promise<void>;
使用示例¶
import { FTMobileReactNative } from '@cloudcare/react-native-mobile';
FTMobileReactNative.bindRUMUserData('react-native-user', 'user_name');
FTMobileReactNative.unbindRUMUserData();
运行时能力¶
关闭 SDK¶
使用 FTMobileReactNative 关闭 SDK。
清理 SDK 缓存数据¶
使用 FTMobileReactNative 清理未上报的缓存数据。
主动同步数据¶
当配置 FTMobileConfig.autoSync 为 true 时,无需做额外操作,SDK 会自动同步。
当配置 FTMobileConfig.autoSync 为 false 时,需要主动触发数据同步。
初始化顺序说明¶
请在顶层 index.js 文件中注册 App 之前完成 SDK 初始化,以确保在调用 SDK 其他方法之前,SDK 已完全准备就绪。
完成基础配置之后,再进行 RUM、Log、Trace 配置。
import App from './App';
async function sdkInit() {
await FTMobileReactNative.sdkConfig(config);
await FTReactNativeRUM.setConfig(rumConfig);
// ...
}
sdkInit();
AppRegistry.registerComponent('main', () => App);
动态配置¶
动态配置相关能力已拆分至 动态配置。