CocosCreator

Last updated 09/16/2026

Latest version: v1.4.0

Update time: 2026-09-16

Supported platforms: Web, WeChat mini games, Alipay mini games, Douyin mini games, Android, iOS, HarmonyOS

Downloads: Download

1. Overview

Starting from AE 4.4, the Engage module provides the client-triggered task feature, which supports millisecond-level triggering in in-app scenarios such as new user registration and character creation, as well as real-time A/B splitting. On the client side, the ThinkingData SDK communicates with the AE backend to fetch and evaluate tasks.

Integrate the ThinkingData SDK into your Cocos Creator project. 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.

Web and mini games use the JS implementation. On Android, iOS, and HarmonyOS, the native side bridges to the native SDK of each platform through JSB. The JS layer always uses TDStrategy, and on the native side the SDK automatically calls TDStrategyProxyApi for the current platform.

2. Integration

2.1 Integrate the SDK manually

Client-triggered tasks depend on the following ThinkingData SDKs:

SDK name	Description	Version requirement
TDAnalytics	Collects and processes data	>= 3.8.0
TDRemoteConfig	Fetches configuration from the AE backend	>= 1.3.1

1. Get the SDK and unzip it. The main files in the release package are as follows.

File	Purpose
tdstrategy.mg.cc.min.js	Cocos Creator JS SDK (put it in assets and import it as a regular module)
tdstrategy.cc.d.ts	TypeScript type declarations
android/TDStrategyProxyApi.java + TDStrategy.aar	Android native bridge and dependency
ios/TDStrategyProxyApi.* + TDStrategy.framework	iOS native bridge and dependency
openharmony/TDStrategyProxyApi.ts + TDStrategy.har	HarmonyOS native bridge and dependency

1. Put tdstrategy.mg.cc.min.js in assets/Script of your project, and put tdstrategy.cc.d.ts in assets/libs. Add the data collection SDK and the Config Center SDK in the same way.
2. If you build for Android, iOS, or HarmonyOS, you must first export the corresponding native project once in Creator, and then copy the bridge files by following the steps for each platform below. With only the JS files, the native channel can't be used.

2.2 Additional Android native configuration

First export or build the Android project once in Creator, and make sure that native/engine/android/app has been generated.

1. Copy TDStrategyProxyApi.java to native/engine/android/app/src/com/cocos/game/.
2. Copy TDStrategy.aar to native/engine/android/app/libs/. If you also integrate the data collection or Config Center SDK, put the corresponding AARs in the same directory. The default Creator project usually already includes implementation fileTree(dir: 'libs', include: ['*.jar','*.aar']). If it doesn't, add it to app/build.gradle.
3. Add keep rules to app/proguard-rules.pro so that the bridge classes can still be found after Release obfuscation.

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

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}

2.3 Additional iOS native configuration

First export the iOS project once in Creator, and make sure that native/engine/ios has been generated. The bundled frameworks are built for arm64 devices. Build for a real device or iphoneos, not only for the simulator.

Copy the following files to native/engine/common/Classes/ThinkingAnalytics/ios/:

• TDStrategyProxyApi.h
• TDStrategyProxyApi.mm
• TDStrategy.framework

If you also integrate the data collection or Config Center SDK, put CocosCreatorProxyApi, ThinkingSDK.framework, ThinkingDataCore.framework, TDRemoteConfigProxyApi, and TDRemoteConfig.framework in the same directory.

Then modify native/engine/ios/CMakeLists.txt: add the bridge source files to the build, link and embed the frameworks after cc_ios_after_target, and add -ObjC.

list(APPEND CC_COMMON_SOURCES
    "${TE_IOS_DIR}/TDStrategyProxyApi.h"
    "${TE_IOS_DIR}/TDStrategyProxyApi.mm"
)

target_link_libraries(${EXECUTABLE_NAME}
    "${TE_IOS_DIR}/TDStrategy.framework"
)
target_link_options(${EXECUTABLE_NAME} PRIVATE "-ObjC")
set_target_properties(${EXECUTABLE_NAME} PROPERTIES
    XCODE_ATTRIBUTE_FRAMEWORK_SEARCH_PATHS "$(inherited) ${TE_IOS_DIR}"
    XCODE_EMBED_FRAMEWORKS "${TE_IOS_DIR}/TDStrategy.framework"
    XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY "YES"
)

