跳转至

SDK 初始化

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

基础配置

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

-(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);
}

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 侧黑名单过滤，默认 YES。支持过滤 Log 和 RUM 数据，SDK 1.6.4 以上支持，使用示例请看黑名单过滤
dataFilters NSDictionary 否 配置应用内黑名单规则，支持 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 以上支持，使用示例请看 这里

黑名单过滤

SDK 1.6.4 以上版本支持在数据写入本地缓存前过滤 RUM 与 Log 数据。该能力默认开启，可以通过 FTSDKConfig.enableDataFilter = NO 关闭 SDK 侧过滤。

黑名单规则可以在观测云工作空间的黑名单中统一配置，由 SDK 从 DataKit 或 DataWay 自动拉取；也可以通过 FTSDKConfig.dataFilters 在应用内配置。两种方式对应同一套黑名单过滤能力，可以同时使用，任一规则命中后该条数据都会被丢弃。

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

enableDataFilter 仅控制 SDK 侧的规则拉取与过滤。设置为 NO 后，SDK 不再应用 dataFilters 或拉取工作空间规则；使用 DataKit 上报时，工作空间黑名单仍可能在 DataKit 端执行。

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..' ] }"]
]

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.*' ] }

用户的绑定与注销

使用 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 主动同步数据。

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

- (void)flushSyncData;

func flushSyncData()

主动同步动态配置

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

文档评价

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