SDK Initialization¶

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

Basic Configuration¶

Initialize the SDK in the AppDelegate for iOS/tvOS. For macOS, the viewDidLoad method of the first displayed NSViewController or the windowDidLoad method of NSWindowController is called before applicationDidFinishLaunching in the AppDelegate. To avoid abnormal lifecycle collection of 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 settings
    // Local environment deployment, Datakit deployment
    //FTSDKConfig *config = [[FTSDKConfig alloc]initWithDatakitUrl:datakitUrl];
    // Using public network DataWay deployment
    FTSDKConfig *config = [[FTSDKConfig alloc]initWithDatawayUrl:datawayUrl clientToken:clientToken];
    //config.enableSDKDebugLog = YES;              //debug mode
    config.compressIntakeRequests = YES;
    //Start 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];
        // Using public network 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 settings
       // Local environment deployment, Datakit deployment
       //let config = FTSDKConfig(datakitUrl: url)
       // Using public network 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)
// Using public network DataWay deployment
// let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
config.enableSDKDebugLog = true
FTSDKAgent.start(withConfigOptions: config)

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

Blacklist Filtering¶

Data Filter is used to filter RUM and Log data according to rules before the SDK writes to the local cache. Data that hits the filtering rules will not enter the local cache and will not be reported.

• Local rules: Configured via FTSDKConfig.dataFilters, delivered by the app during SDK initialization.

• Remote rules: After enabling FTSDKConfig.enableDataFilter, the SDK will pull the blacklist rules added on the Studio side.

• Local and remote rules take effect simultaneously. If any rule is hit, the data item will be discarded.

• Blacklist filtering occurs after lineDataModifier and before writing to the local cache. If both lineDataModifier and blacklist filtering are configured, the filtering rules will evaluate based on the modified data.

Data Filter acts on the SDK data writing pipeline. Too many rules or overly complex regular expressions may affect data writing 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..' ] }"]
]

Rule Syntax¶

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

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

Each rule is represented by { condition }. If any rule is hit, the data under that category is filtered. The tag and field fields of the data can be used in the rules.

For field value format and operator semantics, refer to Field Value Format Description and Operator Description in the blacklist filtering rules.

All field values in the SDK rule string must use array format, and reverse operators are fixed as notin and notmatch.

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

User Binding and Unbinding¶

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

/// Bind user information. Call this method after successful user login 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;

/// Unbind the current user. Call this method after user logout to unbind user information.
- (void)unbindUser;

/// Bind user information. Call this method after successful user login 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]?)

/// Unbind the current user. Call this method after user logout to unbind user information.
open func unbindUser()

For extra adding rules, please refer to here.

Runtime Capabilities¶

Shutting Down the SDK¶

When using FTMobileAgent to shut down the SDK, must be called on the main thread, otherwise thread safety issues may occur. If dynamically changing the SDK configuration, you need to shut it down first to avoid incorrect data generation.

+ (void)shutDown;

open class func shutDown()

Clearing SDK Cache Data¶

Use FTMobileAgent to clear unreported cached data.

+ (void)clearAllData;

open class func clearAllData()

Actively Syncing Data¶

Use FTMobileAgent to actively sync data.

Only when FTSDKConfig.autoSync = NO, you need to perform data synchronization manually. The old version FTMobileConfig.autoSync is still compatible.

- (void)flushSyncData;

func flushSyncData()

Actively Syncing Dynamic Configuration¶

The runtime dynamic configuration capabilities have been moved to Dynamic Configuration.