iOS

Last updated 10/03/2026

tip

The iOS SDK requires iOS 9.0 or later

Latest version: v1.3.1

Update time: 2026-07-24

Downloads: Download

Beta version: None

1. Overview

Starting from AE 4.4, the Engage module provides the Config Center feature, which lets you add feature parameter configurations in the AE backend and pull them to your app through the client SDK, so you can finely customize your interactions with players.

This article describes how to integrate the client SDK. On the app side, you only need to handle interactions with the ThinkingData SDK and don't need to care about task details in the AE backend.

2. SDK integration

2.1 Integrate the SDK automatically

1. Make sure that the CocoaPods package manager is installed on your computer

2. If your project doesn't have a Podfile, run the following command from the command line in the same directory as the project file (.xcodeproj):

   pod init

3. Edit the Podfile as follows:

   platform :ios, '9.0'
   target 'YourProjectTarget' do
     pod 'TDRemoteConfig'
   end

4. In the root directory of the project, run the installation command

   pod install

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

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

5. 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)

2.2 Integrate the SDK manually

Config Center depends on the following ThinkingData SDKs:

SDK name	Description	Version requirement
ThinkingSDK	Collects and processes data	>= 3.1.0
TDRemoteConfig	Fetches configuration from the AE backend	>= 1.0.0
ThinkingDataCore	Provides basic components	>= 1.1.0

1. Click the download link at the top of this page to download the SDK, and then unzip it
2. Drag ThinkingSDK.xcframework, ThinkingDataCore.xcframework, and TDRemoteConfig.xcframework into your XCode Project Workspace
3. Find Targets, and add -ObjC to the Other linker flags option in the Build Settings menu

3. Initialization

Initialize the SDK on the main thread

#import <ThinkingDataCore/ThinkingDataCore.h>

// SDK needs to be initialized on the main thread
// For details on how to configure TDSettings, see [Advanced guide]
TDSettings *settings = [[TDSettings alloc] init];
settings.mode = TDSDKModeNomal;
settings.appId = @"APPID";
settings.serverUrl = @"SERVER_URL";
[TDApp startWithSetting:settings];

4. Usage

4.1 Sample data structure

"configId" : {
    "templateId" : [
        {
         "#strategy_id" : "f712dff93afb1e79caefdf094bda4ba2",
          "paramater_x" : "1111",
          "#ops_receipt_properties" : {}
        }
    ],
    "#custom_params" : {

    }
}

Where:

configId: The Config ID created in the Config Center module of the Engage backend, used to identify the business module. For details about config items, see Config items

templateId: The Template ID that you add under Config Items, used to identify the specific feature module. For details about config templates, see Config templates

#strategy_id: The unique ID of the strategy, used for strategy lifecycle management. For details about config strategies, see Config strategies

paramater_x: A config template parameter, corresponding to a configuration parameter required by the feature module

#ops_receipt_properties: Used for event receipt statistics. When you need to automatically measure strategy effects (not supported yet), receipt events must carry this property

#custom_params: Custom parameters on the client config channel. You can define the user property information to be carried to the client.

4.2 Set local default values

You can set default values for config items in the TDRemoteConfig SDK. When a config item hasn't been added on the AE server, or the remote value hasn't been fetched locally, the SDK gets the local default value.

Format

Local default values must use the following format:

{
    "configId": {
        "templateId": [
            { 
              "paramater_x" : ""
            }
        ]
    }
}

Set directly

NSDictionary *params = @{
    @"configId": @{
        @"templateId": @[
            @{@"paramater_x" : @""}
        ]
    }
};
[TDRemoteConfig setDefaultValues:params];

Set from a local file

NSString *filePath = [[NSBundle mainBundle] pathForResource:fileName ofType:nil];
[TDRemoteConfig setDefaultValuesWithJsonFile:filePath];

Clear default values

[TDRemoteConfig clearDefaultValues];

4.3 Get values

Get the content of the released and online strategies of a certain type under a config item:

#import <TDRemoteConfig/TDRemoteConfig.h>

TDObject *obj = [TDRemoteConfig getData];
NSArray *arr = obj.get(@"configId").get(@"templateId").arrayValue;

Where:

configId: The Config ID created in the Config Center module of the Engage backend, used to identify the business module. For details about config items, see Config items

templateId: The Template ID that you add under Config Items, used to identify the specific feature module. For details about config templates, see Config templates

Value resolution rules

How the value of a key is resolved:

• The remote config value for the key is used first
• If the key isn't configured remotely, the local default value for the key is used
• If the local default values don't contain the key either, an empty value is returned.

4.4 Listen for updates

Before you initialize the SDK, add a notification listener for successful config fetches

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(test:) name:kTDRemoteConfigFetchDataSuccess object:nil];

Notification name

kTDRemoteConfigFetchDataSuccess: config fetched successfully

Parameters carried by the notification

tip

By default, the notification carries the statuses of strategies that changed to suspended (suspend) or forced offline (force_offline) between the previous request and this request. You can use them as your business requires. If you don't need them, ignore them.

Get the notification parameters as follows

NSDictionary *info = notification.userInfo[kTDRemoteConfigStrategyStatusMap];

The value structure of kTDRemoteConfigStrategyStatusMap is as follows. It describes the status of the strategy whose ID is 20241209 in the config item template.

{
  "configId" : {
    "templateId" : {
      "20241209" : "suspend"
    }
  }
}

5. Send Test

To quickly verify that the integration works and that config strategies are valid, the SDK lets you enable debug mode to send tests.

TDSettings *settings = [[TDSettings alloc] init];

// debug 
settings.mode = TDSDKModeDebug;
settings.enableLog = YES;

settings.appId = @"APPID";
settings.serverUrl = @"SERVER_URL";
[TDApp startWithSetting:settings];

After you enable debug mode on the client, the client fetches test strategies every 5s. In the AE Engage module, you can create template tests or strategy tests. While waiting for strategies to be fetched, you can watch the progress nodes on the frontend page.

For details, see the client Send Test section in Config templates.

Send tests for the client SDK require test devices. You can select or add test devices in the test device list.