iOS SDK User Guide

TIP

Before accessing, please read the preparation before accessing .

You can get iOS SDK source code on GitHub (opens new window).

iOS SDK requires a minimum system version of iOS 8.0

iOS SDK (Framework format) size is approximately 5.5 MB

**The latest version is: **2.7. 4

**Updated: **202 2 - 01 - 18

Download address (opens new window)

I. Integration and Initialization of SDK

1.1 Automatic SDK integration

• Installing the SDK using CocoaPods

1. Create and edit the Podfile content (if existing, edit directly):

Create Podfile, project project ( .xcodeproj) file with the command line in the same directory to execute commands:

pod init

Edit the content of the Podfile as follows:

platform :ios, '9.0'
target 'YourProjectTarget' do
  pod 'ThinkingSDK'  #ThinkingSDK
end

2. Execute the installation command

pod install

After success, the following records will appear:

3. The import is successful and the project is started

After the command is executed successfully, a .xcworkspacefile is generated, indicating that you have successfully imported the iOS SDK. Open the .xcworkspacefile to start the project (note: the .xcodeprojfile cannot be opened at the same time)

• Installing the SDK using Carthage

1. Add the following configuration to the Cartfile file:

github "ThinkingDataAnalytics/ios-sdk"

2. Perform carthage update --platform iOSand add ThinkingSDK.frameworkto your project

1.2 Manual Integration SDK

1. Download and extract the iOS SDK (opens new window)

2. Drag ThinkingSDK.frameworkinto the XCode Project Workspace project

3. Modify the settings of Other linker flags in the Build Settings tab under the Targets option of the project, add -ObjC

4. Switch to the Build Phases tab and add the following dependencies under the Link Binary With Libraries column:

libz.dylib、Security.framework、SystemConfiguration.framework、libsqlite3.tbd

1.3 Initialize SDK

In v1.2.0 version, the feature of multiple APP ID instances is added. For guidelines on the use of multiple APPIDs, please refer to the iOS SDK Multi APPID Guide section

Add in AppDelegate.m #import < ThinkingSDK/ThinkingAnalyticsSDK.h >

Then in application: didFinishLaunchingWithOptions:add initialization

As follows

// Initicalize
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:APP_ID withUrl:SERVER_URL];

// Support for initializing multiple APPID instances
// ThinkingAnalyticsSDK *instance2 = [ThinkingAnalyticsSDK startWithAppId:APP_ID2 withUrl:SERVER_URL2];

// Initicalize
let instance = ThinkingAnalyticsSDK.start(withAppId: "YOUR_APPID", withUrl: "YOUR_SERVER_URL")

// Support for initializing multiple APPID instances
// let instance2 = ThinkingAnalyticsSDK.start(withAppId: "YOUR_APPID2", withUrl: "YOUR_SERVER_URL2")

Parameters APP_IDare the APP_ID of your project and will be given when you apply for the project. Please fill in here.

The parameter SERVER_URLis the URL of the data upload

If you are using Cloud as a Service, enter the following URL:

https://receiver.ta.thinkingdata.cn

If you are using the version of private deployment, enter the following URL:

https://Data Acquisition Address

Using the https protocol, please apply for the domain name with the SSL certificate yourself, and the TA staff will assist in port configuration.

After initialization, you can use the SDK as follows:

// SDK can then be used in two ways
[instance track:@"event_name" properties:eventProperties];
// [[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID] track:@"event_name" properties:eventProperties];

// Prior to Version 1.2.0, or as a single instance, the following SDK can be used
// [[ThinkingAnalyticsSDK sharedInstance] track:@"event_name" properties:eventProperties];

// SDK can then be used in two ways
let properties:Dictionary<String,String>=["key":"value"];
instance.track("event_name", properties:properties)

// Prior to Version 1.2.0, or as a single instance, the following SDK can be used
// ThinkingAnalyticsSDK.sharedInstance(withAppid: "YOUR_APPID").track("event_name", properties:eventProperties)

In v2.7.3, the instance name feature is added to identify the instance when the instance is initialized. You can also obtain the instance according to the instance name.

// Set name for example after version 2.7.2
TDConfig *config = [[TDConfig alloc] initWithAppId:@"YOUR_APPID" serverUrl:@"YOUR_SERVER_URL"];
config.name = @"YOUR_NAME";
[ThinkingAnalyticsSDK startWithConfig:config];

// Get an example from name
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK sharedInstanceWithAppid: @"YOUR_NAME"];

// Set name for example after version 2.7.2
let config = TDConfig.init(appId: "YOUR_APPID", serverUrl: "YOUR_SERVER_URL")
config.name = "YOUR_NAME"
ThinkingAnalyticsSDK.start(with: config)

// Get an example from name
let instance = ThinkingAnalyticsSDK.sharedInstance(withAppid: "YOUR_NAME")

1.4 Background Self-Start Event Description

iOS 12 and below (iOS 13 does not use EnableSceneSupport), the background self-start event is not counted by default. It is configured by trackRelaunchedInBackgroundEvents. YESmeans collection, and NOmeans no collection.

iOS 13 uses EnableSceneSupportand must pass in the launchOptionsparameter.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...
    TDConfig *config = [[TDConfig alloc] init];
    config.launchOptions = launchOptions;
    config.trackRelaunchedInBackgroundEvents = YES;
    ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];
    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    let config = TDConfig()
    config.launchOptions = launchOptions ?? [:]
    config.trackRelaunchedInBackgroundEvents = true
    ThinkingAnalyticsSDK.start(withAppId: "APP_ID", withUrl: "SERVICE_URL", with: config)

    return true
}

1.5 Open Access to H5 page (optional)

If you need to get through with the JavaScript SDK that collects H5 page data, please call the following interface. For details, please refer to the H5 and APP SDK get through section

// Get through H5 page data
[instance addWebViewUserAgent];
// [[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID] addWebViewUserAgent];

