본문으로 건너뛰기

Unity

최근 업데이트 2026. 10. 05.
팁

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

Unity SDK: iOS, Android, HarmonyOS, Unity Editor, Windows, Mac, WebGL, Switch, Xbox, PS4/5 등의 게임 단말을 지원하며, 위챗 미니 게임, Douyin 미니 게임, OPPO 등의 미니 게임 플랫폼을 지원합니다

최소 Unity 5.4.0 버전과 호환되며, 크기는 약 320 KB입니다

최신 버전: v3.5.3

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

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

주의

이 문서는 v3.0.0 이상 버전에 적용됩니다. 과거 버전은 Unity 연동 가이드(V2), SDK 다운로드(v2.6.1)를 참고하십시오

1. SDK 통합​

1.1 수동 통합​

  1. Unity SDK 리소스 파일을 다운로드합니다
  2. ta_unity_sdk.unitypackage 파일을 더블 클릭하거나 Assets > Import Package > Custom Package를 통해 ta_unity_sdk.unitypackage를 가져옵니다
노트

unitypackage를 3.3.0에서 3.4+.x로 업그레이드할 때는 기존 SDK를 삭제한 후 다시 가져와야 합니다

이유: Unity/Tuanjie Engine에서 HarmonyOS 플랫폼으로 내보낼 때 .ts 파일이 유실되는 문제가 간헐적으로 발생하여, 현재 모든 ts 파일의 이름을 .tslib로 변경했습니다. 기존 파일을 삭제하지 않으면 파일 이름이 중복되는 문제가 발생합니다

1.2 Package Manager 통합​

v2.4.1부터 Package Manager 방식으로 SDK를 자동 연동할 수 있습니다.

  1. Window - Package Manager 메뉴를 엽니다
  2. +를 클릭한 후 Add package from git URL...을 선택합니다
  3. https://github.com/ThinkingDataAnalytics/unity-sdk.git을 입력한 후 Add를 클릭하고, 로드가 완료될 때까지 기다립니다

2. 초기화​

SDK는 수동 방식으로 초기화하는 것을 권장하며, 프리팹을 이용한 자동 초기화 방식도 제공합니다.

2.1 수동 초기화​

using ThinkingData.Analytics;
//초기화 방법 1
TDAnalytics.Init("APPID","SERVER");
//초기화 방법 2
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);

2.2 자동 초기화​

팁

Package Manager 통합 방식으로 연동한 SDK는 일부 설정만 지원하므로, 실제 동작을 기준으로 하십시오.

  1. TDAnalytics 프리팹을 추가하고 SDK 설정을 지정합니다

위 그림의 설정 항목은 각각 다음과 같습니다:

Configuration

  • Start Manually: 수동 초기화 활성화 여부

    1. 활성화하면 TDAnalytics.Init()을 수동으로 호출하여 SDK를 초기화해야 합니다.
    2. 활성화하지 않으면 TDAnalytics 프리팹이 로드될 때 SDK가 자동으로 초기화됩니다.

  • Enable Log: 로그 활성화 여부입니다. 활성화하면 전송 상황이 출력되어 디버깅에 편리합니다. Editor 모드에서 이벤트 전송이 올바른지 검증할 수도 있으며, 조건에 맞지 않는 속성은 warning 로그로 콘솔에 표시됩니다.

  • Network Type: 데이터 전송 네트워크 조건입니다. 기본값은 All로, 모든 네트워크에서 전송합니다. Wifi를 선택하면 WiFi 네트워크에서만 전송합니다. iOS, Android, HarmonyOS 플랫폼에서만 적용되며, PC, WebGL, 미니 게임에서는 설정이 적용되지 않습니다.

Configs

