跳转至

SDK 初始化

本文用于承载 iOS SDK 初始化与运行时能力相关内容。

基础配置

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
    // SDK FTMobileConfig 设置
     // 本地环境部署、Datakit 部署
     //FTMobileConfig *config = [[FTMobileConfig alloc]initWithDatakitUrl:datakitUrl];
     // 使用公网 DataWay 部署
    FTMobileConfig *config = [[FTMobileConfig alloc]initWithDatawayUrl:datawayUrl clientToken:clientToken];
    //config.enableSDKDebugLog = YES;              //debug 模式
    config.compressIntakeRequests = YES;
    //启动 SDK
    [FTMobileAgent startWithConfigOptions:config];

   //...
    return YES;
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     // SDK FTMobileConfig 设置
       // 本地环境部署、Datakit 部署
       //let config = FTMobileConfig(datakitUrl: url)
       // 使用公网 DataWay 部署
     let config = FTMobileConfig(datawayUrl: datawayUrl, clientToken: clientToken)
     //config.enableSDKDebugLog = true              //debug 模式
     config.compressIntakeRequests = true           //上报数据压缩
     FTMobileAgent.start(withConfigOptions: config)
     //...
     return true
}
属性 类型 必须 含义
datakitUrl NSString 本地环境部署(Datakit)上报 URL 地址,例子:http://10.0.0.1:9529,端口默认 9529,安装 SDK 设备需能访问该地址。注意:datakitUrl 和 datawayUrl 配置两者二选一
datawayUrl NSString 公网 DataWay 上报 URL 地址,从 [用户访问监测] 应用中获取,例子:https://open.dataway.url,安装 SDK 设备需能访问这地址。注意:datakitUrl 和 datawayUrl 配置两者二选一
clientToken NSString 认证 token,需要与 datawayUrl 同时使用
enableSDKDebugLog BOOL 设置是否允许打印日志。默认 NO
env NSString 设置采集环境。默认 prod,支持自定义,也可根据提供的 FTEnv 枚举通过 -setEnvWithType: 方法设置
service NSString 设置所属业务或服务的名称。影响 Log 和 RUM 中 service 字段数据。默认:df_rum_ios
globalContext NSDictionary 添加自定义标签。添加规则请查阅 此处
groupIdentifiers NSArray 需要采集的 Widget Extensions 对应的 AppGroups Identifier 数组。若开启 Widget Extensions 数据采集,则必须设置 App Groups,并将 Identifier 配置到该属性中
autoSync BOOL 是否在采集数据后自动同步到服务器。默认 YES。当为 NO 时使用 [[FTMobileAgent sharedInstance] flushSyncData] 自行管理数据同步
syncPageSize int 设置同步请求条目数。范围 [5,),注意:请求条目数越大,代表数据同步占用更大的计算资源,默认为 10
syncSleepTime int 设置同步间歇时间。范围 [0,5000],默认不设置
enableDataIntegerCompatible BOOL 需要与 web 数据共存情况下,建议开启。此配置用于处理 web 数据类型存储兼容问题
compressIntakeRequests BOOL 对上传同步数据进行 deflate 压缩,SDK 1.5.6 以上版本支持这个参数,默认关闭
enableLimitWithDbSize BOOL 开启使用 DB 限制总缓存大小功能。注意:开启之后 FTLoggerConfig.logCacheLimitCountFTRUMConfig.rumCacheLimitCount 将失效。SDK 1.5.8 以上版本支持该参数
dbCacheLimit long DB 缓存限制大小。范围 [30MB,),默认 100MB,单位 byte,SDK 1.5.8 以上版本支持该参数
dbDiscardType FTDBCacheDiscard 设置数据库中数据丢弃规则。默认 FTDBDiscardFTDBDiscard 当数据数量大于最大值时,丢弃追加数据;FTDBDiscardOldest 当数据大于最大值时,丢弃老数据。SDK 1.5.8 以上版本支持该参数
dataModifier FTDataModifier 对单个字段进行更改。SDK 1.5.16 以上支持,使用示例请看 数据采集脱敏
lineDataModifier FTLineDataModifier 对单条数据数据进行更改。SDK 1.5.16 以上支持,使用示例请看 数据采集脱敏
enableDataFilter BOOL 是否开启 SDK 侧 DataKit 兼容数据过滤,包含本地过滤规则与远程过滤规则。默认 YES,SDK 1.6.4 以上支持,使用示例请看 数据过滤
dataFilters NSDictionary App 本地管理的数据过滤规则。支持的分类:loggingrum。SDK 1.6.4 以上支持,规则语法请看 黑名单规则
remoteConfiguration BOOL 是否开启数据采集的远程配置功能,默认不开启。开启之后,SDK 初始化或应用热启动会触发数据更新。SDK 1.5.17 以上支持。Datakit 版本要求 >=1.60 或使用公网 DataWay
remoteConfigMiniUpdateInterval int 设置远程动态配置最小更新间隔,单位秒,默认 12 小时。SDK 1.5.17 以上支持
remoteConfigFetchCompletionBlock FTRemoteConfigFetchCompletionBlock 远程配置结果回调,用于接收拉取结果并支持自定义调整配置模型。SDK 1.5.19 以上支持,使用示例请看 这里