// Get through H5 page data
instance.addWebViewUserAgent()

II. Set User ID

The SDK instance will use random UUID as the default guest ID for each user, which will be the user's identification ID when the user is not logged in. It should be noted that the guest ID will change when the user reinstates the app and changes the device.

2.1 Set Visitor ID (optional)

If the user can be used in your product without logging in, and you need to configure the user's guest ID in the unlogged state, you can call identify:to set it up:

[instance identify:@"123ABCabc"];

instance.identify("123ABCabc")

If you need to replace the visitor ID, you should use it immediately after the end of the initialization SDK. Do not use it multiple times to avoid creating useless accounts.

If you need to get the current visitor ID, you can use getDistinctIdto get:

// Returns the visitor ID, in case of multiple instances, the visitor ID of the calling instance is returned
[instance getDistinctId];

// Returns the visitor ID, in case of multiple instances, the visitor ID of the calling instance is returned
instance.getDistinctId()

2.2 Set Account ID

When the user logs in, you can call login:to set the user's account ID. The TA platform preferentially uses the account ID as the identity, and the set account ID will be saved. Multiple calls to login:will overwrite the previous account ID:

[instance login:@"123ABCabc@thinkingdata.cn"];

instance.login("123ABCabc@thinkingdata.cn")

Note that this method does not upload events for user logins

2.3 Empty Account ID

After the user produces login behavior, you can call logoutto clear the account ID. Before the next call to login:, it will be identified as the guest ID

[instance logout];

instance.logout()

We recommend that you call logoutduring explicit logout events, such as when the user logs out, instead of when the app is closed.

Note that this method does not upload user logged-out events

III. Send Events

After the SDK initialization is completed, you can use track:, track: properties:to upload events. In general, you may need to upload 20 to 100 different events. If you are using TA for the first time, we recommend that you upload a few key events first.

3.1 Send events

You can use track:, track: properties:to upload events. It is recommended that you set the attributes of the event and the conditions for sending information according to the previously combed doc:

// There are no properties set for this event
[instance track:@"StartApp"];

// Upload merchandise purchase event
NSDictionary *eventProperties = @{
    @"product_name": @"Product Name",
    @"product_num": @(1),
    @"IsFirstBuy": @(YES)
};
[instance track:@"product_buy" properties:eventProperties];

// There are no properties set for this event
instance.track("StartApp")

// Upload merchandise purchase event
let properties = [
    "productName": "商品名",
    "productNumber": 1,
    "isFirstBuy": true
] as [String: Any]
ThinkingAnalyticsSDK.sharedInstance()?.track("event_name", properties: properties)

The name of the event is of type NSString, can only begin with a letter, can contain numbers, letters and an underscore '_', is up to 50 characters in length, and is not case sensitive to letters.

• The attribute of the event is an NSDictionaryobject where each element represents an attribute.
• The value of Key is the name of the attribute, which is of NSStringtype. It is stipulated that it can only start with letters, contain numbers, letters and underscore '_', and is up to 50 characters in length. It is not sensitive to letter case.
• Value is the value of the property, which can be NSString, NSNumber, NSDate, NSDate , NSArray, object, and object group .
• **If you need to upload Boolean attributes, assign values **@YES**with **@NO**or **[NSNumber numberWithBool: YES]with [NSNumber numberWithBool: NO].

You cannot assign Boolean data using @true, @false, @TRUE, and @FALSE.

Note:

NSArray type is supported in v2.4.0 version, and needs to be used with TA background v2.5 and subsequent versions.

V2.7.3 version starts to support objects and object groups

In v2.2.0 version, the method overload of setting event trigger time and time offset is added. It supports passing in parameters of type NSDate to set event trigger time, and parameters of type NSTimeZone to set time offset. If this parameter is not passed in, track: local time and offset when called are taken as event trigger time and time zone offset:

NSDictionary *properties = @{
    @"product_name": @"Product Name",
    @"product_num": @1,
    @"IsFirstBuy": @YES
};
[instance track:@"product_buy"
     properties:properties
           time:[NSDate date]
       timeZone:[NSTimeZone timeZoneWithName:@"Asia/Shanghai"]];

let properties = ["product_name": "Product name", "product_num": NSNumber.init(value: 1), "IsFirstBuy": true] as [String: Any]
instance.track("product_buy", properties:properties time: Date(), timeZone: NSTimeZone(name: "Asia/Shanghai")! as TimeZone)

Note: Although the trigger time can be set for the event, the receiving end will only receive data from the first 10 days to the last 3 days relative to the server time. Data exceeding the time limit will be regarded as abnormal data and the whole data cannot be stored.

Since v2.3.1, you can align event times across multiple time zones by setting the SDK Default Time Zone, see the Setting Default Time Zone section.

Since v2.5.0, you can calibrate the SDK time interface to uniformly use server level time to complete data collection. Please refer to the calibration time section.

3.2 Set Public Event Properties

For some important attributes, such as the user's membership level, source channel, etc., these attributes need to be set in each event. At this time, you can set these attributes as public event attributes. Public event properties refer to the properties that each event will carry. You can call setSuperProperties:to set public properties. We recommend that you set public event properties before sending events.

Format requirements for public event properties are consistent with event properties.

[instance setSuperProperties:@{@"Channel": @"ABC", @"isTest": @YES}];

// Upload data after setting：
[instance track:@"product_view"
     properties:@{@"product_id": @"A1234"}];

// Equivalent to setting properties in an event：
NSDictionary *properties = @{
    @"Channel": @"ABC",
    @"isTest": @YES,
    @"product_id": @"A1234"
};
[instance track:@"product_view"
     properties:properties];

instance.setSuperProperties(["Channel" : "ABC", "isTest": true])

// Upload data after setting：
instance.track("product_view", properties: ["product_id" : "A1234"])

