Cocos2d-x

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

팁

연동하기 전에 먼저 연동 전 준비를 읽어 주십시오.

Cocos2d-x SDK는 iOS, Android, Mac, Windows 플랫폼에서 실행할 수 있으며, 크기는 약 6.8M입니다

최신 버전: v2.0.4

업데이트 시간: 2026-02-04

리소스 다운로드: 소스 코드, SDK 다운로드

주의

이 문서는 v2.0.0 이상 버전에 적용됩니다. 과거 버전은 Cocos2d-x 연동 가이드(V1), SDK 다운로드(v1.3.5)를 참고하십시오

1. SDK 통합

Cocos2d-x SDK 리소스 파일을 다운로드하고 압축을 해제한 후, ThinkingAnalytics 폴더를 Classes 폴더에 넣습니다
CMakeLists.txt에 다음 설정을 추가합니다

list(APPEND GAME_SOURCE
     Classes/ThinkingAnalytics/Common/TDJSONObject.cpp
     )
list(APPEND GAME_HEADER
     Classes/ThinkingAnalytics/Common/TDJSONObject.h
     Classes/ThinkingAnalytics/Common/TDAnalytics.h
     )
if(ANDROID)
    list(APPEND GAME_SOURCE
         Classes/ThinkingAnalytics/Android/TDAnalytics.cpp
         )
elseif(WINDOWS)
    list(APPEND GAME_HEADER
         Classes/ThinkingAnalytics/Other/ThinkingSDKObject.h
         )
    list(APPEND GAME_SOURCE
         Classes/ThinkingAnalytics/Other/TDAnalytics.cpp
         )
elseif(MACOSX)
    list(APPEND GAME_HEADER
        Classes/ThinkingAnalytics/Other/ThinkingSDKObject.h
        )
    list(APPEND GAME_SOURCE
        Classes/ThinkingAnalytics/Other/TDAnalytics.cpp
        )
endif()

Android 설정 추가

proj.android의 app 디렉터리 아래에 libs 폴더를 추가하고, TDAnalytics.aar, TDCore.aar, TDThirdparty.aar를 libs 폴더에 복사합니다
proj.android의 app/src 디렉터리 아래에 cn/thinkingdata/analytics 폴더를 단계별로 추가하고, TDAnalyticsCocosAPI.java를 cn/thinkingdata/analytics 폴더에 복사합니다
proj.android의 app 디렉터리 아래에 있는 build.gradle에 다음 설정을 추가합니다

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

iOS 설정 추가

ios.toolchain.cmake 도구로 iOS 프로젝트를 컴파일합니다

CMakeLists.txt에 iOS 관련 설정을 추가합니다

list(APPEND GAME_SOURCE
     Classes/ThinkingAnalytics/Common/TDJSONObject.cpp
     )
list(APPEND GAME_HEADER
     Classes/ThinkingAnalytics/Common/TDJSONObject.h
     Classes/ThinkingAnalytics/Common/TDAnalytics.h
     )
if(ANDROID)
    list(APPEND GAME_SOURCE
         Classes/ThinkingAnalytics/Android/TDAnalytics.cpp
         )
elseif(WINDOWS)
    list(APPEND GAME_HEADER
         Classes/ThinkingAnalytics/Other/ThinkingSDKObject.h
         )
    list(APPEND GAME_SOURCE
         Classes/ThinkingAnalytics/Other/TDAnalytics.cpp
         )
elseif(IOS)
    # iOS 설정
    list(APPEND GAME_HEADER
         Classes/ThinkingAnalytics/iOS/TDAnalyticsCocosAPI.h
         )
    list(APPEND GAME_SOURCE
         Classes/ThinkingAnalytics/iOS/TDAnalytics.mm
         Classes/ThinkingAnalytics/iOS/TDAnalyticsCocosAPI.m
         )    
elseif(MACOSX)
    list(APPEND GAME_HEADER
        Classes/ThinkingAnalytics/Other/ThinkingSDKObject.h
        )
    list(APPEND GAME_SOURCE
        Classes/ThinkingAnalytics/Other/TDAnalytics.cpp
        )
endif()

if(IOS)
    # iOS 설정
    set(CMAKE_EXE_LINKER_FLAGS -ObjC)
endif()       

Xcode로 iOS 프로젝트를 열고, ThinkingAnalytics 아래 iOS 폴더에 있는 ThinkingSDK.framework와 TAThirdParty.framework를 지정한 Xcode 프로젝트의 Classes/ThinkingAnalytics/iOS 디렉터리로 직접 드래그하여 넣습니다(아래 그림 참고)

설정이 완료되었습니다. 2.0.2 미만 버전이라면 Classes/ThinkingAnalytics/iOS/TDAnalyticsCocosAPI.m의 헤더 파일 import를 수동으로 수정해야 합니다

