Skip to main content

iOS

Last updated 10/05/2026
tip

Before you integrate the SDK, read Pre-integration preparation.

The iOS SDK requires iOS 9.0 or later.

The iOS SDK (Framework format) is about 2.7 MB in size.

Latest version: v3.5.3

Update time: 2026-09-22

Downloads: Source code Download

Note

This document applies to v3.0.0 and later. For earlier versions, see iOS Integration Guide (V2) and SDK download (v2.8.4).

1. Integrate the SDK​

1.1 Automatic integration​

  • Install the SDK with CocoaPods

1. Create and edit the Podfile (if you already have one, edit it directly):

To create a Podfile, run the following command in the directory that contains the project file (.xcodeproj):

pod init

Edit the Podfile as follows:

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

2. In the root directory of the project, run the install command

pod install

After the installation succeeds, the terminal shows the following output:

Analyzing dependencies
Downloading dependencies
Installing ThinkingDataCore
Installing ThinkingSDK
Generating Pods project
Integrating client project
Pod installation complete! There is 1 dependency from the Podfile and 2 total pods installed.

3. After the import succeeds, open the project

After the command runs successfully, a .xcworkspace file is generated, which means that you have imported the iOS SDK. Open the .xcworkspace file to open the project (note: don't open the .xcodeproj file at the same time)

1.2 Manual integration​

1. Download and unzip the iOS SDK

2. Drag ThinkingSDK.xcframework and ThinkingDataCore.xcframework into your Xcode project workspace

3. Find Targets, and add -ObjC to the Other linker flags option in the Build Settings menu

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

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

2. Initialization​

#import <ThinkingSDK/ThinkingSDK.h>

NSString *appid = @"APPID";
NSString *url = @"SERVER_URL";
    
//Method 1
[TDAnalytics startAnalyticsWithAppId:appid serverUrl:url];
    
//Method 2
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
[TDAnalytics startAnalyticsWithConfig:config];

Parameters:

  • APPID: The APPID of your project, which you can find on the Project Settings page in AE

  • SERVER_URL: The URL that data is uploaded to

    • If you use the cloud service, enter: https://global-receiver-ta.thinkingdata.cn
    • If you use an on-premises deployment, bind a domain name to the data collection URL and configure an HTTPS certificate: https://your-domain-for-data-collection

3. Common features​

Before you use the common features, we recommend that you read the user identification rules. By default, the SDK uses DeviceID_InstallCount as the distinct ID and persists it locally. Before a user logs in, the distinct ID is used as the user's identifier. Note: The distinct ID changes when the user reinstalls the App or switches devices.

3.1 Set the account ID​

When a user logs in, you can call login to set the user's account ID. The AE platform uses the account ID as the identifier, and the account ID you set is kept until logout is called. Calling login multiple times overwrites the previous account ID.

// The user's unique login ID. It corresponds to #account_id in the reported data; here, the value of #account_id is TD
[TDAnalytics login:@"TD"];

This method does not upload a login event

3.2 Set super properties​

Super properties are properties that every event carries. You can call setSuperProperties to set super properties. We recommend setting super properties before you send events. Some important properties, such as a user's membership level and source channel, need to be set in every event; in this case, you can set them as super properties.

NSDictionary *superProperties = @{
    @"channel": @"ta",
    @"age": @1,
    @"isSuccess": @YES,
    @"birthday": [NSDate date],
    @"object": @{
        @"key":@"value"
    },
    @"object_arr":@[
        @{
            @"key":@"value"
        }
    ],
    @"arr": @[@"value"],
};
[TDAnalytics setSuperProperties:superProperties];

Super properties are saved in the cache, so you don't need to call this every time the App starts. If you call setSuperProperties to set a super property that was set before, the new value overwrites the previous one.

  • Event properties are an NSDictionary object, where each element represents a property.
  • Key is the name of the property and is of string type. It must start with a letter, can contain digits, letters, and underscores "_", can be up to 50 characters long, and is case-insensitive. AE converts it to lowercase
  • Value is the value of the property. Supported types are string, number, Boolean, time, object, object group, and array
  • To upload a Boolean property, assign it with @YES and @NO, or [NSNumber numberWithBool:YES] and [NSNumber numberWithBool:NO]. Do not use @true, @false, @TRUE, or @FALSE to assign Boolean data.

Event properties and user properties have the same requirements as super properties

3.3 Enable auto-tracking​

The following code example enables the install, start, and end events. To learn more about the SDK's auto-tracking capabilities, see Auto-tracked events

[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAppInstall | TDAutoTrackEventTypeAppStart | TDAutoTrackEventTypeAppEnd];

3.4 Send events​

You can call track to upload events. We recommend that you set event properties and the conditions for sending data based on your tracking plan. The following example tracks a user purchasing a product:

NSDictionary *eventProperties = @{@"product_name": @"book"};
[TDAnalytics track:@"product_buy" properties:eventProperties];

The event name is of the string type. It must start with a letter, can contain digits, letters, and underscores "_", and can be up to 50 characters long.

3.5 Set user properties​

For general user properties, you can call userSet to set them. Properties uploaded with this API overwrite the existing values. If the user property doesn't exist yet, it's created with the same type as the value passed in. The following example sets the user name:

//Now "username" is "ThinkingData"
[TDAnalytics userSet:@{@"username": @"ThinkingData"}];
//Now "username" is "TA"
[TDAnalytics userSet:@{@"username": @"TA"}];

4. Best practices​

The following sample code includes all of the operations above. We recommend using them in the following order:

if (user has accepted the privacy policy) {
    
    //Initialize the SDK
    NSString *appid = @"APPID";
    NSString *url = @"SERVER_URL";
    TDConfig *config = [[TDConfig alloc] init];
    config.appid = appid;
    config.serverUrl = url;
    [TDAnalytics startAnalyticsWithConfig:config];
    
    //Enable auto-tracking
    [TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAppInstall | TDAutoTrackEventTypeAppStart | TDAutoTrackEventTypeAppEnd];
    
    [TDAnalytics login:@"TD"];
    
    NSDictionary *superProperties = @{
        @"channel": @"ta",
        @"age": @1,
        @"isSuccess": @YES,
        @"birthday": [NSDate date],
        @"object": @{
            @"key":@"value"
        },
        @"object_arr":@[
            @{
                @"key":@"value"
            }
        ],
        @"arr": @[@"value"],
    };
    [TDAnalytics setSuperProperties:superProperties];
        
    NSDictionary *eventProperties = @{@"product_name": @"book"};
    [TDAnalytics track:@"product_buy" properties:eventProperties];
    
    [TDAnalytics userSet:@{@"username": @"ThinkingData"}];
}
Was this page helpful?
On this page