Skip to main content

macOS

Last updated 10/03/2026
tip

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

The macOS SDK requires OSX 10.11 or later

Latest version: v3.0.4

Update time: 2024-08-01

Downloads: Source code

Beta version: v3.0.5-beta.1

Note

The iOS SDK has supported the macOS platform since v3.0.0

1. Integrate the SDK​

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 :osx, '10.10'
target 'YourProjectTarget' do
  pod 'ThinkingSDK'
end

2. Run the install command

pod install

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 SDK. Open the .xcworkspace file to open the project (note: don't open the .xcodeproj file at the same time)

2. Initialization​

Initialize the SDK on the main thread. The sample code is as follows:

#import <ThinkingSDK/ThinkingSDK.h>

// SDK needs to be initialized on the main thread

NSString *appid = @"APPID";
NSString *url = @"SERVER_URL";
    
// the first way
[TDAnalytics startAnalyticsWithAppId:appid serverUrl:url];
    
// the second way
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 the AE backend

  • 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 generates a random number as the distinct ID and stores 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 user's identifier, and the account ID 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 the string type. It must start with a letter, can contain only digits, letters, and underscores "_", and can be up to 50 characters long. Keys are not case-sensitive; AE converts all letters 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 Send events​

You can call track to upload events. We recommend setting event properties and the conditions for sending them according to the tracking plan you prepared earlier. The following example tracks a user purchasing a product:

// Upload a product purchase event
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.4 Set user properties​

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

// "username" is "ThinkingData"
[TDAnalytics userSet:@{@"username": @"ThinkingData"}];
// "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 (privacy policy authorized) {
    // enable log
    [TDAnalytics enableLog:NO];
    
    // SDK needs to be initialized on the main thread
    NSString *appid = @"APPID";
    NSString *url = @"SERVER_URL";
    TDConfig *config = [[TDConfig alloc] init];
    config.appid = appid;
    config.serverUrl = url;
    [TDAnalytics startAnalyticsWithConfig:config];
    
    [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];
    
    // "username" is "ThinkingData"
    [TDAnalytics userSet:@{@"username": @"ThinkingData"}];
}
Was this page helpful?
On this page