// Equivalent to setting properties in an event：
let properties = ["Channel": "ABC", "isTest": true, "product_id": "A1234"] as [String: Any]
instance.track("product_view", properties: properties)

The public event properties will be saved to the cache and need not be called every time the app is started. If a call to setSuperProperties:sets a previously set public event property, the previous property is overwritten. If the public event property and the Key of a property uploaded by track: properties:duplicate, the property of the event overrides the public event property:

[instance setSuperProperties:@{@"Channel": @"ABC", @"isTest": @YES}];

// Overwrite "Channel", where the value of the property "Channel" is "XYZ"
[instance setSuperProperties:@{@"Channel": @"XYZ"}];

// Overwrite "isTest", the value of "isTest" is False
[instance track:@"product_view"
     properties:@{@"isTest": @NO}];

instance.setSuperProperties(["Channel": "ABC", "isTest": true])

// Overwrite "Channel", where the value of the property "Channel" is "XYZ"
instance.setSuperProperties(["Channel": "XYZ"])

// Overwrite "isTest", the value of "isTest" is False
instance.track("product_view", properties: ["isTest": false])

If you need to delete a public event property, you can call unsetSuperProperty:clear the specified public event property; if you want to empty all public event properties, you can call clearSuperProperties; if you want to get all public event properties, you can call currentSuperProperties;

// Clear a common event property to clear the previously set "isTest" property
[instance unsetSuperProperty:@"isTest"];

// Clear all public event property
[instance clearSuperProperties];

//Get all public property
[instance currentSuperProperties];

// Clear a common event property to clear the previously set "isTest" property
instance.unsetSuperProGet all property("isTest")

// Clear all public event attributes
instance.clearSuperProperties()

//Get all public attributes
instance.currentSuperProperties()

3.3 Set Dynamic Public Properties

In v1.2.0, the feature of dynamic public attributes is added, that is, public attributes can obtain the current value when reporting, so that variable public attributes such as membership level can be easily reported. After setting the dynamic public property class through registerDynamicSuperProperties, the SDK will automatically execute when the event is reported and obtain the properties in the return value and add them to the triggered event. The following example is that each time the report is reported, the current time will be obtained and the time zone will be switched. When any event is triggered, the SDK will add the returned time to the attributes of the event.

// Set dynamic public attributes to dynamically capture when an event occurs when it is reported
[instance registerDynamicSuperProperties:^NSDictionary * _Nonnull{
    NSDateFormatter *formatter = [[NSDateFormatter alloc] init];
    [formatter setDateFormat:@"yyyy-MM-dd HH:mm:ss.SSS"];
    formatter.timeZone = [NSTimeZone timeZoneWithName:@"America/Chicago"];
    NSDate *datenow = [NSDate date];
    NSString *currentTimeString = [formatter stringFromDate:datenow];
    return @{@"AmericaTime": currentTimeString};
}];

// Set dynamic public attributes to dynamically capture when an event occurs when it is reported
instance.registerDynamicSuperProperties { () -> [String : Any] in
    let formatter = DateFormatter()
    formatter.dateFormat = "yyyy-MM-dd HH:mm:ss.SSS"
    formatter.timeZone = TimeZone(abbreviation: "CDT")
    let currentTimeString = formatter.string(from: Date())
    return ["AmericaTime": currentTimeString]
}

3.4 Record the Duration of the Event

If you need to record the duration of an event, you can call timeEventto start timing, configure the event type you want to time, and when you upload the event, you will automatically add #durationto your event attribute to indicate the duration of the recording, in seconds.

// Start timing with events recorded as "product_view"
[instance timeEvent:@"product_view"];

//Other codes...

// Upload Event, Clock Ended，"product_view" this event will have the attribute'#duration'indicating the length of the event
[instance track:@"product_view"];

// Start timing with events recorded as "product_view"
instance.timeEvent("product_view")

// Other codes...

// Upload Event, Clock Ended，"product_view" this event will have the attribute'#duration'indicating the length of the event
instance.track("product_view")

IV. User Features

The TA platform currently supports the user feature setting interface as user_set:, user_setOnce:, user_add:, user_unset:, user_deleteand user_append

4.1 User_set

For general user features, you can call user_set:to set it up. The attributes uploaded using this interface will overwrite the original attribute values. If the user feature does not exist before, the new user feature will be created. The type is the same as the type of the passed-in attribute

// Set User Properties
[instance user_set:@{@"UserName": @"TA", @"Age": @20}];

// Set User Properties
instance.user_set(["UserName": "TA", "Age": 20])

user_set: The user feature set is an NSDictionary object where each element represents an attribute.

The user feature format set by user_set requires consistency with event properties.

4.2 User_setOnce

If the user feature you want to upload only needs to be set once, you can call user_setOnce:to set it. When the attribute has a value before, this information will be ignored.

// Set user name
[instance user_setOnce:@{@"UserName": @"TA"}];
// Now the user name is TA

[instance user_setOnce:@{@"UserName": @"ABC"}];
// The user name is still TA and this data is ignored

// Set user name
instance.user_setOnce(["UserName": "TA"])
// Now the user name is TA

instance.user_setOnce(["UserName": "ABC"])
// The user name is still TA and this data is ignored

The user feature format set by user_setOnce requires consistency with event properties.

4.3 User_add

When you want to upload a numeric attribute, you can call user_add:to accumulate the attribute. If the attribute has not been set, a value of 0 will be assigned before calculation

// Set Accumulated Payment Amount
[instance user_add:@{@"TotalRevenue": @6}];
// Accumulated Payment Value at this time is 6

[instance user_add:@{@"TotalRevenue": @30}];
// Now the cumulative payment value is 36

// Sett Accumulated Payment Amount
instance.user_add(["TotalRevenue": 6])
// Accumulated Payment Value at this time is 6

instance.user_add(["TotalRevenue": 30])
// Now the cumulative payment value is 36

user_add: The property types and key values are set with the same limits as user_set:, but Value only allows NSNumbers.