#import "ThinkingAnalyticsSDK.h"
//아래와 같이 변경
#import <ThinkingSDK/ThinkingSDK.h>

proj.ios_mac의 Xcode 프로젝트를 직접 엽니다

Xcode로 iOS 프로젝트를 열고, ThinkingAnalytics 아래의 Common 폴더와 iOS 폴더를 Xcode 프로젝트의 Classes 디렉터리로 직접 드래그하여 넣습니다(아래 그림 참고)

Build Setting -> Other Linker Flags에 -ObjC를 추가합니다

Build Setting - Framework Search Paths에 다음을 추가합니다

"$(SRCROOT)/../Classes/ThinkingAnalytics/iOS"

Build Phases - Link Binary With Libraries

WebKit.framework, GameController.framework, MediaPlayer.framework

설정이 완료되었습니다. 2.0.2 미만 버전이라면 Classes/ThinkingAnalytics/iOS/TDAnalyticsCocosAPI.m의 헤더 파일 import를 수동으로 수정해야 합니다

#import "ThinkingAnalyticsSDK.h"
//아래와 같이 변경
#import <ThinkingSDK/ThinkingSDK.h>

2. 초기화

#include "./ThinkingAnalytics/Common/TDAnalytics.h"
using namespace thinkingdata::analytics;
// 메인 스레드에서 SDK 초기화 
//방법 1
TDAnalytics::init(TA_APP_ID, TA_SERVER_URL);
//방법 2
TDConfig config(TA_APP_ID, TA_SERVER_URL);
TDAnalytics::init(config);

파라미터 설명:

APPID: 프로젝트의 APPID로, AE 백엔드의 프로젝트 관리 페이지에서 확인할 수 있습니다
SERVER_URL: 데이터 전송 URL
- 클라우드 서비스를 사용하는 경우 다음을 입력합니다: https://global-receiver-ta.thinkingdata.cn
- 프라이빗 배포 버전을 사용하는 경우 데이터 수집 주소에 도메인을 바인딩하고 HTTPS 인증서를 설정하십시오: https://데이터 수집 주소에 바인딩한 도메인

Android 9.0+에서는 기본적으로 HTTP 요청이 제한되므로 반드시 HTTPS 프로토콜을 사용하십시오

3. 자주 사용하는 기능

자주 사용하는 기능을 사용하기 전에 먼저 유저 식별 규칙을 이해하는 것을 권장합니다. SDK는 기본적으로 난수를 생성하여 게스트 ID로 사용하고, 게스트 ID를 로컬에 영구 저장합니다. 유저가 로그인하기 전에는 게스트 ID가 신원 식별 ID로 사용됩니다. 참고: 게스트 ID는 유저가 앱을 재설치하거나 디바이스를 변경하면 바뀝니다.

3.1 계정 ID 설정

유저가 로그인할 때 Login을 호출하여 유저의 계정 ID를 설정할 수 있습니다. AE 플랫폼은 계정 ID를 신원 식별 ID로 사용하며, 설정한 계정 ID는 Logout을 호출하기 전까지 계속 유지됩니다. Login을 여러 번 호출하면 이전 계정 ID를 덮어씁니다.

// 유저의 로그인 고유 식별자로, 전송 데이터의 #account_id에 해당합니다. 이때 #account_id의 값은 TA입니다
TDAnalytics::login("TA");

Login은 여러 번 호출할 수 있습니다. 호출할 때마다 전달된 계정 ID가 이전에 저장된 ID와 같은지 확인하여, 같으면 호출을 무시하고 다르면 이전 ID를 덮어씁니다.

이 메서드는 로그인 이벤트를 전송하지 않습니다

3.2 공통 이벤트 속성 설정

공통 이벤트 속성은 모든 이벤트에 포함되는 속성입니다. setSuperProperties를 호출하여 공통 이벤트 속성을 설정할 수 있으며, 이벤트를 보내기 전에 먼저 공통 이벤트 속성을 설정하는 것을 권장합니다. 유저의 회원 등급, 유입 채널 등 일부 중요한 속성은 모든 이벤트에 설정해야 하므로, 이러한 속성은 공통 이벤트 속성으로 설정할 수 있습니다.

TDJSONObject superProperties;
superProperties.setString("channel", "ta");//문자열
superProperties.setNumber("age",1);//숫자
superProperties.setBool("isSuccess",true);//불리언
superProperties.setDateTime("birthday","2020-01-02 10:52:52.290");//시간

TDJSONObject object;
object.setString("key", "value");
superProperties.setJsonObject("object", object);// 객체

TDJSONObject object1;
object1.setString("key", "value");
vector<TDJSONObject> arr;  
arr.push_back(object1);
superProperties.setList("object_arr", arr); // 객체 그룹

vector<string> arr1;
arr1.push_back("value");
superProperties.setList("arr",arr1);//배열

TDAnalytics::setSuperProperties(superProperties);

