SDK Initialization¶

This article covers the initialization and runtime capabilities of the iOS/tvOS/macOS SDK.

Basic Configuration¶

For iOS/tvOS, initialization is usually performed in AppDelegate. On macOS, the viewDidLoad method of the first displayed NSViewController and the windowDidLoad method of NSWindowController are called before AppDelegate's applicationDidFinishLaunching. To avoid abnormal lifecycle collection for the first view, it is recommended to initialize the SDK in main.m or main.swift.

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
    // SDK FTSDKConfig configuration
     // Local environment deployment, Datakit deployment
     //FTSDKConfig *config = [[FTSDKConfig alloc]initWithDatakitUrl:datakitUrl];
     // Use public DataWay deployment
    FTSDKConfig *config = [[FTSDKConfig alloc]initWithDatawayUrl:datawayUrl clientToken:clientToken];
    //config.enableSDKDebugLog = YES;              //Debug mode
    config.compressIntakeRequests = YES;
    // Start the SDK
    [FTMobileAgent startWithConfigOptions:config];

   //...
    return YES;
}

// main.m file
#import <Cocoa/Cocoa.h>
#import <TrueWatchSDK/TrueWatchSDK.h>
int main(int argc, const char * argv[]) {
    @autoreleasepool {
        // Local environment deployment, Datakit deployment
        FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatakitUrl:datakitUrl];
        // Use public DataWay deployment
        // 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 configuration
       // Local environment deployment, Datakit deployment
       //let config = FTSDKConfig(datakitUrl: url)
       // Use public DataWay deployment
     let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
     //config.enableSDKDebugLog = true              //Debug mode
     config.compressIntakeRequests = true           //Compress reported data
     FTMobileAgent.start(withConfigOptions: config)
     //...
     return true
}

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

let config = FTSDKConfig(datakitUrl: datakitUrl)
// Use public DataWay deployment
// let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
config.enableSDKDebugLog = true
FTSDKAgent.start(withConfigOptions: config)

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

Blacklist Filtering¶

SDK 1.6.4 and later support filtering RUM and Log data before it is written to the local cache. This capability is enabled by default. You can disable SDK-side filtering by setting FTSDKConfig.enableDataFilter = NO.

Blacklist rules can be configured centrally in the Blacklist of the Guance workspace, and the SDK automatically pulls them from DataKit or DataWay. They can also be configured in-app via FTSDKConfig.dataFilters. Both methods correspond to the same blacklist filtering capability and can be used simultaneously; if any rule matches, the data entry is discarded.

Blacklist filtering runs after lineDataModifier and before writing to the local cache. If both lineDataModifier and blacklist filtering are configured, the filtering rules are evaluated against the modified data.

enableDataFilter only controls rule fetching and filtering on the SDK side. After setting it to NO, the SDK no longer applies dataFilters or pulls workspace rules. When reporting through DataKit, the workspace blacklist may still be enforced on the DataKit side.

Data Filter applies to the SDK data write path. Too many rules or overly complex regular expressions may affect data write performance. It is recommended to configure only necessary rules.

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

The SDK pulls the workspace blacklist rules immediately at initialization. Subsequent pull intervals follow the pull_interval returned by the server; if the server does not return a valid value, the SDK uses 10 seconds as the fallback interval. pull_interval supports seconds or strings with units, for example 10, 30s, 2m, 1h.

Rule Syntax¶

The Data Filter rule syntax is basically the same as the blacklist filtering rules. For the complete syntax, refer to Blacklist Filtering Rules.

The key of dataFilters indicates the data category. The SDK currently supports:

Each rule is expressed as { condition }. If any rule matches, the data of that category is filtered. Rules can use the tag and field fields of the data, as well as the data type identifier fields source and measurement.

For field value formats and operator semantics, refer to Field Value Formats and Operators in the blacklist filtering rules.

In SDK rule strings, field values are recommended to be in array format. Reverse operators support not in and not match, and are also compatible with notin, notmatch, and not_in used in rules delivered by the server.

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

Binding and Unbinding Users¶

Use FTMobileAgent to bind user information and unbind the current user.

/// Binds user information. Call this method after the user successfully logs in to bind user information.
///
/// - Parameters:
///   - Id: User ID
///   - userName: User name (optional)
///   - userEmail: User email (optional)
///   - extra: Additional user information (optional)
- (void)bindUserWithUserID:(NSString *)Id userName:(nullable NSString *)userName userEmail:(nullable NSString *)userEmail extra:(nullable NSDictionary *)extra;

/// Unbinds the current user. Call this method after the user logs out to unbind user information.
- (void)unbindUser;

/// Binds user information. Call this method after the user successfully logs in to bind user information.
///
/// - Parameters:
///   - Id: User ID
///   - userName: User name (optional)
///   - userEmail: User email (optional)
///   - extra: Additional user information (optional)
open func bindUser(withUserID Id: String, userName: String?, userEmail: String?, extra: [AnyHashable : Any]?)

/// Unbinds the current user. Call this method after the user logs out to unbind user information.
open func unbindUser()

For notes on the extra adding rules, see here.

Runtime Capabilities¶

Shutting Down the SDK¶

When shutting down the SDK with FTMobileAgent, be sure to call it on the main thread; otherwise, thread safety issues may occur. If you change the SDK configuration dynamically, shut down the SDK first to avoid generating incorrect data.

+ (void)shutDown;

open class func shutDown()

Clearing SDK Cached Data¶

Use FTMobileAgent to clear cached data that has not been reported.

+ (void)clearAllData;

open class func clearAllData()

Syncing Data Manually¶

Use FTMobileAgent to sync data manually.

You only need to sync data manually when FTSDKConfig.autoSync = NO. The older FTMobileConfig.autoSync remains compatible.

- (void)flushSyncData;

func flushSyncData()

Syncing Dynamic Configuration Manually¶

Dynamic configuration capabilities have been moved to Dynamic Configuration.