跳到主要内容

CocosCreator

最近更新 2026/10/03

最新版本：v1.3.1

更新时间：2026-09-16

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

资源下载： 下载

1. 概述​

从 AE 4.4 版本开始，运营模块上线了“配置中心”功能，支持在 AE 后台添加功能参数配置，通过客户端 SDK 拉取至 App，精细化定制您与玩家的互动内容。

本文介绍 Cocos Creator 客户端 SDK 的集成过程。小游戏 / Web 走 JS 通道；Android / iOS / HarmonyOS 原生包体会通过 jsb.reflection 调用原生 TDRemoteConfig。App 端只需要关注与数数 SDK 的交互即可，不需要关心 AE 后台的任务细节。

建议先初始化数数分析 SDK（TDAnalytics），再初始化配置中心 SDK（TDRemoteConfig）。

2. 集成​

2.1 手动集成 SDK​

配置中心需要依赖以下数数 SDK：

SDK名称介绍版本要求
TDAnalytics实现数据采集与处理>= 3.8.0
TDRemoteConfig（JS）Cocos Creator 配置中心 SDK>= 1.3.1
  1. 将 tdremoteconfig.mg.cc.min.js 与 tdremoteconfig.cc.d.ts 放入工程（例如 assets/Script/、assets/libs/）。
  2. 在脚本中以普通模块加载，Inspector 里不要勾选「导入为插件」。
import './Script/tdremoteconfig.mg.cc.min.js';

仅发布 Web / 小游戏时，完成 JS 集成即可。发布 Android / iOS / HarmonyOS 原生包体时，还需按下列步骤接入原生 SDK 与桥接类。

2.2 Android 原生额外步骤​

先在 Creator 中构建一次 Android 工程，生成 native/engine/android 后再拷贝文件。

  1. 将 TDRemoteConfigProxyApi.java 拷贝到 native/engine/android/app/src/com/cocos/game/。
  2. 将 TDRemoteConfig.aar 拷贝到 native/engine/android/app/libs/（工程已包含 implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])）。
  3. 在 app/proguard-rules.pro 中增加混淆保留：
-keep public class com.cocos.game.TDRemoteConfigProxyApi { *; }
-keep class cn.thinkingdata.** { *; }
-dontwarn cn.thinkingdata.**

2.3 iOS 原生额外步骤​

先在 Creator 中构建一次 iOS 工程，生成 native/engine/ios 后再拷贝文件。当前 Framework 为 arm64 真机包。

  1. 将 TDRemoteConfigProxyApi.h、TDRemoteConfigProxyApi.mm 与 TDRemoteConfig.framework 拷贝到 native/engine/common/Classes/ThinkingAnalytics/ios/。
  2. 在 iOS CMake 中加入源文件，并在 target 链接后 Embed Frameworks：
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 HarmonyOS 原生额外步骤​

先在 Creator 中构建一次 HarmonyOS 工程，生成 native/engine/harmonyos-next 后再操作。缺任一步都会导致 jsb.reflection 调不到桥，或配置回调无法回到 JS。

  1. 将 TDRemoteConfigProxyApi.ts 拷贝到 entry/src/main/ets/，将 TDRemoteConfig.har 拷贝到 entry/libs/。
  2. 在 entry/oh-package.json5 增加依赖：
{
  "dependencies": {
    "@thinkingdata/remoteconfig": "file:./libs/TDRemoteConfig.har"
  }
}
  1. 在 EntryAbility.ets 中设置应用上下文：
globalThis.appContext = this.context;
  1. 在 entry/build-profile.json5 的 buildOption 中配置 arkOptions.runtimeOnly，否则 jsb.reflection.callStaticMethod 找不到桥接类：
arkOptions: {
  runtimeOnly: {
    sources: [
      './src/main/ets/TDRemoteConfigProxyApi.ts'
    ],
    packages: [
      '@thinkingdata/remoteconfig'
    ]
  }
}
  1. 工程级 native/engine/harmonyos-next/build-profile.json5 开启 useNormalizedOHMUrl: true（bytecode HAR 必需）。
  2. Creator 导出的 entry/src/main/ets/workers/cocos_worker.ts 默认没有 evalString。配置拉取回调从主线程 post 到 Worker，必须增加分支，否则监听不到更新：
