# Unity

::: 팁

데이터 액세스를 준비하기 전에 확인하시기 바랍니다.

Unity SDK 지원 플랫폼: iOS, Android, Unity Editor, Windows, Mac, WebGL, Switch, Wechat 등의 미니앱 플랫폼

Unity 5.4.0 이상 버전 지원, 크기는 약 320 KB입니다.

:::

최신 버전: v3.0.1 다운로드 (opens new window)

업데이트 시간: 2023-11-23

소스 코드: Source Code (opens new window)

# 1. SDK 구현

# 1.1 수동 통합

Unity SDK (opens new window)를 다운로드
ta_unity_sdk.unitypackage를 클릭하거나 Assets > Import Package > Custom Package에서 ta_unity_sdk.unitypackage를 업로드

# 1.2 Package Manager 구현

v2.4.1 이후부터는 Package Manager를 사용하여 SDK 구현을 지원하게 되었습니다.

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

# 2. 초기 설정

SDK를 수동으로 초기 설정하는 것을 권장합니다. 또한 자동으로 초기 설정하는 방법도 제공합니다.

# 2.1 수동으로 초기 설정

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

# 2.2 자동으로 초기 설정

::: 팁

Package Manager를 통해 SDK를 통합할 경우 일부 설정만 지원됩니다. 실제 내용에 따라 주세요.

:::

ThinkingAnalytics의 프리팹을 추가하고, SDK 구성을 설정합니다.

상단의 구성은 다음과 같습니다:

Configuration

Start Manually: 수동 초기 설정을 활성화할지 여부
1. 활성화하면, 수동으로 ThinkingAnalyticsAPI.StartThinkingAnalytics() 호출을 설정하여 SDK의 초기 설정을 진행합니다.
2. 활성화하지 않으면, ThinkingAnalytics에서 프리팹을 로딩할 때 자동으로 SDK 초기 설정을 진행합니다.
Enable Log: 로그를 활성화할지 여부
- 활성화하면, 전송 상태를 출력하여 디버깅을 쉽게 할 수 있으며, 이벤트가 정확히 전송되었는지 Editor 모드에서도 확인할 수 있습니다. 조건을 충족하지 않는 속성에 대해서는, warning 로그로 콘솔에 표시됩니다.

Tokens

토큰으로 인스턴스를 식별합니다. 여러 프로젝트에 데이터 전송이 필요한 경우, 우측 하단의 '+'를 클릭하여 프로젝트 구성을 추가하고, 다른 APP ID로 여러 토큰 구성을 설정할 수 있습니다.

APPID: 프로젝트의 APPID, TE 프로젝트 관리 화면에서 획득 가능
SERVER_URL: 데이터 전송 URL
- SaaS의 경우 프로젝트 관리 → 데이터 전송 주소에서 확인해 주세요
- 프라이빗 구축의 경우, 데이터 전송 주소를 지정할 수 있습니다
MODE: SDK 인스턴스 실행 모드, 생산 환경에서는 반드시 NORMAL 모드를 사용해야 합니다.

주의: 일부 디바이스에서는 기본적으로 평문 전송이 금지되어 있으므로, HTTPS 형식의 수신 주소 사용을 권장합니다.

# 3. 주요 기능

주요 기능을 사용하기 전에, 유저 식별 규칙을 확인해 주세요.

SDK는 게스트 ID를 자동으로 생성하고, 로컬에 저장됩니다; 유저가 로그인하기 전에, 게스트 ID를 신분 식별 ID로 사용됩니다.

주의: 게스트 ID는 유저가 앱을 재설치할 때 리셋됩니다.

# 3.1 계정 ID 설정

유저가 로그인할 때, login을 호출하여 유저의 계정 ID를 설정할 수 있습니다. TE 플랫폼은 계정 ID를 신원 식별 ID로 logout을 호출할 때까지 유지합니다. login을 여러 번 호출하면, 이전의 계정 ID가 덮어씌워집니다.

// 유저의 고유 로그인 식별자, 데이터 추적에서 #account_id에 해당합니다. #Account_id는 이제 TE입니다.
TDAnalytics.Login("TA");

