Skip to content

SDK Initialization

This document covers the content related to iOS SDK initialization and runtime capabilities.

Basic Configuration

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

   //...
    return YES;
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     // SDK FTMobileConfig settings
       // Local environment deployment, Datakit deployment
       //let config = FTMobileConfig(datakitUrl: url)
       // Using public DataWay deployment
     let config = FTMobileConfig(datawayUrl: datawayUrl, clientToken: clientToken)
     //config.enableSDKDebugLog = true              //debug mode
     config.compressIntakeRequests = true           //Upload data compression
     FTMobileAgent.start(withConfigOptions: config)
     //...
     return true
}
Property Type Required Meaning
datakitUrl NSString Yes Local environment deployment (Datakit) upload URL address, example: http://10.0.0.1:9529, default port is 9529, the device installing the SDK must be able to access this address. Note: Choose one between datakitUrl and datawayUrl configuration
datawayUrl NSString Yes Public DataWay upload URL address, obtained from the [RUM] application, example: https://open.dataway.url, the device installing the SDK must be able to access this address. Note: Choose one between datakitUrl and datawayUrl configuration
clientToken NSString Yes Authentication token, must be used together with datawayUrl
enableSDKDebugLog BOOL No Sets whether to allow log printing. Default NO
env NSString No Sets the collection environment. Default prod, supports customization, can also be set via the provided FTEnv enumeration using the -setEnvWithType: method
service NSString No Sets the name of the business or service it belongs to. Affects the service field data in Log and RUM. Default: df_rum_ios
globalContext NSDictionary No Adds custom tags. Addition rules please refer to here
groupIdentifiers NSArray No Array of AppGroups Identifiers corresponding to Widget Extensions that need to be collected. If Widget Extensions data collection is enabled, App Groups must be set up, and the Identifier must be configured in this property
autoSync BOOL No Whether to automatically sync collected data to the server. Default YES. When NO, use [[FTMobileAgent sharedInstance] flushSyncData] to manage data synchronization manually
syncPageSize int No Sets the number of entries per sync request. Range [5,), Note: Larger request entry count means data synchronization occupies more computing resources, default is 10
syncSleepTime int No Sets the sync interval time. Range [0,5000], default is not set
enableDataIntegerCompatible BOOL No Recommended to enable when coexistence with web data is needed. This configuration handles web data type storage compatibility issues
compressIntakeRequests BOOL No Deflate compression for upload synchronization data, supported in SDK version 1.5.6 and above, default is off
enableLimitWithDbSize BOOL No Enables the function to limit total cache size using DB. Note: After enabling, FTLoggerConfig.logCacheLimitCount and FTRUMConfig.rumCacheLimitCount will become invalid. Supported in SDK version 1.5.8 and above
dbCacheLimit long No DB cache limit size. Range [30MB,), default 100MB, unit byte, supported in SDK version 1.5.8 and above
dbDiscardType FTDBCacheDiscard No Sets the data discard rule in the database. Default FTDBDiscard. FTDBDiscard discards appended data when data count exceeds the maximum; FTDBDiscardOldest discards old data when data exceeds the maximum. Supported in SDK version 1.5.8 and above
dataModifier FTDataModifier No Modifies a single field. Supported in SDK version 1.5.16 and above, usage examples see Data Collection Desensitization
lineDataModifier FTLineDataModifier No Modifies a single piece of data. Supported in SDK version 1.5.16 and above, usage examples see Data Collection Desensitization
enableDataFilter BOOL No Whether to enable SDK-side DataKit compatible data filtering, including local filtering rules and remote filtering rules. Default YES, supported in SDK version 1.6.4 and above, usage examples see Data Filtering
dataFilters NSDictionary No App locally managed data filtering rules. Supported categories: logging, rum. Supported in SDK version 1.6.4 and above, rule syntax see Blacklist Rules
remoteConfiguration BOOL No Whether to enable the remote configuration function for data collection, default is not enabled. After enabling, SDK initialization or app hot start will trigger data updates. Supported in SDK version 1.5.17 and above. Datakit version requirement >=1.60 or using public DataWay
remoteConfigMiniUpdateInterval int No Sets the minimum update interval for remote dynamic configuration, unit seconds, default 12 hours. Supported in SDK version 1.5.17 and above
remoteConfigFetchCompletionBlock FTRemoteConfigFetchCompletionBlock No Remote configuration result callback, used to receive fetch results and support custom adjustment of configuration model. Supported in SDK version 1.5.19 and above, usage examples see here

Blacklist Filtering

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

  • Local Rules: Configured via FTMobileConfig.dataFilters, issued by the App when initializing the SDK.
  • Remote Rules: After enabling FTMobileConfig.enableDataFilter, the SDK will pull blacklist rules added on the Studio side.

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

  • Blacklist filtering executes after lineDataModifier and before local cache write. If both lineDataModifier and blacklist filtering are configured, filtering rules will be judged based on the modified data.

Data Filter acts on the SDK data write pipeline. When there are too many rules or regular expressions are too complex, it may affect data write performance. It is recommended to only configure 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 rules. For complete syntax description, please refer to Blacklist Filtering Rules.

The key of dataFilters represents the data category, currently the SDK supports:

Category Description
logging Log data
rum RUM data

Each rule is represented using { condition }, hitting any rule will filter data under that category. Rules can use tag, field fields of the data.

Field value formats and operator semantics can refer to the 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 the reverse operators are fixed as notin, 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, can be called after user login succeeds to bind user information
///
/// - Parameters:
///   - Id:  User Id
///   - userName: User name (optional)
///   - userEmail: User email (optional)
///   - extra: User's extra information (optional)
- (void)bindUserWithUserID:(NSString *)Id userName:(nullable NSString *)userName userEmail:(nullable NSString *)userEmail extra:(nullable NSDictionary *)extra;

/// Unbind the current user, can be called after user logout to unbind user information
- (void)unbindUser;
/// Bind user information, can be called after user login succeeds to bind user information
///
/// - Parameters:
///   - Id:  User Id
///   - userName: User name (optional)
///   - userEmail: User email (optional)
///   - extra: User's extra information (optional)
open func bindUser(withUserID Id: String, userName: String?, userEmail: String?, extra: [AnyHashable : Any]?)

/// Unbind the current user, can be called after user logout to unbind user information
open func unbindUser()

For extra addition rule precautions, please refer to here.

Runtime Capabilities

Shutting Down the SDK

When using FTMobileAgent to shut down the SDK, be sure to call it in the main thread, otherwise thread safety issues may arise. If dynamically changing SDK configuration, it needs to be shut down first to avoid generating erroneous data.

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

Clearing SDK Cache Data

Use FTMobileAgent to clear unreported cache data.

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

Actively Syncing Data

Use FTMobileAgent to actively sync data.

FTMobileConfig.autoSync = NO is required before manually performing data synchronization.

- (void)flushSyncData;
func flushSyncData()

Actively Syncing Dynamic Configuration

Dynamic configuration related capabilities have been separated into Dynamic Configuration.