case "evalString":
  cocos.evalString(msg.param);
  break;
  1. 执行 ohpm install 后重新构建 HarmonyOS。

3. 初始化​

必须先初始化 TDAnalytics SDK，再调用 TDRemoteConfig.init。配置中心依赖分析 SDK 的账号与设备信息；原生通道会自动走 TDRemoteConfigProxyApi，无需在 JS 里再写 JNI / ObjC / ArkTS。

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
});

常用参数：

参数说明备注
appId项目 APP ID必填，与分析 SDK 共用
serverUrl数据接收地址必填
enableLog打印日志不等于 Debug 模式
debugMode传 'debug' 开启测试模式原生通道只识别 'debug'，不识别 'debugOnly'
templateCode模板编码可选
customFetchParams初始化时携带的自定义拉取参数可选

4. 使用​

4.1 数据结构样例​

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

    }
}

其中：

configId：在运营后台配置中心模块创建的“配置项ID”，用于标识业务模块信息。配置项说明详见配置项管理

templateId：业务在“配置项”下添加的“模版ID”，用于标识具体的功能模块信息。配置模板说明详见配置模板管理

#strategy_id：策略的唯一ID，用于策略生命周期管理。配置策略说明见配置策略管理

paramater_x：配置模板参数，对应功能模块所需的配置参数

#ops_receipt_properties：用于事件回收统计，当你需要自动统计策略效果（暂未支持）时，回收事件需要携带此属性

#custom_params：客户端配置通道上的自定义参数，可定义需要携带到客户端的用户属性信息。

4.2 设置本地默认值​

您可以在 TDRemoteConfig SDK 中设置配置项默认值，在 AE 服务端未添加配置项、或者本地未拉取到远端值时，SDK 会获取到本地默认值。

格式​

本地默认值的结构需要保持以下格式：

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

直接设置​

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

清空默认值​

TDRemoteConfig.clearDefaultValues(appId);

4.3 获取值​

获取配置项下某一类已经发布上线中的策略内容：

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

对象 / 字符串 / 数值示例：

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

其中：

configId：在智能运营配置中心设置的“配置项ID”。配置项说明详见配置项管理

templateId：在智能运营配置中心“配置项”下设置的“模版ID”。配置模板说明详见配置模板管理

取值规则​

某一个 key 的取值过程：

  • 优先取该 key 对应的远端配置的值
  • 若远端没有配置该 key，则去查找该 key 的本地默认值
  • 若本地默认值也没有该 key，返回空。

4.4 监听更新​

建议在业务真正消费配置前添加拉取成功监听。原生 Android / iOS / HarmonyOS 会回调到 window._configFetchListener。

TDRemoteConfig.addConfigFetchListener((status) => {
  // status 为本次拉取结果
});

通知携带的参数​

提示

通知将默认携带本次请求和上次请求期间，变更为暂停生效（suspend）、强制下线（force_offline）的策略状态，您可结合业务需求取用。若无需使用，可直接忽略。

使用以下方式获取通知参数：

let map = statusData["strategy_status_map"];

对应的 value 结构如下，用来描述配置项模版中策略 id 为 20241209 的策略状态。

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

5. 发送测试​

为了快速验证接入的可用性，与配置策略的有效性，SDK 支持开启测试模式。

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

客户端开启 debug 模式后，会每 5s 拉取一次测试策略。在 AE 运营模块可以创建模版测试或者策略测试，等待配置拉取的过程中，可以关注前端页面的进度节点。

参考操作文档 配置模板管理 中的客户端发送测试部分。

客户端 SDK 发送测试需要使用测试设备，您可在测试设备列表中选择或添加测试设备。

enableLog 只控制日志，不会进入测试模式。原生通道仅当 debugMode 为 'debug' 时生效。

这篇文档对你有帮助吗？
本页内容