SDK 初始化¶

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

基础配置¶

iOS/tvOS 通常在 AppDelegate 中初始化。macOS 中第一个显示的 NSViewController 的 viewDidLoad 方法、NSWindowController 的 windowDidLoad 方法调用要早于 AppDelegate applicationDidFinishLaunching，为避免第一个视图的生命周期采集异常，建议在 main.m 或 main.swift 中进行 SDK 初始化。

Objective-CSwift

iOS/tvOSmacOS

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

   //...
    return YES;
}

// main.m 文件
#import <Cocoa/Cocoa.h>
#import <GuanceSDK/GuanceSDK.h>
int main(int argc, const char * argv[]) {
    @autoreleasepool {
        // 本地环境部署、Datakit 部署
        FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatakitUrl:datakitUrl];
        // 使用公网 DataWay 部署
        // FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatawayUrl:datawayUrl clientToken:clientToken];
        config.enableSDKDebugLog = YES;
        [FTSDKAgent startWithConfigOptions:config];
    }
    return NSApplicationMain(argc, argv);
}

iOS/tvOSmacOS

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     // SDK FTSDKConfig 设置
       // 本地环境部署、Datakit 部署
       //let config = FTSDKConfig(datakitUrl: url)
       // 使用公网 DataWay 部署
     let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
     //config.enableSDKDebugLog = true              //debug 模式
     config.compressIntakeRequests = true           //上报数据压缩
     FTMobileAgent.start(withConfigOptions: config)
     //...
     return true
}

创建 main.swift 文件，删除 AppDelegate.swift 中 @main 或 @NSApplicationMain。

import Cocoa
import GuanceSDK
let delegate = AppDelegate()
NSApplication.shared.delegate = delegate

let config = FTSDKConfig(datakitUrl: datakitUrl)
// 使用公网 DataWay 部署
// let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
config.enableSDKDebugLog = true
FTSDKAgent.start(withConfigOptions: config)

_ = NSApplicationMain(CommandLine.argc, CommandLine.unsafeArgv)

初始化配置命名

SDK 1.6.6 及以上版本中，新代码建议使用 FTSDKConfig。FTMobileConfig 当前仍可兼容使用，并继承自 FTSDKConfig；1.6.6 以下版本请继续使用 FTMobileConfig。

属性	类型	必须	含义
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 字段数据。默认 iOS 为 `df_rum_ios`，tvOS 为 `df_rum_tvos`，macOS 为 `df_rum_macos`
globalContext	NSDictionary	否	添加自定义标签。添加规则请查阅此处
groupIdentifiers	NSArray	否	需要采集的 iOS Widget Extensions 对应的 AppGroups Identifier 数组。若开启 Widget Extensions 数据采集，则必须设置 App Groups，并将 Identifier 配置到该属性中。macOS 不支持 Widget Extension
autoSync	BOOL	否	是否在采集数据后自动同步到服务器。默认 `YES`。当为 `NO` 时，iOS/tvOS 使用 `[[FTMobileAgent sharedInstance] flushSyncData]`，macOS 使用 `[[FTSDKAgent 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.logCacheLimitCount` 及 `FTRUMConfig.rumCacheLimitCount` 将失效。SDK 1.5.8 以上版本支持该参数
dbCacheLimit	long	否	DB 缓存限制大小。范围 [30MB,)，默认 100MB，单位 byte，SDK 1.5.8 以上版本支持该参数
dbDiscardType	FTDBCacheDiscard	否	设置数据库中数据丢弃规则。默认 `FTDBDiscard`。`FTDBDiscard` 当数据数量大于最大值时，丢弃追加数据；`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 本地管理的数据过滤规则。支持的分类：`logging`、`rum`。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 数据。命中过滤规则的数据不会进入本地缓存，也不会上报。

本地规则：通过 FTSDKConfig.dataFilters 配置，由 App 在初始化 SDK 时下发。
远程规则：开启 FTSDKConfig.enableDataFilter 后，SDK 会拉取 Studio 侧添加的黑名单规则。
本地规则与远程规则会同时生效，任一规则命中后该条数据都会被丢弃。
黑名单过滤在 lineDataModifier 之后、本地缓存写入之前执行。如果同时配置了 lineDataModifier 和黑名单过滤，过滤规则会基于修改后的数据进行判断。

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

Objective-CSwift

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 数据

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

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

SDK 规则字符串中所有字段值均需使用数组格式，反向操作符固定写作 notin、notmatch。

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

用户的绑定与注销¶

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

Objective-CSwift

/// 绑定用户信息，可以在用户登录成功后调用此方法用来绑定用户信息
///
/// - 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 配置，需要先关闭，以避免错误数据的产生。

Objective-CSwift

+ (void)shutDown;

open class func shutDown()

清理 SDK 缓存数据¶

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

Objective-CSwift

+ (void)clearAllData;

open class func clearAllData()

主动同步数据¶

使用 FTMobileAgent 主动同步数据。

FTSDKConfig.autoSync = NO 时，才需要自行进行数据同步。旧版 FTMobileConfig.autoSync 仍兼容。

Objective-CSwift

- (void)flushSyncData;

func flushSyncData()

主动同步动态配置¶

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

SDK 初始化¶

基础配置¶

黑名单过滤¶

规则语法¶

用户的绑定与注销¶

运行时能力¶

关闭 SDK¶

清理 SDK 缓存数据¶

主动同步数据¶

主动同步动态配置¶

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

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