CocosCreator

최근 업데이트 2026. 10. 03.

최신 버전: v1.3.1

업데이트 시간: 2026-09-16

지원 플랫폼: Cocos Creator(Web, 위챗 미니 게임, Douyin 미니 게임, Alipay 미니 게임, Android, iOS, HarmonyOS)

리소스 다운로드: 다운로드

1. 개요

AE 4.4 버전부터 운영 모듈에 구성 센터 기능이 출시되었습니다. AE 백엔드에서 기능 파라미터 구성을 추가하고 클라이언트 SDK를 통해 App으로 가져와, 플레이어와의 상호 작용 콘텐츠를 세밀하게 맞춤 설정할 수 있습니다.

이 문서에서는 Cocos Creator 클라이언트 SDK의 통합 과정을 소개합니다. 미니 게임 / Web은 JS 채널을 사용하며, Android / iOS / HarmonyOS 네이티브 패키지는 jsb.reflection을 통해 네이티브 TDRemoteConfig를 호출합니다. App 측에서는 ThinkingData SDK와의 상호 작용만 고려하면 되며, AE 백엔드의 작업 세부 사항은 신경 쓸 필요가 없습니다.

ThinkingData 분석 SDK(TDAnalytics)를 먼저 초기화한 후 구성 센터 SDK(TDRemoteConfig)를 초기화하는 것을 권장합니다.

2. 통합

2.1 SDK 수동 통합

구성 센터에는 다음 ThinkingData 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 As Plugin을 체크하지 마십시오.

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 규칙을 추가합니다:

-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"
  }
}

3. EntryAbility.ets에서 애플리케이션 컨텍스트를 설정합니다:

globalThis.appContext = this.context;

4. entry/build-profile.json5의 buildOption에 arkOptions.runtimeOnly를 설정합니다. 그렇지 않으면 jsb.reflection.callStaticMethod가 브리지 클래스를 찾지 못합니다:

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

5. 프로젝트 수준의 native/engine/harmonyos-next/build-profile.json5에서 useNormalizedOHMUrl: true를 활성화합니다(bytecode HAR에 필수).
6. Creator가 내보낸 entry/src/main/ets/workers/cocos_worker.ts에는 기본적으로 evalString이 없습니다. 구성 가져오기 콜백은 메인 스레드에서 Worker로 post되므로 반드시 분기를 추가해야 합니다. 그렇지 않으면 업데이트를 수신할 수 없습니다:

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

7. 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'일 때만 적용됩니다.