iOS/tvOS Application Integration¶
By collecting Metrics data from various iOS applications, visually analyze the performance of each iOS application.
Prerequisites¶
Note
If the RUM Headless service has been activated, the prerequisites are automatically configured, and the application can be directly integrated.
- Install DataKit;
- Configure the RUM Collector;
- Configure DataKit to be accessible over the public network and install the IP geolocation database.
Application Integration¶
- Go to User Access Monitoring > Create Application > iOS;
- Enter the application name;
- Enter the application ID;
-
Select the application integration method:
- Public DataWay: Directly receives RUM data without installing the DataKit collector.
- Local Environment Deployment: Receives RUM data after meeting the prerequisites.
Installation¶
Source Code: https://github.com/GuanceCloud/datakit-ios
Demo: https://github.com/GuanceDemo/guance-app-demo
-
Configure the
Podfile
file.-
Use Dynamic Library
-
Use Static Library
Podfile
file:use_modular_headers! # Main project target 'yourProjectName' do pod 'FTMobileSDK', :path => '[folder_path]' end # Widget Extension target 'yourWidgetExtensionName' do pod 'FTMobileSDK', :subspecs => ['Extension'] , :path => '[folder_path]' end
folder_path
: Path to the folder containingFTMobileSDK.podspec
.FTMobileSDK.podspec
file:Modify
s.version
ands.source
in theFTMobileSDK.podspec
file.Pod::Spec.new do |s| s.name = "FTMobileSDK" s.version = "[latest_version]" s.source = { :git => "https://github.com/GuanceCloud/datakit-ios.git", :tag => s.version } end
s.version
: Modify to the specified version, recommended to matchSDK_VERSION
inFTMobileSDK/FTMobileAgent/Core/FTMobileAgentVersion.h
.s.source
:tag => s.version
-
-
Execute
pod install
in thePodfile
directory to install the SDK.
-
Configure the
Cartfile
file. -
Update dependencies.
Depending on your target platform (iOS or tvOS), execute the corresponding
carthage update
command and add the--use-xcframeworks
parameter to generate XCFrameworks:-
For iOS platform:
-
For tvOS platform:
The generated xcframework is used the same way as a regular Framework. Add the compiled library to the project.
FTMobileAgent
: Add to the main project Target, supports iOS and tvOS platforms.FTMobileExtension
: Add to the Widget Extension Target. -
-
Add
-ObjC
toTARGETS
->Build Setting
->Other Linker Flags
. -
When using Carthage for integration, SDK version support:
FTMobileAgent
: >=1.3.4-beta.2FTMobileExtension
: >=1.4.0-beta.1
Using Xcode UI
1. Select PROJECT
-> Package Dependency
, click the + under the Packages
section.
-
Enter
https://github.com/GuanceCloud/datakit-ios.git
in the search box on the pop-up page. -
After Xcode successfully retrieves the package, it will display the SDK configuration page.
Dependency Rule
: It is recommended to selectUp to Next Major Version
.Add To Project
: Select the supported project.After filling in the configuration, click the
Add Package
button and wait for the loading to complete. -
In the pop-up
Choose Package Products for datakit-ios
, select the Target to which the SDK needs to be added, click theAdd Package
button, and the SDK will be successfully added.FTMobileSDK
: Add to the main project TargetFTMobileExtension
: Add to the Widget Extension Target
Using Package.swift
If your project is managed by SPM, add the SDK as a dependency by adding dependencies
to Package.swift
.
// Main project
dependencies: [
.package(url: "https://github.com/GuanceCloud/datakit-ios.git",
.upToNextMajor(from: "[latest_version]"))
]
Add dependencies for your Targets
targets: [
.target(
name: "YourTarget",
dependencies: [
.product(name: "FTMobileSDK", package: "FTMobileSDK"),
]),
.target(
name: "YourWidgetExtensionTarget",
dependencies: [
.product(name: "FTMobileExtension", package: "FTMobileSDK"),
]),
]
Note: Swift Package Manager is supported from version 1.4.0-beta.1 and above.
Add Header File¶
SDK Initialization¶
Basic Configuration¶
-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
// SDK FTMobileConfig settings
// Local environment deployment, Datakit deployment
//FTMobileConfig *config = [[FTMobileConfig alloc]initWithDatakitUrl:datakitUrl];
// Use 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)
// Use public DataWay deployment
let config = FTMobileConfig(datawayUrl: datawayUrl, clientToken: clientToken)
//config.enableSDKDebugLog = true //debug mode
config.compressIntakeRequests = true //Compress intake data
FTMobileAgent.start(withConfigOptions: config)
//...
return true
}
Attribute | Type | Required | Meaning |
---|---|---|---|
datakitUrl | NSString | Yes | Local environment deployment (Datakit) reporting URL address, example: http://10.0.0.1:9529, port defaults to 9529, the device installing the SDK needs to be able to access this address. Note: Only one of datakitUrl and datawayUrl should be configured |
datawayUrl | NSString | Yes | Public Dataway reporting URL address, obtained from the [User Access Monitoring] application, example: https://open.dataway.url, the device installing the SDK needs to be able to access this address. Note: Only one of datakitUrl and datawayUrl should be configured |
clientToken | NSString | Yes | Authentication token, needs to be used together with datawayUrl |
enableSDKDebugLog | BOOL | No | Set whether to allow log printing. Default NO |
env | NSString | No | Set the collection environment. Default prod , supports customization, or can be set using the provided FTEnv enumeration via the -setEnvWithType: method |
service | NSString | No | Set the name of the business or service. Affects the service field data in Log and RUM. Default: df_rum_ios |
globalContext | NSDictionary | No | Add custom tags. Refer to here for adding rules |
groupIdentifiers | NSArray | No | Array of AppGroups Identifiers for the Widget Extensions to be collected. If Widget Extensions data collection is enabled, App Groups must be set up, and the Identifier must be configured in this attribute |
autoSync | BOOL | No | Whether to automatically sync data to the server after collection. Default YES . When NO , use [[FTMobileAgent sharedInstance] flushSyncData] to manage data sync manually |
syncPageSize | int | No | Set the number of entries for sync requests. Range [5,). Note: A larger number of request entries means data sync will occupy more computing resources, default is 10 |
syncSleepTime | int | No | Set the sync interval time. Range [0,5000], default is not set |
enableDataIntegerCompatible | BOOL | No | Recommended to enable when coexisting with web data. This configuration is used to handle web data type storage compatibility issues. |
compressIntakeRequests | BOOL | No | Compress intake data with deflate, supported in SDK version 1.5.6 and above, default is off |
enableLimitWithDbSize | BOOL | No | Enable the use of DB to limit total cache size. 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 is 100MB, unit is byte, supported in SDK version 1.5.8 and above |
dbDiscardType | FTDBCacheDiscard | No | Set the data discard rule in the database. Default FTDBDiscard FTDBDiscard When the data count exceeds the maximum, discard the appended data. FTDBDiscardOldest When the data exceeds the maximum, discard the oldest data. Supported in SDK version 1.5.8 and above |
dataModifier | FTDataModifier | No | Modify individual fields. Supported in SDK version 1.5.16 and above, see example here |
lineDataModifier | FTLineDataModifier | No | Modify individual line data. Supported in SDK version 1.5.16 and above, see example here |
remoteConfiguration | BOOL | No | Whether to enable remote configuration for data collection, default is off. After enabling, SDK initialization or application hot start will trigger data updates. Supported in SDK version 1.5.17 and above. datakit version requirement >=1.60 or use public dataway |
remoteConfigMiniUpdateInterval | int | No | Set the minimum update interval for remote dynamic configuration, unit is seconds, default is 12 hours. Supported in SDK version 1.5.17 and above |
RUM Configuration¶
//Enable rum
FTRumConfig *rumConfig = [[FTRumConfig alloc]initWithAppid:appid];
rumConfig.enableTraceUserView = YES;
rumConfig.deviceMetricsMonitorType = FTDeviceMetricsMonitorAll;
rumConfig.monitorFrequency = FTMonitorFrequencyRare;
rumConfig.enableTraceUserAction = YES;
rumConfig.enableTraceUserResource = YES;
rumConfig.enableTrackAppFreeze = YES;
rumConfig.enableTrackAppCrash = YES;
rumConfig.enableTrackAppANR = YES;
rumConfig.errorMonitorType = FTErrorMonitorAll;
[[FTMobileAgent sharedInstance] startRumWithConfigOptions:rumConfig];
let rumConfig = FTRumConfig(appid: appid)
rumConfig.enableTraceUserView = true
rumConfig.deviceMetricsMonitorType = .all
rumConfig.monitorFrequency = .rare
rumConfig.enableTraceUserAction = true
rumConfig.enableTraceUserResource = true
rumConfig.enableTrackAppFreeze = true
rumConfig.enableTrackAppCrash = true
rumConfig.enableTrackAppANR = true
rumConfig.errorMonitorType = .all
FTMobileAgent.sharedInstance().startRum(withConfigOptions: rumConfig)
Attribute | Type | Required | Meaning |
---|---|---|---|
appid | NSString | Yes | Unique identifier for the User Access Monitoring application ID. Corresponds to setting the RUM appid , which will enable the RUM collection function, method to get appid |
samplerate | int | No | Sampling rate. Range [0,100], 0 means no collection, 100 means full collection, default is 100. Scope is all View, Action, LongTask, Error data under the same session_id |
sessionOnErrorSampleRate | int | No | Set the error collection rate. When the session is not sampled by samplerate , if an error occurs during the session, data from 1 minute before the error can be collected. Range [0,100], 0 means no collection, 100 means full collection, default is 0. Scope is all View, Action, LongTask, Error data under the same session_id. Supported in SDK version 1.5.16 and above |
enableTrackAppCrash | BOOL | No | Set whether to collect crash logs. Default NO |
enableTrackAppANR | BOOL | No | Collect ANR unresponsive events. DefaultNO |
enableTrackAppFreeze | BOOL | No | Collect UI freeze events. DefaultNO Can be enabled with -setEnableTrackAppFreeze:freezeDurationMs: method to collect freezes and set the freeze threshold |
freezeDurationMs | long | No | Set the UI freeze threshold. Range [100,), unit is milliseconds, default is 250ms. Supported in SDK version 1.5.7 and above |
enableTraceUserView | BOOL | No | Set whether to track user View operations. DefaultNO |
enableTraceUserAction | BOOL | No | Set whether to track user Action operations. DefaultNO Can use view.accessibilityIdentifier to customize action_name |
enableTraceUserResource | BOOL | No | Set whether to track user network requests. DefaultNO , only affects native http Note: Network requests initiated via [NSURLSession sharedSession] cannot collect performance data;SDK version 1.5.9 and above supports collecting network requests initiated via Swift's URLSession async/await APIs. |
resourceUrlHandler | FTResourceUrlHandler | No | Customize resource collection rules. Default is no filtering. Return: NO means to collect, YES means not to collect. |
errorMonitorType | FTErrorMonitorType | No | Error event monitoring supplement type. Add monitoring information to the collected crash data. FTErrorMonitorBattery for battery level, FTErrorMonitorMemory for memory usage, FTErrorMonitorCpu for CPU usage, default is not set. |
deviceMetricsMonitorType | FTDeviceMetricsMonitorType | No | View performance monitoring type, default is not set. Add corresponding monitoring item information to the collected View data. FTDeviceMetricsMonitorMemory monitors current application memory usage, FTDeviceMetricsMonitorCpu monitors CPU jumps, FTDeviceMetricsMonitorFps monitors screen frame rate, default is not set. |
monitorFrequency | FTMonitorFrequency | No | View performance monitoring sampling period. Configure monitorFrequency to set the sampling period for View monitoring item information. FTMonitorFrequencyDefault 500ms (default), FTMonitorFrequencyFrequent 100ms, FTMonitorFrequencyRare 1000ms. |
enableResourceHostIP | BOOL | No | Whether to collect the IP of the request target domain address. Supported on >= iOS 13.0 >= tvOS 13.0 |
globalContext | NSDictionary | No | Add custom tags, used to distinguish user monitoring data sources. If tracking function is needed, the parameter key is track_id , value is any value, refer to here for adding rules |
rumCacheLimitCount | int | No | RUM maximum cache limit. Default 100_000, supported in SDK version 1.5.8 and above |
rumDiscardType | FTRUMCacheDiscard | No | Set RUM discard rules. Default FTRUMCacheDiscard FTRUMCacheDiscard When RUM data count exceeds the maximum, discard the appended data. FTRUMDiscardOldest When RUM data exceeds the maximum, discard the oldest data. Supported in SDK version 1.5.8 and above |
resourcePropertyProvider | FTResourcePropertyProvider | No | Add custom properties to RUM Resource via block callback. Supported in SDK version 1.5.10 and above. Priority lower than URLSession custom collection |
enableTraceWebView | BOOL | No | Set whether to collect webView data, default YES. Supported in SDK version 1.5.17 and above |
allowWebViewHost | NSArray | No | Set the WebView host addresses allowed for data tracking, nil means all collection, default is nil. Supported in SDK version 1.5.17 and above |
sessionTaskErrorFilter | FTSessionTaskErrorFilter | No | Set whether to intercept URLSessionTask Error, return YES to intercept, NO to not intercept, intercepted RUM-Error will not collect this error. Supported in SDK version 1.5.17 and above |
viewTrackingHandler | FTViewTrackingHandler | No | Customize View tracking logic, used to determine which ViewControllers need to be monitored as RUM Views and customize View Name. Effective condition: enableTraceUserView = YES . Supported in SDK version 1.5.18 and above |
actionTrackingHandler | FTActionTrackingHandler | No | Customize Action tracking logic, used to filter RUM Action events to be recorded and customize Action Name. Effective condition: enableTraceUserAction = YES . Supported in SDK version 1.5.18 and above |
Log Configuration¶
//Enable logger
FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc]init];
loggerConfig.enableCustomLog = YES;
loggerConfig.enableLinkRumData = YES;
loggerConfig.logLevelFilter = @[@(FTStatusError),@(FTStatusCritical)];
loggerConfig.discardType = FTDiscardOldest;
[[FTMobileAgent sharedInstance] startLoggerWithConfigOptions:loggerConfig];
let loggerConfig = FTLoggerConfig()
loggerConfig.enableCustomLog = true
loggerConfig.enableLinkRumData = true
loggerConfig.logLevelFilter = [NSNumber(value: FTLogStatus.statusError.rawValue),NSNumber(value: FTLogStatus.statusCritical.rawValue)] // loggerConfig.logLevelFilter = [2,3]
loggerConfig.discardType = .discardOldest
FTMobileAgent.sharedInstance().startLogger(withConfigOptions: loggerConfig)
Attribute | Type | Required | Meaning |
---|---|---|---|
samplerate | int | No | Sampling rate. Range [0,100], 0 means no collection, 100 means full collection, default is 100. |
enableCustomLog | BOOL | No | Whether to upload custom log. DefaultNO |
printCustomLogToConsole | BOOL | No | Set whether to output custom logs to the console. DefaultNO , custom log output format |
logLevelFilter | NSArray | No | Set log level filtering, default is not set. Example: 1. Collect logs of Info and Error levels, set as @[@(FTStatusInfo),@(FTStatusError)] or @[@0,@1] 2. Collect logs including custom levels, such as collecting "customLevel" and Error, set as @[@"customLevel",@(FTStatusError)] Supported in SDK version 1.5.16 and above for filtering custom levels |
enableLinkRumData | BOOL | No | Whether to associate with RUM data. DefaultNO |
globalContext | NSDictionary | No | Add log custom tags. Refer to here for adding rules |
logCacheLimitCount | int | No | Local cache maximum log entry limit [1000,), larger logs mean greater disk cache pressure, default is 5000 |
discardType | FTLogCacheDiscard | No | Set the log discard rule when the log reaches the limit. Default FTDiscard FTDiscard When log data count exceeds the maximum (5000), discard the appended data. FTDiscardOldest When log data exceeds the maximum, discard the oldest data. |
Trace Configuration¶
Attribute | Type | Required | Meaning |
---|---|---|---|
samplerate | int | No | Sampling rate. Range [0,100], 0 means no collection, 100 means full collection, default is 100. |
networkTraceType | FTNetworkTraceType | No | Set the type of link tracing. Default is DDTrace , currently supports Zipkin , Jaeger , DDTrace , Skywalking (8.0+), TraceParent (W3C). If integrating with OpenTelemetry, please check the supported types and agent related configurations. |
enableLinkRumData | BOOL | No | Whether to associate with RUM data. DefaultNO |
enableAutoTrace | BOOL | No | Set whether to enable automatic http trace. DefaultNO , currently only supports NSURLSession |
traceInterceptor | FTTraceInterceptor | No | Support custom link tracing via URLRequest, return TraceContext after confirming interception, return nil if not intercepted. Supported in SDK version 1.5.10 and above. Priority lower than URLSession custom collection |
RUM User Data Tracking¶
FTRUMConfig
configuration enableTraceUserAction
, enableTraceUserView
, enableTraceUserResource
, enableTrackAppFreeze
, enableTrackAppCrash
, and enableTrackAppANR
to achieve automatic collection tracking of Action
, View
, Resource
, LongTask
, Error
data. If custom collection is needed, use FTExternalDataManager
to report data, as shown below:
View¶
Usage¶
/// Create a page
///
/// Call this method before `-startViewWithName` to record the page load time. If the load time cannot be obtained, this method does not need to be called.
/// - Parameters:
/// - viewName: Page name
/// - loadTime: Page load time (in nanoseconds)
-(void)onCreateView:(NSString *)viewName loadTime:(NSNumber *)loadTime;
/// Enter a page
/// - Parameters:
/// - viewName: Page name
/// - property: Event custom properties (optional)
-(void)startViewWithName:(NSString *)viewName property:(nullable NSDictionary *)property;
/// Update the current RUM View's load time.
/// Must be called between `-startView` and `-stopView` to take effect.
/// - Parameter duration: Load duration (in nanoseconds).
-(void)updateViewLoadingTime:(NSNumber *)duration;
/// Leave a page
/// - Parameter property: Event custom properties (optional)
-(void)stopViewWithProperty:(nullable NSDictionary *)property;
/// Create a page
///
/// Call this method before `-startViewWithName` to record the page load time. If the load time cannot be obtained, this method does not need to be called.
/// - Parameters:
/// - viewName: Page name
/// - loadTime: Page load time (ns)
open func onCreateView(_ viewName: String, loadTime: NSNumber)
/// Enter a page
/// - Parameters:
/// - viewName: Page name
/// - property: Event custom properties (optional)
open func startView(withName viewName: String, property: [AnyHashable : Any]?)
/// Update the current RUM View's load time.
/// Must be called between `-startView` and `-stopView` to take effect.
/// - Parameter duration: Load duration (in nanoseconds).
open func updateViewLoadingTime(_ duration: NSNumber)
/// Leave a page
/// - Parameter property: Event custom properties (optional)
open func stopView(withProperty property: [AnyHashable : Any]?)
Code Example¶
- (void)viewDidAppear:(BOOL)animated{
[super viewDidAppear:animated];
// Scenario 1:
[[FTExternalDataManager sharedManager] startViewWithName:@"TestVC"];
// Scenario 2: Dynamic parameters
[[FTExternalDataManager sharedManager] startViewWithName:@"TestVC" property:@{@"custom_key":@"custom_value"}];
}
-(void)viewDidDisappear:(BOOL)animated{
[super viewDidDisappear:animated];
// Scenario 1:
[[FTExternalDataManager sharedManager] stopView];
// Scenario 2: Dynamic parameters
[[FTExternalDataManager sharedManager] stopViewWithProperty:@{@"custom_key":@"custom_value"}];
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
// Scenario 1:
FTExternalDataManager.shared().startView(withName: "TestVC")
// Scenario 2: Dynamic parameters
FTExternalDataManager.shared().startView(withName: "TestVC",property: ["custom_key":"custom_value"])
}
override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
// Scenario 1:
FTExternalDataManager.shared().stopView()
// Scenario 2: Dynamic parameters
FTExternalDataManager.shared().stopView(withProperty: ["custom_key":"custom_value"])
}
Action¶
Usage¶
/// Start a RUM Action.
///
/// RUM will bind the Action to the possible Resource, Error, LongTask events triggered by it. Avoid adding multiple times within 0.1 s, only one Action will be associated with the same View at the same time. If the previous Action has not ended, the new Action will be discarded.
/// Does not affect Actions added with the `addAction:actionType:property` method.
///
/// - Parameters:
/// - actionName: Event name
/// - actionType: Event type
/// - property: Event custom properties (optional)
- (void)startAction:(NSString *)actionName actionType:(NSString *)actionType property:(nullable NSDictionary *)property;
/// Add an Action event. No duration, no discard logic
///
/// Does not affect RUM Actions started with `startAction:actionType:property:`.
/// - Parameters:
/// - actionName: Event name
/// - actionType: Event type
/// - property: Event custom properties (optional)
- (void)addAction:(NSString *)actionName actionType:(NSString *)actionType property:(nullable NSDictionary *)property;
/// Start a RUM Action.
///
/// RUM will bind the Action to the possible Resource, Error, LongTask events triggered by it. Avoid adding multiple times within 0.1 s, only one Action will be associated with the same View at the same time. If the previous Action has not ended, the new Action will be discarded.
/// Does not affect Actions added with the `addAction:actionType:property` method.
///
/// - Parameters:
/// - actionName: Event name
/// - actionType: Event type
/// - property: Event custom properties (optional)
open func startAction(_ actionName: String, actionType: String, property: [AnyHashable : Any]?)
/// Add an Action event. No duration, no discard logic
///
/// Does not affect RUM Actions started with `startAction:actionType:property:`.
/// - Parameters:
/// - actionName: Event name
/// - actionType: Event type
/// - property: Event custom properties (optional)
open func addAction(_ actionName: String, actionType: String, property: [AnyHashable : Any]?)
Code Example¶
Error¶
Usage¶
```objectivec /// Add an Error event /// - Parameters: /// - type: error type /// - message: Error message /// - stack: Stack information /// - property: Event custom properties (optional) - (void)addErrorWithType:(NSString *)type message:(NSString *)message stack:(NSString *)stack property:(nullable NSDictionary *)property;
/// Add an Error event /// - Parameters: /// - type: error type /// - state: Application running state /// - message: Error message /// - stack: Stack information /// - property: Event custom properties (optional) - (