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
lineDataModifierand before local cache write. If bothlineDataModifierand 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.
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.
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.
Clearing SDK Cache Data¶
Use FTMobileAgent to clear unreported cache data.
Actively Syncing Data¶
Use FTMobileAgent to actively sync data.
FTMobileConfig.autoSync = NOis required before manually performing data synchronization.
Actively Syncing Dynamic Configuration¶
Dynamic configuration related capabilities have been separated into Dynamic Configuration.