4.4 User_unset

When you want to empty a user feature value of a user, you can call user_unset:to empty the specified attribute. If the attribute has not been created in the cluster, then user_unset: **will not **create the attribute

// Empty the user's attributed value of the accumulated payment amount
[instance user_unset:@"TotalRevenue"];

// Empty the user's attributed value of the accumulated payment amount
instance.user_unset("TotalRevenue")

The incoming value of user_unset: is the Key value of the emptied property.

4.5 User_delete

If you want to delete a user, you can call user_deleteto delete the user. You will no longer be able to query the user features of the user, but the events generated by the user can still be queried

[instance user_delete];

instance.user_delete()

4.6 User_append

Starting with v2.4.0, you can call user_appendto append to user features of type NSArray.

// Use user_ Append is the user attribute product_ Buy additional elements. If not, the element is created
[instance user_append:@{@"product_buy": @[@"product_name1", @"product_name2"]}];

instance.user_append(["product_buy": ["product_name1", "product_name2"]])

V. Automatic Acquisition Events

Please refer to the chapter iOS SDK Auto Capture Guide for details on how to use auto capture events.

VI. SDK Configuration

6.1 Set Uploaded Network Conditions

By default, the SDK will upload data in 2G, 3G, 4G, 5G and Wifi. You can modify the network conditions that allow uploading by the following methods:

// Upload data on 2G, 3G, 4G, 5G and Wifi
[instance setNetworkType:TDNetworkTypeALL];

// Report data only in Wifi environment
[instance setNetworkType:TDNetworkTypeOnlyWIFI];

// Upload data on 2G, 3G, 4G, 5G and Wifi with default settings
[instance setNetworkType:TDNetworkTypeDefault];

// Upload data on 2G, 3G, 4G, 5G and Wifi
ThinkingAnalyticsSDK.sharedInstance()?.setNetworkType(ThinkingAnalyticsNetworkType.TDNetworkTypeALL)

// Report data only in Wifi environment
ThinkingAnalyticsSDK.sharedInstance()?.setNetworkType(ThinkingAnalyticsNetworkType.TDNetworkTypeOnlyWIFI)

// Upload data on 2G, 3G, 4G, 5G and Wifi with default settings
ThinkingAnalyticsSDK.sharedInstance()?.setNetworkType(ThinkingAnalyticsNetworkType.TDNetworkTypeDefault)

6.2 Pause/stop Data Reporting

In v2.1.0 version, the function of stopping SDK reporting data has been added. There are two types of interfaces to stop SDK reporting:

6.2.1 Pause SDK reporting (enableTracking)

You may want to temporarily stop SDK data collection and reporting in some scenarios, such as the user is in a test environment, or the user logged in to a test account. At this time, you can call the following interfaces to temporarily stop SDK reporting.

You can call enableTracking:through an instance (including the main instance and the light instance) to pause the reporting of the SDK by passing in false. The #distinct_id, #account_id, public attributes that have been set by the instance will be retained; the data that has been collected but has not been successfully reported by the instance will continue to try to report; the subsequent instance cannot collect and report any new data, cannot set visitor ID, account ID, and public attributes, etc., but can read the instance The public attributes and device ID, visitor ID, account ID and other information that have been set.

The stop state of the instance will be saved in the local cache until the call to enableTracking:and the incoming true, the SDK instance will resume data collection and reporting. It should be noted that the light instance is not cached, so every time after opening the APP, the pause state of the light instance will not be retained, and the reporting will be reopened.

// Pause reporting
[instance enableTracking:NO];

// Restore reporting
[instance enableTracking:YES];

// Pause reporting
instance.enableTracking(false)

// Restore reporting
instance.enableTracking(true)

6.2.2 Stop SDK Reporting (optOutTracking)

In some special situations, you may need to completely stop the functions of the SDK. For example, in areas where GDPR is applicable, users choose not to provide data collection permissions, you can call the following interface to completely turn off the functions of the SDK.

OptOutTrackingcan only be called through the main instance. The biggest difference with enableTrackingis that it will empty the local cache of this instance, including the guest ID, account ID, public attributes, and unreported data queues of this instance. Then turn off the collection and reporting functions of this instance.

// Stop reporting and reset local caching
[instance optOutTracking];

// Stop reporting and reset local caching
instance.optOutTracking()

If you want to delete the user's user data in the TA group while turning off the SDK function, you can use optOutTrackingAndDeleteUser, which will report a piece of user_deldata before stopping the function of the SDK instance to delete the user's user data.

// Stop reporting and send delete user request
[instance optOutTrackingAndDeleteUser];

// Stop reporting and send delete user request
instance.optOutTrackingAndDeleteUser()

The stop state of the instance will also be saved in the local cache until the optInTrackingis called, and subsequent reports can continue, but this is equivalent to a completely new instance

// Re-start reporting
[instance optInTracking];

// Re-start reporting
instance.optInTracking()

6.3 Print Data Log

You can use setLogLevelto turn it on (it is off by default):

[ThinkingAnalyticsSDK setLogLevel:TDLoggingLevelDebug];
// TDLoggingLevelError :Error Log
// TDLoggingLevelInfo  :Info  Log
// TDLoggingLevelDebug :Debug Log

ThinkingAnalyticsSDK.setLogLevel(TDLoggingLevel.debug)
// TDLoggingLevel.error :Error Log
// TDLoggingLevel.info  :Info  Log
// TDLoggingLevel.debug :Debug Log

6.4 Get the Device ID