이 방법으로는 로그인 이벤트가 전송되지 않습니다.

# 3.2 공통 이벤트 속성 설정

공통 이벤트 속성은 모든 이벤트에 포함되는 속성입니다. setSuperProperties를 호출하여 설정할 수 있습니다. 이벤트를 전송하기 전에, 공통 이벤트 속성을 설정해 주세요.

예를 들어: 플레이어의 레벨, 전투력, 소지 자원 등의 속성

Dictionary<string, object> superProperties = new Dictionary<string, object>();
superProperties["channel"] = "te";//string
superProperties["age"] = 1;//number
superProperties["isSuccess"] = true;//boolean
superProperties["birthday"] = DateTime.Now;//time
superProperties["object"] = new Dictionary<string, object>(){{ "key", "value"}};//object
superProperties["object_arr"] = new List<object>() {new Dictionary<string, object>(){{ "key", "value" }}};//object array
superProperties["arr"] = new List<object>() { "value" };//array
TDAnalytics.SetSuperProperties(superProperties);//공통 이벤트 속성 설정

공통 이벤트 속성은 캐시에 저장되며, 앱을 시작할 때마다 호출할 필요는 없습니다. 호출하게 되면 setSuperProperties이전에 설정한 공통 이벤트 속성은 덮어씌워집니다.

이벤트 속성은 Dictionary<string, object> 타입인 경우, 각 요소별로 속성으로 분리됩니다
Key는 해당 속성의 이름으로 string 타입이며, 영문자와 숫자, "_"를 포함하고, 최대 50자입니다. TE 시스템은 일괄적으로 소문자로 통일됩니다
Value는 해당 속성의 값으로, String, Number, Boolean, Time, object, array, list object를 지원합니다.

이벤트 속성, 유저 속성은 공통 이벤트 속성과 일치해야 합니다.

# 3.3 자동 수집 이벤트의 On/Off

클라이언트 SDK는 일부 이벤트를 자동으로 수집할 수 있으며, 실제 업무 상황에 따라 on/off를 설정해 주세요.

// 자동 추적 이벤트 활성화
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);

이벤트 이름은 string 타입이며, 영문자와 숫자, "_"를 포함하여 최대 50자까지 입력 가능합니다.

# 3.5 유저 속성 설정

일반적인 유저 속성은 UserSet을 사용하여 설정할 수 있으며, UserSet은 기존 값을 덮어씁니다. 원래 해당 속성에 값이 없는 경우, 속성이 새로 생성됩니다. 다음은 코드 예시입니다.

// 이름이 이제 TA입니다
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
// 이름이 이제 TE입니다
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TE"}});

# 4. 코드 예시 (Example Code)

아래의 코드 예시에 모든 작업이 포함되어 있으며, 아래 순서대로 사용하는 것을 권장합니다:

if (Authorized Privacy Policy)
{  
   // SDK 초기화
   TDAnalytics.Init("APPID", "SERVER_URL");
   // 유저가 로그인했다면, 유저의 계정 ID를 고유 식별자로 설정할 수 있습니다
   TDAnalytics.Login("TA");
   // 공통 이벤트 속성 설정 후, 각 이벤트는 공통 속성을 가집니다
   Dictionary<string, object> superProperties = new Dictionary<string, object>();
   superProperties["channel"] = "te";//string
   superProperties["age"] = 1;//number
   superProperties["isSuccess"] = true;//boolean
   superProperties["birthday"] = DateTime.Now;//time
   superProperties["object"] = new Dictionary<string, object>(){{ "key", "value"}};//object
   superProperties["object_arr"] = new List<object>() {new Dictionary<string, object>(){{ "key", "value" }}};//object array
   superProperties["arr"] = new List<object>() { "value" };//array
   TDAnalytics.SetSuperProperties(superProperties);// 공통 속성 설정
   // 자동 추적 활성화
   TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);
   // 이벤트 업로드
   Dictionary<string, object> properties = new Dictionary<string, object>(){{"product_name", "아이템명"}};
   TDAnalytics.Track("product_buy", properties);
   // 유저 속성 설정
   TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
}