Cocos Creator 2.x doesn't support this CMake approach. In Xcode, manually add the source files, Link Binary, Framework Search Paths, -ObjC, and Embed Frameworks.

2.4 Additional HarmonyOS native configuration

First export the HarmonyOS project once in Creator, and make sure that native/engine/harmonyos-next/entry has been generated. If you miss any of the steps below, the bridge classes may not be found at runtime, or the HAR may fail to compile.

Copy the bridge files and HAR. Copy TDStrategyProxyApi.ts to entry/src/main/ets/, and copy TDStrategy.har to entry/libs/. If you also integrate the data collection or Config Center SDK, copy the corresponding Proxy and HAR files as well.

Declare the HAR dependency. Add the local HAR dependency to entry/oh-package.json5, and then run ohpm install.

{
  "dependencies": {
    "@thinkingdata/strategy": "file:./libs/TDStrategy.har"
  }
}

Set appContext. Set globalThis.appContext in onCreate of EntryAbility.ets. The native SDK needs this context for initialization.

globalThis.abilityWant = want;
globalThis.appContext = this.context;

Register the jsb.reflection runtime sources. entry/build-profile.json5 must configure arkOptions.runtimeOnly. Otherwise, TDStrategyProxyApi can't be found at runtime.

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

If you also integrate the data collection or Config Center SDK, add the corresponding Proxy to sources, and add @thinkingdata/analytics and @thinkingdata/remoteconfig to packages.

Enable useNormalizedOHMUrl and raise the API version. The project-level native/engine/harmonyos-next/build-profile.json5 must enable useNormalizedOHMUrl. Otherwise, hvigor reports 00306046 when you integrate a bytecode HAR. The compatibleSdkVersion of the current strategy HAR is 20, so you need to raise the compatibleSdkVersion of your project to 6.0.0(20).

"buildOption": {
  "strictMode": {
    "useNormalizedOHMUrl": true
  }
}

Handle evalString in cocos_worker. The strategy trigger callback needs to go from the ArkTS main thread back to the Cocos Worker to run JS. The entry/src/main/ets/workers/cocos_worker.ts exported by Creator has no evalString branch by default. Add the branch. Otherwise, HarmonyOS doesn't receive triggerListener.

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

3. Initialization

You must initialize TDAnalytics first, and then initialize TDRemoteConfig and TDStrategy. All three share the same appId / serverUrl. On the native side, we recommend turning on enableNative: true in the data collection SDK configuration.

import './Script/tdanalytics.mg.cocoscreator.min.js';
import './Script/tdstrategy.mg.cc.min.js';

TDAnalytics.init({
  appId: 'AppId',
  serverUrl: 'ServerUrl',
  enableNative: true,
});

TDStrategy.init({
  appId: 'AppId',
  serverUrl: 'ServerUrl',
  enableLog: true,
  debugMode: 'debug',
  triggerListener: function (result) {

  }
});

TDStrategy.init configuration options:

Parameter	Required	Description
appId	Yes	Project APP ID. You can view it on the Project Settings page in the TE backend
serverUrl	Yes	Server URL. Keep it the same as the data collection project
enableLog	No	Whether to print logs. Defaults to false
debugMode	No	Pass debug to use Debug mode. Takes effect only on the Android / iOS / HarmonyOS native channels
triggerListener	No	Callback when a task is hit. Pass it in at init to avoid missing the first trigger

4. Set a callback listener

When you initialize the SDK, set a callback listener for the TDStrategy SDK.

triggerListener: function (result) {

}

TDStrategy SDK task trigger result:

Property name	Type	Description
channelMsgType	String	Channel message type
appId	String	The app id of your AE project
pushId	String	Channel send ID of the operation task
taskId	String	ID of the operation task
content	object	Push content of the operation task
userParams	object	Custom parameters in the client channel
opsProperties	object	Channel information carried by the client-triggered task, used as receipt parameters for touch funnel events.