In v2.0.0, an interface was added to get the device ID (that is, the preset attribute #device_id). You can get the device ID by calling getDeviceId:

[instance getDeviceId];

 // If you need to set the device ID to the visitor ID, you can call it as follows
 // [instance identify:[instance getDeviceId]];

6.5 Configure HTTPS Verification Method:

Starting from v2.3.0, the SDK can configure HTTPS verification methods. You need to first obtain the TDConfig instance during initialization, and then use TDConfig to complete the initialization.

 TDConfig *config = [[TDConfig alloc] init];
 TDSecurityPolicy *securityPolicy = [TDSecurityPolicy policyWithPinningMode:TDSSLPinningModeNone];
 // TDSSLPinningModeNone:The default authentication method only validates the certificates returned by the server in the trusted certificate list of the system
 // TDSSLPinningModePublicKey:Public Key of Proofreading Certificate
 // TDSSLPinningModeCertificate:All contents of proofreading certificate
 securityPolicy.allowInvalidCertificates = YES; // Allow self-built certificates or expired SSL certificates, default NO
 securityPolicy.validatesDomainName = NO; // Whether to verify the certificate domain name, default YES
 config.securityPolicy = securityPolicy;
 [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];

let tdconfig = TDConfig();
let tdSecurityPolicy = TDSecurityPolicy(pinningMode: TDSSLPinningMode.publicKey);
// TDSSLPinningMode [] The default authentication method only validates the certificates returned by the server in the trusted certificate list of the system
// TDSSLPinningMode.publicKey Public Key of Proofreading Certificate
// TDSSLPinningMode.certificate All contents of proofreading certificate
tdSecurityPolicy.allowInvalidCertificates = true // Allow self-built certificates or expired SSL certificates, default NO
tdSecurityPolicy.validatesDomainName = false // Whether to verify the certificate domain name, default YES
tdconfig.securityPolicy = tdSecurityPolicy;
ThinkingAnalyticsSDK.start(withAppId: "YOUR_APPID", withUrl: "YOUR_SERVER_URL", with: tdconfig);

6.6 Set the Default Time Zone

By default, if the user does not specify an event occurrence time, the SDK reports the event occurrence time by default using the native time of the interface call. Since v2.3.1, you can also specify the default time zone by setting the default time zone interface, so that all events (including automatic collection events) will align the event time according to the time zone you set:

// Get an example of TDConfig
TDConfig *config = [[TDConfig alloc] init];
// Set default time zone to UTC
config.defaultTimeZone = [NSTimeZone timeZoneWithName:@"UTC"];
// Initialise SDK
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];

Note: Aligning the event time with the specified time zone will lose the device native time zone information. If you need to retain the device native time zone information, you currently need to add relevant attributes for the event yourself.

6.7 Turn on Debug mode

Starting from v2.4.0, the client side SDK supports Debug mode and needs to be used with TA platform versions after 2.5.

Debug mode may affect the quality of data collection and the stability of the app. It is only used for data verification during the integration phase and should not be used in online environments.

The current SDK instance supports three operating modes, defined in TDConfig:

/**
Debug Mode

- ThinkingAnalyticsDebugOff : Default does not open Debug mode
*/
typedef NS_OPTIONS(NSInteger, ThinkingAnalyticsDebugMode) {
    /**
     Default does not open Debug mode
     */
    ThinkingAnalyticsDebugOff      = 0,

    /**
     Open Debug_ Only mode, only verify the data, will not be stored
     */
    ThinkingAnalyticsDebugOnly     = 1 << 0,

    /**
     Debug mode, data is reported item by item. Alert users with logs and exceptions when problems occur
     */
    ThinkingAnalyticsDebug         = 1 << 1
};

To set the SDK instance running mode, use TDConfigto complete the SDK initialization:

// Get an example of TDConfig
TDConfig *config = [[TDConfig alloc] init];
// Set Running Mode to Debug Mode
config.debugMode = ThinkingAnalyticsDebug;
// Initialise SDK
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];

In order to prevent Debug mode from going live in the production environment, it is stipulated that only specified devices can turn on Debug mode. Debug mode can only be enabled on the client side, and the device ID is configured in the "Debug Data" section of the 'Event tracking management' page in the background of the TA.

The device ID can be obtained in three ways:

• #device_id attribute in event data in TA platform
• Client side log: The device DeviceId will be printed after the SDK initialization is completed
• Called through the instance interface: get device ID

6.8 Calibration Time

The SDK will use the original time as the event occurrence time by default. If the user manually modifies the device time, it will affect your business analysis. Starting from version v2.5.0, you can use the current timestamp obtained from the server level to calibrate the SDK's time. After that, all calls to the specified time, including event data and user feature setting operations, use the calibrated time as the time of occurrence.

// 1585633785954 is the current UNIX time stamp in milliseconds, corresponding to Beijing time 2020-03-31 13:49:45
[ThinkingAnalyticsSDK calibrateTime:1585633785954];

// 1585633785954 is the current UNIX time stamp in milliseconds, corresponding to Beijing time 2020-03-31 13:49:45
ThinkingAnalyticsSDK.calibrateTime(1585633785954)

We also provide the ability to get time-to-SDK calibration from NTP. You need to pass in an NTP server address that your users can access. The SDK then tries to get the current time from the incoming NTP service address and calibrates the SDK time. If the correct return result is not obtained within the default timeout time (3 seconds), the data will be reported using the local time later.

// Time Calibration Using Apple NTP Service
[ThinkingAnalyticsSDK calibrateTimeWithNtp:@"time.apple.com"];

ThinkingAnalyticsSDK.calibrateTime(withNtp: "time.apple.com")

Note:

• You need to choose your NTP server address carefully to ensure that the user equipment can get the server time quickly when the network is in good condition.
• There is some uncertainty in using the NTP service for time calibration. It is recommended that you give priority to using timestamp calibration.

In addition to the above calibration time interface, v2.5.0 provides time function overloading for all user feature interfaces. When you call the user feature related interface, you pass in the Date object, and the system will use the incoming Date object to set the data #timefield.

VII. Relevant Preset Attributes

7.1 Preset Properties for All Events

The following preset properties are the preset properties that all events in the iOS SDK, including AutoCollect events, carry