각 Config는 하나의 인스턴스를 나타냅니다. 여러 프로젝트로 데이터를 전송하려면 오른쪽 하단의 + 버튼을 클릭하여 프로젝트 구성을 추가할 수 있으며, APP ID가 서로 다른 여러 Token 구성을 추가할 수 있습니다.

  • APP ID: 설정이 필요합니다. 프로젝트의 APP_ID로, 프로젝트를 신청할 때 제공됩니다. 여기에 입력하십시오.

  • SERVER URL: 설정이 필요합니다. 데이터 수신 측의 URL입니다:

    • 클라우드 서비스를 사용하는 경우 다음 URL을 입력하십시오: https://global-receiver-ta.thinkingdata.cn
    • 프라이빗 배포 버전을 사용하는 경우 다음 URL을 입력하십시오: https://데이터 수집 주소

  • MODE: SDK 인스턴스의 실행 모드입니다. 운영 환경에서는 반드시 NORMAL 모드를 사용하십시오.

  • TimeZone: SDK 인스턴스의 기본 시간대로, 이벤트 시간을 정렬하는 데 사용하며 고급 가이드의 기본 시간대 설정과 같은 역할을 합니다. 기본값은 Local(디바이스 로컬 시간대)이며, UTC, Asia_Shanghai, Asia_Tokyo, America_Los_Angeles, America_New_York을 선택할 수 있습니다. Other를 선택하면 오른쪽 입력란에 시간대 ID를 입력합니다.

주의: 일부 디바이스는 기본적으로 평문 전송을 금지하므로 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");

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

3.2 공통 이벤트 속성 설정​

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

Dictionary<string, object> superProperties = new Dictionary<string, object>();
superProperties["channel"] = "ta";//문자열
superProperties["age"] = 1;//숫자
superProperties["isSuccess"] = true;//불리언
superProperties["birthday"] = DateTime.Now;//시간
superProperties["object"] = new Dictionary<string, object>(){{ "key", "value"}};//객체
superProperties["object_arr"] = new List<object>() {new Dictionary<string, object>(){{ "key", "value" }}};//객체 그룹
superProperties["arr"] = new List<object>() { "value" };//배열
TDAnalytics.SetSuperProperties(superProperties);//공통 이벤트 속성 설정

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

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

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

3.3 자동 수집 활성화​

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

노트

Harmony 플랫폼에서는 이 기능이 일시적으로 비활성화되어 있습니다

//설치, 시작, 종료 이벤트의 자동 수집 활성화
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);

3.4 이벤트 전송​

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

Dictionary<string, object> properties = new Dictionary<string, object>(){{"product_name", "상품명"}};
TDAnalytics.Track("product_buy", properties);

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

3.5 유저 속성 설정​

일반적인 유저 속성은 UserSet을 호출하여 설정할 수 있습니다. 이 인터페이스로 전송한 속성은 원래 속성 값을 덮어쓰며, 이전에 해당 유저 속성이 없었다면 새로 생성합니다.

//이때 username은 TA
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
//이때 username은 AE
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TE"}});

4. 모범 사례​

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

using ThinkingData.Analytics;
if (개인정보 처리방침 동의 완료)
{  // SDK 초기화
   TDAnalytics.Init("APPID", "SERVER");
   //자동 수집 이벤트 활성화
   TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);
   //유저가 로그인한 경우 유저의 계정 ID를 고유 식별자로 설정할 수 있습니다
   TDAnalytics.Login("TA");
   //공통 이벤트 속성을 설정하면 모든 이벤트에 공통 이벤트 속성이 포함됩니다
   Dictionary<string, object> superProperties = new Dictionary<string, object>();
   superProperties["channel"] = "ta";//문자열
   superProperties["age"] = 1;//숫자
   superProperties["isSuccess"] = true;//불리언
   superProperties["birthday"] = DateTime.Now;//시간
   superProperties["object"] = new Dictionary<string, object>(){{ "key", "value"}};//객체
   superProperties["object_arr"] = new List<object>() {new Dictionary<string, object>(){{ "key", "value" }}};//객체 그룹
   superProperties["arr"] = new List<object>() { "value" };//배열
   TDAnalytics.SetSuperProperties(superProperties);//공통 이벤트 속성 설정
   //이벤트 전송
   Dictionary<string, object> properties = new Dictionary<string, object>(){{"product_name", "상품명"}};
   TDAnalytics.Track("product_buy", properties);
   //유저 속성 설정
   TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
}
이 문서가 도움이 되었나요?
이 페이지의 내용