CocosCreator

최근 업데이트 2026. 09. 16.

최신 버전: v1.4.0

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

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

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

1. 개요

AE 4.4 버전부터 운영 모듈에 클라이언트 트리거 작업 기능이 출시되어, 앱 내 신규 유저 가입, 캐릭터 생성 등의 시나리오에서 밀리초 단위 트리거 요구를 지원하며 실시간 A/B 분할도 지원합니다. 클라이언트 측에서는 ThinkingData SDK가 AE 백엔드와 통신하여 작업을 가져오고 계산합니다.

Cocos Creator 프로젝트에 ThinkingData SDK를 통합해야 합니다. 비즈니스 측에서는 ThinkingData SDK와의 상호 작용만 고려하면 되며, AE 백엔드의 작업 세부 사항은 신경 쓸 필요가 없습니다.

Web / 미니 게임은 JS로 구현되며, Android, iOS, HarmonyOS 네이티브 측은 JSB를 통해 각 플랫폼의 네이티브 SDK로 브리징됩니다. JS 레이어에서는 일관되게 TDStrategy를 사용하며, 네이티브 측에서는 SDK가 플랫폼에 따라 TDStrategyProxyApi를 자동으로 호출합니다.

2. 통합

2.1 SDK 수동 통합

클라이언트 트리거 작업에는 다음 ThinkingData 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와 구성 센터 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 분기가 없으므로 추가해야 합니다. 그렇지 않으면 HarmonyOS에서 triggerListener를 받을 수 없습니다.

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

3. 초기화

반드시 TDAnalytics를 먼저 초기화한 후 TDRemoteConfig와 TDStrategy를 초기화해야 하며, 세 SDK는 같은 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. 콜백 리스너 설정​