Attribute name	Chinese name	Description
#ip	IP address	The user's IP address, which the TA will use to obtain the user's geographic location information
#country	Country	User's country, generated according to IP address
#country_code	Country code	The country code of the country where the user is located (ISO 3166-1 alpha-2, that is, two uppercase English letters), generated based on the IP address
#province	Province	The user's province is generated according to the IP address
#city	City	The user's city is generated according to the IP address
#os_version	Operating system version	iOS 11.2.2、Android 8.0.0 等
#manufacturer	Equipment manufacturer	Manufacturers of user equipment, such as Apple, vivo, etc
#os	Operating system	Such as Android, iOS, etc
#device_id	Device ID	The user's device ID, iOS take the user's IDFV or UUID, Android takes androidID
#screen_height	Screen height	The screen height of the user equipment, such as 1920, etc
#screen_width	Screen width	The screen height of the user equipment, such as 1080, etc
#device_model	Equipment model	The model of the user equipment, such as iPhone 8, etc
#app_version	App version	Version of your app
#bundle_id	Application unique identification	Application package name
# lib	SDK type	The type of SDK you access, such as Android, iOS, etc
#lib_version	SDK version	The version you access to the SDK
#network_type	Network status	Network status when uploading events, such as WIFI, 3G, 4G, etc
#carrier	Network Operator	Network operators of user equipment, such as China Mobile, China Telecom, etc
#zone_offset	Time zone offset	The number of hours the data time is offset from UTC time

7.2 Preset Properties for Automatic Acquisition Events

The following preset properties are unique to each AutoCapture event

• Preset properties for APP launch event (ta_app_start)

Attribute name	Chinese name	Description
#resume_from_background	Whether to wake up from the background	Indicates whether the APP is turned on or woken up from the background, the value of true indicates waking up from the background, and false is directly turned on

• Preset properties for APP shutdown events (ta_app_end)

Attribute name	Chinese name	Description
#duration	Event duration	Represents the duration of the APP access (from start to end) in seconds

• Preset properties for APP browsing page events (ta_app_view)

Attribute name	Chinese name	Description
#title	Page Title	For the title of the View Controller, take the value of the controller.navigation I tem.title attribute
#screen_name	Page name	Class name for View Controller
#url	Page address	The address of the current page, you need to call getScreenUrl to set the url
#referrer	Forward address	The address of the page before the jump, the page before the jump needs to call getScreenUrl to set the url

• Preset properties for APP control click events (ta_app_click)

Attribute name	Chinese name	Description
#title	Page Title	For the title of the View Controller, take the value of the controller.navigation I tem.title attribute
#screen_name	Page name	Class name for View Controller
#element_id	Element ID	Control ID, need thinkingAnalyticsViewID to set
#element_type	Element type	Type of control
#element_selector	Element selector	Splicing for the viewPath of a control
#element_position	Element position	Control location information, only if the widget type is UITableView or UICollectionView will exist, indicating the position where the control was clicked, the value is Group Number (Section): Line Number (Row)
#element_content	Element content	Content on the control

• Preset properties for APP crash events (ta_app_crash)

Attribute name	Chinese name	Description
#app_crashed_reason	Abnormal information	Character type to record the stack trajectory when crashing

7.3 Other Preset Properties

In addition to the preset attributes mentioned above, there are also some preset attributes that need to call the corresponding interface to be recorded:

Attribute name	Chinese name	Description
#duration	Event duration	You need to call the timing function interface timeEvent: to record the duration of the event, in seconds
#background_duration	Duration of backstage stay	#background_duration v2.7.4, new attribute. This attribute will only exist in startup events and duration events, in seconds

7.4 Get Preset Properties

V2.7.0 and later can call the getPresetPropertiesmethod to obtain preset properties.

When server level event tracking requires some preset properties of the App side, you can obtain the preset properties of the App side through this method and then pass them to the server level.

//Get Property Object
TDPresetProperties *presetProperties = [instance getPresetProperties];

//Generate event preset properties
NSDictionary *properties = [presetProperties toEventPresetProperties];
/*
   {
	"#carrier": "China Telecom",
	"#os": "iOS",
	"#device_id": "A8B1C00B-A6AC-4856-8538-0FBC642C1BAD",
	"#screen_height": 2264,
	"#bundle_id": "com.sw.thinkingdatademo",
	"#manufacturer": "Apple",
	"#device_model": "iPhone7",
	"#screen_width": 1080,
	"#system_language": "zh",
	"#os_version": "10",
	"#network_type": "WIFI",
	"#zone_offset": 8
    }
*/

//Get a preset property
NSString *bundle_id = presetProperties.bundle_id;//name
NSString *os = presetProperties.os;//os type，as iOS
NSString *system_language = presetProperties.system_language;//Phone System Language Type
NSNumber *screen_width = presetProperties.screen_width;//Screen Width
NSNumber *screen_height = presetProperties.screen_height;//Screen Height
NSString *device_model = presetProperties.device_model;//Device Model
NSString *device_id = presetProperties.device_id;//Unique Identification of Device
NSString *carrier = presetProperties.carrier;//Operator information for SIM card, operator information for master card with dual cards and dual standby
NSString *manufacture = presetProperties.manufacturer;//Mobile phone manufacturers such as Apple
NSString *network_type = presetProperties.network_type;//Network Type
NSString *os_version = presetProperties.os_version;//System Version Number
NSNumber *zone_offset = presetProperties.zone_offset;//Time zone offset

let presetProperties = instance.getPresetProperties();

//Generate event preset properties
let properties = presetProperties.toEventPresetProperties();

