Multiple instances

Last updated 10/05/2026

1. Multi-instance overview

iOS SDK 1.2.0 added support for multiple APPIDs. You can create multiple SDK instances, each reporting data to its own APPID, so you can report data to multiple APPIDs.

iOS SDK 2.1.0 added light instances. You can generate multiple child light instances for the same APPID. A child light instance has the same APPID as its parent instance, but different account and other information.

If you upgrade an old SDK (earlier than 1.2.0) to 1.2.0 or later and the old SDK still has unreported data in its local cache, that data is reported directly to the first instantiated APPID. If you use only one APPID instance, your data is not affected in any way.

2. Create multiple SDK instances

This section describes how to use multiple SDK instances:

[TDAnalytics enableLog:YES];

NSString *appId_1 = @"appId_1";
NSString *receiverUrl_1 = @"https://receiver-ta-preview.thinkingdata.cn";
[TDAnalytics startAnalyticsWithAppId:appId_1 serverUrl:receiverUrl_1];

NSString *appId_2 = @"appId_2";
NSString *receiverUrl_2 = @"https://receiver-ta-preview.thinkingdata.cn";
[TDAnalytics startAnalyticsWithAppId:appId_2 serverUrl:receiverUrl_2];

[TDAnalytics calibrateTimeWithNtp:@"time.apple.com"];

[TDAnalytics login:@"TD" withAppId:appId_1];
[TDAnalytics login:@"TD" withAppId:appId_2];

[TDAnalytics setDistinctId:@"Thinker" withAppId:appId_2];

// Set static super properties
[TDAnalytics setSuperProperties:@{@"channel": @"ta",} withAppId:appId_1];
[TDAnalytics setSuperProperties:@{@"channel": @"ta",} withAppId:appId_2];
[TDAnalytics unsetSuperProperty:@"isTest" withAppId:appId_1];
[TDAnalytics clearSuperPropertiesWithAppId:appId_1];
[TDAnalytics getSuperPropertiesWithAppId:appId_1];
[TDAnalytics setDynamicSuperProperties:^NSDictionary * _Nonnull{
    return @{@"now": [NSDate date]};
} withAppId:appId_1];

//Enable auto-tracking
[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAppInstall | TDAutoTrackEventTypeAppStart | TDAutoTrackEventTypeAppEnd withAppId:appId_1];
// Ignore auto-tracked events on a page
[TDAnalytics ignoreAutoTrackViewControllers:@[] withAppId:appId_1];
[TDAnalytics setAutoTrackProperties:TDAutoTrackEventTypeAll properties:@{@"auto_key2": @"auto_value2"} withAppId:appId_1];

// Report a regular event
[TDAnalytics track:@"product_buy" withAppId:appId_1];

// Report a first event
TDFirstEventModel *firstModel = [[TDFirstEventModel alloc] initWithEventName:@"device_activation" firstCheckID:@"TD"];
firstModel.properties = @{@"key":@"value"};
[TDAnalytics trackWithEventModel:firstModel withAppId:appId_1];

// Report an updatable event
TDUpdateEventModel *updateModel = [[TDUpdateEventModel alloc] initWithEventName:@"UPDATABLE_EVENT" eventID:@"test_event_id"];
updateModel.properties = @{@"status": @3, @"price": @100};
[TDAnalytics trackWithEventModel:updateModel withAppId:appId_1];

// Report an overwritable event
TDOverwriteEventModel *overwriteModel = [[TDOverwriteEventModel alloc] initWithEventName:@"OVERWRITE_EVENT" eventID:@"test_event_id"];
overwriteModel.properties = @{@"status": @3, @"price": @100};
[TDAnalytics trackWithEventModel:overwriteModel withAppId:appId_1];

// The following example measures how long a user stays on a product page
[TDAnalytics timeEvent:@"stay_shop" withAppId:appId_1];
/*
 do someting .......
 */
// The user leaves the product page and timing ends. The "stay_shop" event carries the #duration property, which indicates the event duration
[TDAnalytics track:@"stay_shop" withAppId:appId_1];

// Log out
[TDAnalytics logoutWithAppId:appId_1];

// User properties
[TDAnalytics userSet:@{@"username": @"ThinkingData"} withAppId:appId_2];
[TDAnalytics userSetOnce:@{@"first_payment_time": @"2018-01-01 01:23:45.678"} withAppId:appId_1];
[TDAnalytics userAdd:@{@"total_revenue": @30} withAppId:appId_1];
[TDAnalytics userUnset:@"key" withAppId:appId_1];
[TDAnalytics userDeleteWithAppId:appId_1];
[TDAnalytics userAppend:@{@"user_list": @[@"apple", @"ball"]} withAppId:appId_1];
[TDAnalytics userUniqAppend:@{@"user_list":@[@"apple", @"cube"]} withAppId:appId_1];

// Connect H5 page data
[TDAnalytics addWebViewUserAgent];

// Get the device ID
[TDAnalytics getDeviceId];

[TDAnalytics flushWithAppId:appId_1];

// Third-party data integration
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeAppsFlyer withAppId:appId_1];

Note that each SDK instance must have a different APPID, and most data is not shared between instances. For details, see Section 4, "Data and settings sharing between instances".

3. Create light instances

In iOS SDK 3.0.0 and later, you can call the lightInstanceIdWithAppId: API to create multiple instances under the same APPID as light instances

// Original project
NSString *appId = @"appId";
NSString *receiverUrl = @"https://receiver-ta-preview.thinkingdata.cn";
[TDAnalytics startAnalyticsWithAppId:appId serverUrl:receiverUrl];

// Create a light instance from the original project
NSString *lightProjectAppId = [TDAnalytics lightInstanceIdWithAppId:appId];
    
// Report an event
[TDAnalytics track:@"event" withAppId:lightProjectAppId];
    
// User properties
[TDAnalytics userSet:@{@"age": @18} withAppId:lightProjectAppId];

A child light instance has the same APPID, data receiving URL, and some settings as its parent instance, but other information is not shared. For details, see Section 4, "Data and settings sharing between instances".

4. Data and settings sharing between instances

Most APIs are called on instance objects, so most data and settings are not shared among instances with different APPIDs, or between a parent instance and its light instances. However, some data and settings take effect for all instances. The following describes whether each type of data and setting is shared among instances:

• Account information

  • Distinct ID #distinct_id generated by the system by default: shared
  • Distinct ID #distinct_id set by calling setDistinctId: not shared
  • Account ID #account_id set by calling login: not shared

• Event tracking track and user property operations userSet, userSetOnce, userAdd, and userDelete: not shared

• Super properties setSuperProperties and dynamic super properties setDynamicSuperProperties: not shared

• Whether SDK configuration is shared among instances:

  • Reporting strategy (the reporting interval and the amount of data in each batch): shared, determined by the project data of the APPID that is instantiated first
  • Network conditions for uploading setNetworkType: shared

• Auto-tracked events

  • We recommend enabling auto-tracked events on only one instance
  • Auto-tracked events can be reported to multiple APP IDs
  • Settings for auto-tracked events can take effect for a single APPID instance only. For details, see the iOS SDK auto-tracking guide

• Record event duration timeEvent: not shared