黑名单过滤

Data Filter 用于在 SDK 写入本地缓存前,按规则过滤 RUM 与 Log 数据。命中过滤规则的数据不会进入本地缓存,也不会上报。

  • 本地规则:通过 FTMobileConfig.dataFilters 配置,由 App 在初始化 SDK 时下发。
  • 远程规则:开启 FTMobileConfig.enableDataFilter 后,SDK 会拉取 Studio 侧添加的黑名单规则。

  • 本地规则与远程规则会同时生效,任一规则命中后该条数据都会被丢弃。

  • 黑名单过滤在 lineDataModifier 之后、本地缓存写入之前执行。如果同时配置了 lineDataModifier 和黑名单过滤,过滤规则会基于修改后的数据进行判断。

Data Filter 作用于 SDK 数据写入链路。规则过多或正则表达式过于复杂时,可能影响数据写入性能,建议仅配置必要规则。

config.enableDataFilter = YES;
config.dataFilters = @{
    @"logging": @[@"{ source in [ 'df_rum_ios_log' ] and message match [ 'timeout' ] }"],
    @"rum": @[@"{ resource_status match [ '5..' ] }"]
};
config.enableDataFilter = true
config.dataFilters = [
    "logging": ["{ source in [ 'df_rum_ios_log' ] and message match [ 'timeout' ] }"],
    "rum": ["{ resource_status match [ '5..' ] }"]
]

规则语法

Data Filter 规则语法与黑名单过滤规则基本一致,完整语法说明可参考 黑名单过滤规则

dataFilters 的 key 表示数据分类,目前 SDK 支持:

分类 说明
logging Log 数据
rum RUM 数据

每条规则使用 { 条件 } 表示,命中任意一条规则即过滤该分类下的数据。规则中可使用数据的 tagfield 字段。

字段值格式和操作符语义可参考黑名单过滤规则中的 字段值格式说明操作符说明

SDK 规则字符串中所有字段值均需使用数组格式,反向操作符固定写作 notinnotmatch

{ status in [ 'debug' ] and env notin [ 'prod' ] and message notmatch [ '.*error.*' ] }

用户的绑定与注销

使用 FTMobileAgent 绑定用户信息与注销当前用户。

/// 绑定用户信息,可以在用户登录成功后调用此方法用来绑定用户信息
///
/// - Parameters:
///   - Id:  用户Id
///   - userName: 用户名称(可选)
///   - userEmail: 用户邮箱(可选)
///   - extra: 用户的额外信息(可选)
- (void)bindUserWithUserID:(NSString *)Id userName:(nullable NSString *)userName userEmail:(nullable NSString *)userEmail extra:(nullable NSDictionary *)extra;

/// 注销当前用户,可以在用户退出登录后调用此方法来解绑用户信息
- (void)unbindUser;
/// 绑定用户信息,可以在用户登录成功后调用此方法用来绑定用户信息
///
/// - Parameters:
///   - Id:  用户Id
///   - userName: 用户名称(可选)
///   - userEmail: 用户邮箱(可选)
///   - extra: 用户的额外信息(可选)
open func bindUser(withUserID Id: String, userName: String?, userEmail: String?, extra: [AnyHashable : Any]?)

/// 注销当前用户,可以在用户退出登录后调用此方法来解绑用户信息
open func unbindUser()

extra 添加规则注意事项请查阅 此处

运行时能力

关闭 SDK

使用 FTMobileAgent 关闭 SDK 时,请务必在主线程中调用,否则可能引发线程安全问题。如果动态改变 SDK 配置,需要先关闭,以避免错误数据的产生。

+ (void)shutDown;
open class func shutDown()

清理 SDK 缓存数据

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

+ (void)clearAllData;
open class func clearAllData()

主动同步数据

使用 FTMobileAgent 主动同步数据。

FTMobileConfig.autoSync = NO 时,才需要自行进行数据同步。

- (void)flushSyncData;
func flushSyncData()

主动同步动态配置

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

文档评价

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