//Get a preset property
let bundle_id = presetProperties.bundle_id;//包名
let os = presetProperties.os;//os类型，如iOS
let system_language = presetProperties.system_language;// Phone System Language Type
let screen_width = presetProperties.screen_width;// Screen Width
let screen_height = presetProperties.screen_height;//Screen Height
let device_model = presetProperties.device_model;//Device Model
let device_id = presetProperties.device_id;//Unique Identification of Device
let carrier = presetProperties.carrier;// Operator information for SIM card, operator information for master card with dual cards and dual standby
let manufacture = presetProperties.manufacturer;//Mobile phone manufacturers such as Apple
let network_type = presetProperties.network_type;// Network Type
let os_version = presetProperties.os_version;//System Version Number
let zone_offset = presetProperties.zone_offset;// Time zone offset

IP, country city information is generated by server level parsing, and the client side does not provide an interface to obtain these attributes

7.5 Performance Indicators Prefabricated Attributes

Starting with v2.7.4, the SDK reports performance-related prefab attributes by default:

Attribute name	Chinese name	Description
#ram	Available memory size/total memory	Unit is GB
#disk	Available disk capacity/total disk volume	Unit is GB
# fps	FPS	Plastic surgery
#simulator	Is it a mobile emulator?	Boolean value
#install_time	Application installation time

7.6 Prefabricated Attribute Switches

Starting with v2.7.4, the SDK supports masking reports of specified prefab attributes.

Add the **TDDisPresetProperties **field to the info.plist file of the project, the type is Array, and the preset properties corresponding to the added fields will not be uploaded.

Such as shielding "#fps", @"#ram", @"#disk", @"#start_reason", @"#simulator" and other prefabricated attributes, the configuration is as follows:

VIII. Advanced Functions

Starting from v2.6.0, the SDK supports the reporting of three special types of events: first events, updatable events, and rewritable events. These three events need to be used in conjunction with TA system 2.8 and later versions. Since special events are only applicable in certain specific scenarios, please use special events to report data with the help of Count Technology's customer success and analysts.

8.1 First Incident

First-time events are events that are recorded only once for an ID of a device or another dimension. For example, in some scenarios, you may want to record the first event on a device, so you can use first-time events to report data.

// Instance: Report device first event assuming the event name is DEVICE_FIRST
TDFirstEventModel *firstModel = [[TDFirstEventModel alloc] initWithEventName:@"DEVICE_FIRST"];

// Optional parameters
firstModel.properties = @{};
[firstModel configTime:[NSDate date] timeZone:[NSTimeZone localTimeZone]];

// Report Event API
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:firstModel];

// Instance: Report device first event assuming the event name is DEVICE_FIRST
let firstModel = TDFirstEventModel(eventName:"DEVICE_FIRST")
// Optional parameters
firstModel.properties = ["KEY": "VALUE"]
firstModel.configTime(Date(), timeZone: NSTimeZone.local)
// Report Event API
ThinkingAnalyticsSDK.sharedInstance()?.track(with: firstModel)

If you want to determine whether it is the first time in a dimension other than the device, you can set FIRST_CHECK_ID for the first event. For example, if you need to record the first event of an account, you can set the account ID to the FIRST_CHECK_ID of the first event:

// Customize #first_ Check_ Construction method of ID
TDFirstEventModel *firstModel = [[TDFirstEventModel alloc] initWithEventName:@"DEVICE_FIRST" firstCheckID:@"YOUR_ACCOUNT_ID"];

// Optional parameters
firstModel.properties = @{};
[firstModel configTime:[NSDate date] timeZone:[NSTimeZone localTimeZone]];

// Report Event API
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:firstModel];

// Instance: Report device first event assuming the event name is DEVICE_FIRST
let firstModel = TDFirstEventModel(eventName:"DEVICE_FIRST", firstCheckID:"YOUR_ACCOUNT_ID")
// Optional parameters
firstModel.properties = ["KEY": "VALUE"]
firstModel.configTime(Date(), timeZone: NSTimeZone.local)
// Report Event API
ThinkingAnalyticsSDK.sharedInstance()?.track(with: firstModel)

Note: Due to the completion of the verification of whether it is the first time at the server level, the first event will be delayed for 1 hour.

8.2 Updatable Events

You can implement the need to modify event data in a specific scenario through updatable events. Updatable events need to specify an ID that identifies the event and pass it in when you create an updatable event object. The TA will determine the data that needs to be updated based on the event name and event ID.

// Instance: Report an event that can be updated, assuming the event name is UPDATABLE_ EVENT
TDUpdateEventModel *updateModel = [[TDUpdateEventModel alloc] initWithEventName:@"UPDATABLE_EVENT" eventID:@"test_event_id"];
updateModel.properties = @{@"status": @3, @"price": @100};
// Event attributes after reporting are status 3 and price 100
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:updateModel];

TDUpdateEventModel *updateModel_new = [[TDUpdateEventModel alloc] initWithEventName:@"UPDATABLE_EVENT" eventID:@"test_event_id"];
updateModel_new.properties = @{@"status": @5};
// Event attributes status is updated to 5 after reporting, price remains unchanged
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:updateModel_new];

// Instance:Report an event that can be updated, assuming the event name is UPDATABLE_ EVENT
let updateModel = TDUpdateEventModel(eventName: "UPDATABLE_EVENT", eventID: "test_event_id")
updateModel.properties = ["status": 3, "price": 100]

// Optional parameters
updateModel.configTime(<#T##time: Date##Date#>, timeZone: <#T##TimeZone?#>)

// Event attributes after reporting are status 3 and price 100
ThinkingAnalyticsSDK.sharedInstance()?.track(with: updateModel)


let updateModel_new =TDUpdateEventModel(eventName: "UPDATABLE_EVENT", eventID: "test_event_id")
updateModel_new.properties = ["status": 5]
// Event attribute status is 5 after reporting, price remains unchanged
ThinkingAnalyticsSDK.sharedInstance()?.track(with: updateModel_new)

8.3 Rewritable Events

Rewritable events are similar to updatable events, except that rewritable events will completely cover historical data with the latest data, which is equivalent to deleting the previous data and storing the latest data in effect. The TA background will determine the data that needs to be updated based on the event name and event ID.

// Instance: Report an event that can be overridden, assuming the event name is OVERWRITE_ EVENT
TDOverwriteEventModel *overwriteModel = [[TDOverwriteEventModel alloc] initWithEventName:@"OVERWRITE_EVENT" eventID:@"test_event_id"];
overwriteModel.properties = @{@"status": @3, @"price": @100};
// Event attributes after reporting are status 3 and price 100
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:overwriteModel];

