CocosCreator

Last updated 10/03/2026

Latest version: v1.3.1

Update time: 2026-09-16

Supported platforms: Cocos Creator (Web, WeChat mini games, Douyin mini games, Alipay mini games, Android, iOS, HarmonyOS)

Downloads: Download

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 Cocos Creator client SDK. Mini games and Web use the JS channel. Native Android / iOS / HarmonyOS packages call the native TDRemoteConfig through jsb.reflection. 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.

We recommend initializing the ThinkingData analytics SDK (TDAnalytics) first, and then the Config Center SDK (TDRemoteConfig).

2. Integration

2.1 Integrate the SDK manually

Config Center depends on the following ThinkingData SDKs:

SDK name	Description	Version requirement
TDAnalytics	Collects and processes data	>= 3.8.0
TDRemoteConfig（JS）	Cocos Creator Config Center SDK	>= 1.3.1

1. Put tdremoteconfig.mg.cc.min.js and tdremoteconfig.cc.d.ts in your project (for example, assets/Script/ and assets/libs/).
2. Load it as a regular module in your script. In the Inspector, don't select Import As Plugin.

import './Script/tdremoteconfig.mg.cc.min.js';

If you publish only for Web or mini games, completing the JS integration is enough. To publish native Android / iOS / HarmonyOS packages, you also need to integrate the native SDK and bridge classes by following the steps below.

2.2 Additional Android native steps

First build the Android project once in Creator. After native/engine/android is generated, copy the files.

1. Copy TDRemoteConfigProxyApi.java to native/engine/android/app/src/com/cocos/game/.
2. Copy TDRemoteConfig.aar to native/engine/android/app/libs/ (the project already includes implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])).
3. Add obfuscation keep rules to app/proguard-rules.pro:

-keep public class com.cocos.game.TDRemoteConfigProxyApi { *; }
-keep class cn.thinkingdata.** { *; }
-dontwarn cn.thinkingdata.**

2.3 Additional iOS native steps

First build the iOS project once in Creator. After native/engine/ios is generated, copy the files. The current framework is an arm64 package for real devices.

1. Copy TDRemoteConfigProxyApi.h, TDRemoteConfigProxyApi.mm, and TDRemoteConfig.framework to native/engine/common/Classes/ThinkingAnalytics/ios/.
2. Add the source files to the iOS CMake configuration, and Embed Frameworks after linking the target:

list(APPEND CC_COMMON_SOURCES
    "${TE_IOS_DIR}/TDRemoteConfigProxyApi.h"
    "${TE_IOS_DIR}/TDRemoteConfigProxyApi.mm"
)
target_link_libraries(${EXECUTABLE_NAME} "${TE_IOS_DIR}/TDRemoteConfig.framework")
target_link_options(${EXECUTABLE_NAME} PRIVATE "-ObjC")

2.4 Additional HarmonyOS native steps

First build the HarmonyOS project once in Creator. After native/engine/harmonyos-next is generated, perform the following steps. If you miss any step, jsb.reflection can't reach the bridge, or the config callback can't return to JS.

1. Copy TDRemoteConfigProxyApi.ts to entry/src/main/ets/, and copy TDRemoteConfig.har to entry/libs/.
2. Add the dependency to entry/oh-package.json5:

{
  "dependencies": {
    "@thinkingdata/remoteconfig": "file:./libs/TDRemoteConfig.har"
  }
}

3. Set the application context in EntryAbility.ets:

globalThis.appContext = this.context;

4. Configure arkOptions.runtimeOnly in buildOption of entry/build-profile.json5. Otherwise, jsb.reflection.callStaticMethod can't find the bridge class:

arkOptions: {
  runtimeOnly: {
    sources: [
      './src/main/ets/TDRemoteConfigProxyApi.ts'
    ],
    packages: [
      '@thinkingdata/remoteconfig'
    ]
  }
}

5. Enable useNormalizedOHMUrl: true in the project-level native/engine/harmonyos-next/build-profile.json5 (required for bytecode HARs).
6. The entry/src/main/ets/workers/cocos_worker.ts exported by Creator has no evalString by default. The config fetch callback is posted from the main thread to the Worker, so you must add the branch. Otherwise, your listener doesn't receive updates:

case "evalString":
  cocos.evalString(msg.param);
  break;

7. Run ohpm install, and then rebuild for HarmonyOS.

3. Initialization

You must initialize the TDAnalytics SDK first, and then call TDRemoteConfig.init. Config Center depends on the account and device information of the analytics SDK. The native channel automatically goes through TDRemoteConfigProxyApi, so you don't need to write any JNI / ObjC / ArkTS code in JS.

import './tdanalytics.mg.cocoscreator.min.js';
import './tdremoteconfig.mg.cc.min.js';

TDAnalytics.init({
  appId: 'YOUR-APP-ID',
  serverUrl: 'https://your-server-url'
});

TDRemoteConfig.init({
  appId: 'YOUR-APP-ID',
  serverUrl: 'https://your-server-url',
  enableLog: true
});

Common parameters:

Parameter	Description	Remarks
appId	Project APP ID	Required. Shared with the analytics SDK
serverUrl	Data receiving URL	Required
enableLog	Prints logs	Not the same as Debug mode
debugMode	Pass 'debug' to enable test mode	The native channel only recognizes 'debug', not 'debugOnly'
templateCode	Template code	Optional
customFetchParams	Custom fetch parameters carried during initialization	Optional

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

TDRemoteConfig.setDefaultValues({
    "configId": {
        "templateId": [
            {
              "paramater_x": ""
            }
        ]
    }
}, appId);

Clear default values

TDRemoteConfig.clearDefaultValues(appId);

4.3 Get values

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

let array = TDRemoteConfig.getData().get("configId").get("templateId").arrayValue();

Object / string / number example:

const array = TDRemoteConfig.getData().get("configId").get("templateId").arrayValue();

Where:

configId: The Config ID set in Engage Config Center. For details about config items, see Config items

templateId: The Template ID set under Config Items in Engage Config Center. 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

We recommend adding a fetch success listener before your business logic actually consumes the configuration. On native Android / iOS / HarmonyOS, the callback goes to window._configFetchListener.

TDRemoteConfig.addConfigFetchListener((status) => {
  // status is the result of this fetch
});

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:

let map = statusData["strategy_status_map"];

The corresponding value structure 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 supports a test mode.

TDRemoteConfig.init({
  appId: 'YOUR-APP-ID',
  serverUrl: 'https://your-server-url',
  enableLog: true,
  debugMode: 'debug'
});

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 the configuration 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.

enableLog only controls logging and doesn't enter test mode. The native channel takes effect only when debugMode is 'debug'.