CocosCreator

最近更新 2026/09/16

最新版本：v1.4.0

更新时间：2026-09-16

支持平台：Web、微信小游戏、支付宝小游戏、抖音小游戏、Android、iOS、HarmonyOS

资源下载：下载

1. 概述

从 AE 4.4 版本开始，运营模块上线了“客户端触发式任务”功能，支持端内新用户注册、创角等场景中的毫秒级触发需求，并支持实时 A/B 分流。客户端侧由数数 SDK 来实现与 AE 后端的通信，完成任务的拉取与计算。

在 Cocos Creator 工程中需要集成数数 SDK。业务侧只需要关注与数数 SDK 的交互即可，不需要关心 AE 后台的任务细节。

Web / 小游戏走 JS 实现；Android、iOS、HarmonyOS 原生端通过 JSB 桥接到对应平台的原生 SDK。JS 层统一使用 TDStrategy，原生端由 SDK 按平台自动调用 TDStrategyProxyApi。

2. 集成

2.1 手动集成 SDK

客户端触发式需要依赖以下数数 SDK：

SDK 名称	介绍	版本要求
TDAnalytics	实现数据采集与处理	>= 3.8.0
TDRemoteConfig	拉取 AE 后台的配置信息	>= 1.3.1

获取 SDK 并解压，发布包主要文件如下。

文件	用途
tdstrategy.mg.cc.min.js	Cocos Creator JS SDK（放入 assets，按普通模块 import）
tdstrategy.cc.d.ts	TypeScript 类型声明
android/TDStrategyProxyApi.java + TDStrategy.aar	Android 原生桥接与依赖
ios/TDStrategyProxyApi.* + TDStrategy.framework	iOS 原生桥接与依赖
openharmony/TDStrategyProxyApi.ts + TDStrategy.har	HarmonyOS 原生桥接与依赖

将 tdstrategy.mg.cc.min.js 放入工程 assets/Script，将 tdstrategy.cc.d.ts 放入 assets/libs。数据采集、配置中心 SDK 按同样方式放入。
若打包 Android / iOS / HarmonyOS，必须先在 Creator 中导出一次对应原生工程，再按下面各端步骤拷贝桥接文件。只放 JS 文件无法走原生通道。

2.2 Android 原生额外配置

先在 Creator 中导出 / 构建一次 Android 工程，确认已生成 native/engine/android/app。

把 TDStrategyProxyApi.java 拷到 native/engine/android/app/src/com/cocos/game/。
把 TDStrategy.aar 拷到 native/engine/android/app/libs/。若同时接入采集 / 配置中心，同目录还需放入对应 AAR。Creator 默认工程一般已包含 implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])；若没有，在 app/build.gradle 补上。
在 app/proguard-rules.pro 增加 keep 规则，避免 Release 混淆后找不到桥接类。

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

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

2.3 iOS 原生额外配置

先在 Creator 中导出一次 iOS 工程，确认已生成 native/engine/ios。随包 framework 为 arm64 真机，请用真机或 iphoneos 构建，不要只编模拟器。

将以下文件拷到 native/engine/common/Classes/ThinkingAnalytics/ios/：

TDStrategyProxyApi.h
TDStrategyProxyApi.mm
TDStrategy.framework

若同时接入数据采集 / 配置中心 SDK，同目录还需放入 CocosCreatorProxyApi、ThinkingSDK.framework、ThinkingDataCore.framework、TDRemoteConfigProxyApi 与 TDRemoteConfig.framework。

然后改写 native/engine/ios/CMakeLists.txt：把桥接源文件加入编译，并在 cc_ios_after_target 之后链接、嵌入 framework，同时加上 -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 不支持这套 CMake 写法，需要在 Xcode 里手动加源文件、Link Binary、Framework Search Paths、-ObjC 和 Embed Frameworks。

2.4 HarmonyOS 原生额外配置

先在 Creator 中导出一次 HarmonyOS 工程，确认已生成 native/engine/harmonyos-next/entry。缺任何一步，运行期都可能找不到桥接类或编不过 HAR。

拷贝桥接文件与 HAR。将 TDStrategyProxyApi.ts 拷到 entry/src/main/ets/，将 TDStrategy.har 拷到 entry/libs/。若同时接入采集 / 配置中心 SDK，再拷贝对应 Proxy 与 HAR。

声明 HAR 依赖。在 entry/oh-package.json5 增加本地 HAR 依赖后执行 ohpm install。

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

设置 appContext。在 EntryAbility.ets 的 onCreate 中设置 globalThis.appContext，原生 SDK 初始化需要这个上下文。

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

注册 jsb.reflection 运行时源。entry/build-profile.json5 必须配置 arkOptions.runtimeOnly，否则运行时报找不到 TDStrategyProxyApi。

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

若同时接入采集 / 配置中心，sources 再加对应 Proxy，packages 再加 @thinkingdata/analytics、@thinkingdata/remoteconfig。

开启 useNormalizedOHMUrl，并提升 API 版本。工程级 native/engine/harmonyos-next/build-profile.json5 必须打开 useNormalizedOHMUrl，否则接入 bytecode HAR 时 hvigor 会报 00306046。当前策略 HAR 的 compatibleSdkVersion 为 20，需要把工程 compatibleSdkVersion 提到 6.0.0(20)。

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

处理 cocos_worker 的 evalString。策略触发回调要从 ArkTS 主线程回到 Cocos Worker 执行 JS。Creator 导出的 entry/src/main/ets/workers/cocos_worker.ts 默认没有 evalString 分支，需要补上，否则鸿蒙收不到 triggerListener。

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

3. 初始化

必须先初始化 TDAnalytics，再初始化 TDRemoteConfig 与 TDStrategy，三者共用同一套 appId / serverUrl。原生端建议在采集 SDK 配置里打开 enableNative: true。

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 配置项说明：

参数	必填	说明
appId	是	项目 APP ID，可在 TE 后台项目管理页查看
serverUrl	是	服务地址，与数据采集项目保持一致
enableLog	否	是否打印日志，默认 false
debugMode	否	传 `debug` 时走 Debug 模式。仅 Android / iOS / HarmonyOS 原生通道生效
triggerListener	否	任务命中时的回调。建议在 init 时传入，避免错过首次触发

4. 设置回调监听

初始化 SDK 的时候，给 TDStrategy SDK 设置一个回调监听。

triggerListener: function (result) {

}

TDStrategy SDK 任务触发结果：

属性名	类型	说明
channelMsgType	String	通道消息类型
appId	String	您的 AE 项目的 app id
pushId	String	运营任务的通道发送 ID
taskId	String	运营任务的 ID
content	object	运营任务的推送内容
userParams	object	客户端通道中的自定义参数
opsProperties	object	客户端触发任务携带的通道信息，用于触达漏斗事件的回执参数。

这篇文档对你有帮助吗？

1. 概述​

2. 集成​

2.1 手动集成 SDK​

2.2 Android 原生额外配置​

2.3 iOS 原生额外配置​

2.4 HarmonyOS 原生额外配置​

3. 初始化​

4. 设置回调监听​