TDOverwriteEventModel *overwriteModel_new = [[TDOverwriteEventModel alloc] initWithEventName:@"OVERWRITE_EVENT" eventID:@"test_event_id"];
overwriteModel_new.properties = @{@"status": @5};
// Event attribute status is 5 after reporting and price attribute is deleted
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:overwriteModel_new];

// Instance: Report an event that can be overridden, assuming the event name is OVERWRITE_ EVENT
let overwriteModel = TDOverwriteEventModel(eventName: "OVERWRITE_EVENT", eventID: "test_event_id")
overwriteModel.properties = ["status": 3, "price": 100]

// Optional parameters
overwriteModel.configTime(<#T##time: Date##Date#>, timeZone: <#T##TimeZone?#>)

// Event attributes after reporting are status 3 and price 100
ThinkingAnalyticsSDK.sharedInstance()?.track(with: overwriteModel)


let overwriteModel_new = TDOverwriteEventModel(eventName: "UPDATABLE_EVENT", eventID: "test_event_id")
overwriteModel_new.properties = ["status": 5]
// Event attribute status is 5 after reporting, price is deleted
ThinkingAnalyticsSDK.sharedInstance()?.track(with: overwriteModel_new)

ChangeLog

v2.7.4 2022/01/18

• Code optimization
• Add prefabricated attributes such as startup reason and performance indicators

v2.7.3 2021/11/09

• Support for complex data types

v2.7.2 2021/08/18

• Code optimization
• Optimize installation event acquisition logic

v2.7.1 2021/07/21

• Code optimization

v2.7.0 2021/06/16

• Support preset attribute acquisition
• Code optimization

v2.6.5 2021/04/19

• Code optimization

v2.6.4 2021/03/15

• Added preset property #bundle_id (application package name)
• Adaptation iOS 14

v2.6.3 2021/01/18

• Optimized to get network type logic

v2.6.2 2020/10/29

• Adapt to 5G network
• Optimize install, start event reporting logic
• Optimized data transfer format
• Default network reporting policy adjusted to 2G/3G/4G/5G/WIFI

v2.6.1 2020/08/25

• Fix the logic of setting timeZone for special events. Now the data reported without timeZone will no longer have #zone_offset = 0.

v2.6.0 2020/08/24

• Supports first-time events, allowing custom ID checks to be passed in to verify whether it is reported for the first time
• Supports updatable, rewritable events

v2.5.6 2020/08/11

• Optimize the time calibration API, now multiple calls will take effect multiple times.

v2.5.5 2020/06/23

• Fix some models #system_language anomalies

v2.5.4 2020/06/22

• 修复 v2.5.3 undeclared selector 'applicationWillTerminateNotification:' [-Wundeclared-selector]

v2.5.3 2020/06/22

• Added preset property #system_language
• Fixed preset property #os to "iOS"
• Optimize code

v2.5.2 2020/05/15

• Fix the problem that Debug mode will be degraded due to data format errors in v2.5.1

v2.5.1 2020/05/14

• Adapt TA version 2.7 shielding event configuration interface
• Adjust DEBUG mode to remove client side exception throwing logic

v2.5.0 2020/04/03

• Support time calibration function of client SDK
• Added user feature interface for specified time
• Code optimization

v2.4.3 2020/03/11

• Remove UIWebView related code

v2.4.2 2020/03/09

• Data is normally reported at intervals during delayed initialization
• Code optimization

v2.4.1 2020/02/21

• Fix the bug introduced by v2.3.0, v2.3.1, v2.4.0

v2.4.0 2020/02/10

• Supports NSArray types
• Add user_append interface
• Remove the client attribute format check

v2.3.1 2020/01/07

• Support configuring default time zone

v2.3.0 2019/12/31

• Support Debug mode: need to cooperate with the background Debug device whitelist to open together
• H5 and original SDK open support multiple instances
• Optimize SDK configuration: increase global settings; reporting policy allows configuration for different projects
• Support for configuring HTTPS certificate verification

v2.2.2 2019/12/01

• Fix the problem that when using EnableSceneSupport, the attribute #resume_from_backgroundin the APP startup event ( ta_app_install) has an abnormal value

v2.2.1 2019/11/22

• Remove UIWebView related content by default according to Appstore ITMS-90809

v2.2.0 2019/10/21

• Added user_unsetinterface to clear a user feature
• Added preset property #zone_offsetin hours. By default, the offset of the local time zone is reported to the server level, which is affected by daylight saving time. The following formula is satisfied:

utc_time + #zone_offset = #event_time

v2.1.1 2019/10/11

• Optimize the reporting logic to solve the problem of abnormal data reporting in extreme cases

v2.1.0 2019/09/16

• Supports lightweight instances to facilitate reporting of passive events and other requirements
• Added enableTracking interface, you can turn on or off the instance reporting function
• Added optOutTracking/optInTracking interface
• Other code optimizations

v2.0.1 2019/07/15

• Adjusted the trigger sequence of the ta_app_install (APP installation event) in the automatic collection event, which will now be triggered before the ta_app_start (APP startup event)

v2.0.0 2019/07/12

• Automatic collection of events Add APP installation events
• By default, the data generated when the background self-start is not collected, and the background self-start interface will be added later to control whether to collect the data generated when the background self-start

v1.2.0 2019/06/20

• Add multiple APPID instance function
• Added dynamic public attribute feature
• Automatically collect events Add APP crash events