Native 지원

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

1. iOS Native 지원

iOS 프로젝트를 처음 빌드하면 ./build/ios/와 ./native/engine/ios/ 두 디렉터리에 프로젝트 코드가 생성되며, 그다음 iOS 프로젝트를 설정합니다.

1.1 수동 설정

• iOS 프로젝트 의존성 파일 추가

  • CocosCreatorProxyApi.h
  • CocosCreatorProxyApi.mm
  • ThinkingSDK.framework
  • ThinkingDataCore.framework

• Build Phases 설정

  • Link Binary With Libraries에 ThinkingSDK.framework 추가

• Build Settings 설정

  • Framework Search Paths에 ThinkingSDK.framework의 참조 경로 추가(예: "$(SRCROOT)/../Classes")
  • Other Linker Flags에 -ObjC 추가

1.2 CMakeList 설정

알림:

CMakeList 파일 경로는 ./native/engine/ios/CMakeLists.txt입니다.

iOS 프로젝트를 처음 빌드한 후 CMakeList 파일이 생성되며, 설정한 후 다시 빌드할 때 적용됩니다.

먼저 iOS 리소스 파일을 해당 폴더(예: ./native/engine/common/Classes/ThinkingAnalytics/ios/)에 복사한 후, CMakeList를 설정할 때 해당 경로를 입력하면 됩니다.

• iOS 프로젝트 의존성 파일 추가

# 이 코드 줄 찾기
set(PROJ_COMMON_SOURCES
    ${CMAKE_CURRENT_LIST_DIR}/../common/Classes/Game.h
    ${CMAKE_CURRENT_LIST_DIR}/../common/Classes/Game.cpp
    # 다음 코드 추가
    ${CMAKE_CURRENT_LIST_DIR}/../common/Classes/ThinkingAnalytics/ios/CocosCreatorProxyApi.h
    ${CMAKE_CURRENT_LIST_DIR}/../common/Classes/ThinkingAnalytics/ios/CocosCreatorProxyApi.mm
    ${CMAKE_CURRENT_LIST_DIR}/../common/Classes/ThinkingAnalytics/ios/ThinkingSDK.framework
    ${CMAKE_CURRENT_LIST_DIR}/../common/Classes/ThinkingAnalytics/ios/ThinkingDataCore.framework
)

• Build Phases 설정

# 이 코드 줄 찾기
target_link_libraries(${LIB_NAME} cocos2d)
# 다음 코드 추가
target_link_libraries(${LIB_NAME} ${CMAKE_CURRENT_LIST_DIR}/../common/Classes/ThinkingAnalytics/ios/ThinkingSDK.framework)
target_link_libraries(${LIB_NAME} ${CMAKE_CURRENT_LIST_DIR}/../common/Classes/ThinkingAnalytics/ios/ThinkingDataCore.framework)

• Build Settings 설정

# 이 코드 줄 찾기
set(PRODUCT_NAME ${APP_NAME})
# 다음 코드 추가
set(CMAKE_EXE_LINKER_FLAGS -ObjC)

주의

Cocos Creator v2.x 에디터는 아직 CMake 설정 방식을 지원하지 않으므로 수동으로 설정해야 합니다.

2. Android Native 지원

Android 프로젝트를 빌드하고 Android 프로젝트를 설정합니다.

• Android 표시 모드의 app 프로젝트에서 의존성 파일 CocosCreatorProxyApi.java를 com.cocos.game에 추가합니다(아래 그림 참고)

• 프로젝트 app 폴더의 proguard-rules.pro 파일에 난독화 규칙을 추가합니다

-keep public class com.cocos.game.CocosCreatorProxyApi {*;}

• 프로젝트 app 폴더에 libs 디렉터리를 새로 만들고 TDAnalytics.aar, TDCore.aar를 복사합니다
• Module 아래의 build.gradle 파일에 의존성을 추가합니다

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

3. OpenHarmony Native 지원

먼저 OpenHarmony 프로젝트를 빌드합니다

• TDAnalytics.har와 CocosCreatorProxyApi.ts를 아래 디렉터리에 넣습니다

• entry/oh-package.json5 파일에서 SDK를 불러옵니다

"@thinkingdata/analytics": "file:./libs/TDAnalytics.har"

• entry/build-profile.json5에서 브리지 파일을 불러옵니다

arkOptions: {
  runtimeOnly: {
    sources: [
      './src/main/ets/CocosCreatorProxyApi.ts',
    ],
  },
}

• context 불러오기

현재는 CocosCreator가 HarmonyOS를 지원하는 첫 번째 버전으로, 상호 작용은 worker 스레드에서 이루어지며 아직 context를 가져오는 공식 api가 없습니다. 이후 공식 업데이트를 기다려야 하며, 현재는 직접 수동으로 추가할 수 있습니다

entry/src/main/ets/pages/index.ets의 aboutToAppear()에 다음을 추가합니다:

aboutToAppear(): void {
  console.log('[LIFECYCLE-Index] cocos aboutToAppear');
  this.workPort.postMessage('context', getContext(this));
  ...
}

entry/src/main/ets/workers/cocos_worker.ts의 메시지 switch에 context 분기를 추가합니다:

switch (msg.name) {
  ...
  case "context":
    globalThis.appContext = msg.param
    break;
  default:
    console.error("cocos worker: message type unknown");
    break;
}

위의 작업은 context를 worker 스레드로 전달하는 것이며, 이후 SDK를 초기화할 때 사용해야 합니다

CocosCreatorProxyApi.ts의 initWithConfig에서 초기화할 때 globalThis.appContext를 전달합니다:

function initWithConfig(param: string): void {
  try {
    let obj = JSON.parse(param)
    if (obj['enableLog'] === true) {
      TDAnalytics.enableLog(true)
    }
    let config = new TDConfig()
    config.appId = obj['appId']
    config.serverUrl = obj['serverUrl']
    TDAnalytics.initWithConfig(globalThis.appContext, config)
  } catch (e) {
  }
}

context를 가져오는 다른 방법이 있다면 CocosCreatorProxyApi.ts 파일의 initWithConfig 메서드를 직접 수정해도 됩니다

4. Native 지원 활성화

SDK를 초기화할 때 config에 enableNative: true를 추가하면 Native 지원이 활성화됩니다.

// TA SDK 설정 객체
var config = {
   appId: "YOUR_APPID", // 프로젝트 APP ID
   serverUrl: "YOUR_SERVER_URL", // 전송 주소
   enableNative: true,// Native 코드 호출 허용
   autoTrack: {
      appShow: true, // 시작 이벤트 자동 수집
      appHide: true, // 종료 이벤트 자동 수집
      appCrash: true, // 크래시 이벤트 자동 수집(native에서만 적용)
      appInstall: true // 설치 이벤트 자동 수집(native에서만 적용)
   }
};
// 초기화
TDAnalytics.init(config);