공통 이벤트 속성은 캐시에 저장되므로 앱을 시작할 때마다 호출할 필요가 없습니다. setSuperProperties를 호출하여 이전에 이미 설정한 공통 이벤트 속성을 전송하면 이전 속성을 덮어씁니다.

이벤트 속성은 TDJSONObject 타입이며, 각 요소가 하나의 속성을 나타냅니다
Key는 해당 속성의 이름으로 문자열 타입입니다. 영문자로 시작해야 하며 숫자, 영문자, 밑줄 "_"을 포함할 수 있고, 최대 길이는 50자입니다. 대소문자를 구분하지 않으며 AE에서 모두 소문자로 변환합니다
Value는 해당 속성의 값으로 문자열, 숫자, 불리언, 시간, 객체, 객체 그룹, 배열을 지원합니다

이벤트 속성과 유저 속성의 요구 사항은 공통 이벤트 속성과 같습니다

3.3 자동 수집 활성화

다음 코드 예시는 설치, 시작, 종료 이벤트를 활성화합니다. SDK의 자동 수집 기능을 자세히 알아보려면 자동 수집 기능 상세 소개를 참고하십시오

// 자동 수집 활성화
TDAnalytics::enableAutoTrack();

3.4 이벤트 전송

Track을 호출하여 이벤트를 전송할 수 있습니다. 앞서 정리한 트래킹 문서에 따라 이벤트 속성과 전송 조건을 설정하는 것을 권장합니다. 여기서는 유저가 어떤 상품을 구매하는 경우를 예로 듭니다:

TDJSONObject eventProperties;
eventProperties.setString("product_name", "상품명");
TDAnalytics::track("product_buy", eventProperties);

이벤트 이름은 문자열 타입이며, 영문자로 시작해야 하고 숫자, 영문자, 밑줄 "_"을 포함할 수 있으며, 최대 길이는 50자입니다.

3.5 유저 속성 설정

일반적인 유저 속성은 userSet을 호출하여 설정할 수 있습니다. 이 인터페이스로 전송한 속성은 원래 속성 값을 덮어쓰며, 이전에 해당 유저 속성이 없었다면 새로 생성하고 타입은 전달된 속성의 타입과 같습니다. 여기서는 사용자 이름 설정을 예로 듭니다:

//이때 username은 TA
TDJSONObject properties;
properties.setString("username", "TA");
TDAnalytics::userSet(properties);
//이때 userName은 AE
TDJSONObject newProperties;
newProperties.setString("username", "TE");
TDAnalytics::userSet(newProperties);

속성 형식 요구 사항은 이벤트 속성과 같습니다.

4. 모범 사례

다음 예시 코드에는 위의 모든 작업이 포함되어 있으며, 다음 단계에 따라 사용하는 것을 권장합니다.

#include "./ThinkingAnalytics/Common/TDAnalytics.h"
using namespace thinkingdata::analytics;

if (개인정보 처리방침 동의 완료) {
      //SDK 초기화
      TDAnalytics::init(TA_APP_ID, TA_SERVER_URL);
      
      //자동 수집 이벤트 활성화
      TDAnalytics::enableAutoTrack();
      //유저가 로그인한 경우 유저의 계정 ID를 고유 식별자로 설정할 수 있습니다
      TDAnalytics::login("TA");
      
      //공통 이벤트 속성을 설정하면 모든 이벤트에 공통 이벤트 속성이 포함됩니다
      TDJSONObject superProperties;
      superProperties.setString("channel", "ta");//문자열
      superProperties.setNumber("age",1);//숫자
      superProperties.setBool("isSuccess",true);//불리언
      superProperties.setDateTime("birthday","2020-01-02 10:52:52.290");//시간

      TDJSONObject object;
      object.setString("key", "value");
      superProperties.setJsonObject("object", object);// 객체

      TDJSONObject object1;
      object1.setString("key", "value");
      vector<TDJSONObject> arr;  
      arr.push_back(object1);
      superProperties.setList("object_arr", arr); // 객체 그룹

      vector<string> arr1;
      arr1.push_back("value");
      superProperties.setList("arr",arr1);//배열
      TDAnalytics::setSuperProperties(superProperties);
      
      //이벤트 전송
      TDJSONObject eventProperties;
      eventProperties.setString("product_name", "상품명");
      TDAnalytics::track("product_buy",eventProperties);
      
      //유저 속성 설정
      TDJSONObject userProperties;
      userProperties.setString("username", "TE");
      TDAnalytics::userSet(userProperties);
}

이 문서가 도움이 되었나요?

1. SDK 통합​

2. 초기화​

3. 자주 사용하는 기능​

3.1 계정 ID 설정​

3.2 공통 이벤트 속성 설정​

3.3 자동 수집 활성화​

3.4 이벤트 전송​

3.5 유저 속성 설정​

4. 모범 사례​