跳转至

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。

{ `status` in [ 'debug' ] and `env` not in [ 'prod' ] and `message` not match [ '.*error.*' ] }

用户信息绑定与解绑

使用方法

/**
 * 绑定用户。
 * @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 内正在运行对象。
 */
shutDown(): Promise<void>;
FTMobileReactNative.shutDown();

清理 SDK 缓存数据

使用 FTMobileReactNative 清理未上报的缓存数据。

/**
 * 清除所有尚未上传至服务器的数据。
 */
clearAllData(): Promise<void>;
FTMobileReactNative.clearAllData();

主动同步数据

当配置 FTMobileConfig.autoSync 为 true 时,无需做额外操作,SDK 会自动同步。

当配置 FTMobileConfig.autoSync 为 false 时,需要主动触发数据同步。

/**
 * 主动同步数据,当配置 `FTMobileConfig.autoSync = false` 时需要主动触发。
 */
flushSyncData(): Promise<void>;
FTMobileReactNative.flushSyncData();

初始化顺序说明

请在顶层 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);

动态配置

动态配置相关能力已拆分至 动态配置。

文档评价

文档内容是否对您有帮助?