고급 가이드

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

1. 유저 ID 설정

SDK 인스턴스는 기본적으로 랜덤 UUID를 각 유저의 기본 게스트 ID로 사용하며, 이 ID는 유저가 로그인하지 않은 상태에서 신원을 식별하는 ID로 사용됩니다. 게스트 ID는 유저가 앱을 재설치하거나 디바이스를 변경하면 바뀐다는 점에 유의하십시오.

1.1 게스트 ID 설정

팁

일반적으로 게스트 ID를 직접 정의할 필요는 없습니다. 유저 식별 규칙을 충분히 이해한 후 게스트 ID를 설정하십시오.

게스트 ID를 교체해야 하는 경우 SDK 초기화가 끝난 직후에 호출해야 합니다. 불필요한 계정이 생기지 않도록 여러 번 호출하지 마십시오.

App에 유저별 자체 게스트 ID 관리 체계가 있다면 SetDistinctId를 호출하여 게스트 ID를 설정할 수 있습니다:

// 게스트 ID를 Thinker로 설정
TDAnalytics.SetDistinctId("Thinker");

현재 게스트 ID를 가져오려면 GetDistinctId를 호출합니다:

//게스트 ID 반환
String distinctId = TDAnalytics.GetDistinctId();

1.2 계정 ID 설정

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

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

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

1.3 계정 ID 지우기

유저가 로그아웃한 후 Logout을 호출하여 계정 ID를 지울 수 있습니다. 다음에 Login을 호출하기 전까지는 게스트 ID를 신원 식별 ID로 사용합니다.

TDAnalytics.Logout();

Logout은 명시적인 로그아웃 이벤트가 발생했을 때, 예를 들어 유저가 계정에서 로그아웃하는 행동을 했을 때만 호출하고, App을 닫을 때는 호출하지 않는 것을 권장합니다.

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

2. 이벤트 전송

SDK 초기화가 완료되면 데이터 트래킹을 진행하여 유저의 행동 정보를 수집할 수 있습니다. 일반적으로 일반 이벤트로 비즈니스 시나리오의 요구 사항을 충족할 수 있으며, 실제 비즈니스 시나리오에 따라 최초 이벤트, 업데이트 가능 이벤트 등을 사용할 수도 있습니다.

2.1 일반 이벤트

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

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

2.2 최초 이벤트

최초 이벤트는 특정 디바이스 또는 다른 차원의 ID에 대해 한 번만 기록되는 이벤트입니다. 예를 들어 어떤 시나리오에서는 특정 디바이스에서 처음 발생한 이벤트를 기록하고 싶을 수 있으며, 이때 최초 이벤트로 데이터를 전송할 수 있습니다.

Dictionary<string, object> properties = new Dictionary<string, object>() { 
    { "status", 1} 
};
TDFirstEventModel firstEvent = new TDFirstEventModel("first_event");
firstEvent.Properties = properties;
TDAnalytics.Track(firstEvent);

디바이스 이외의 다른 차원으로 최초 여부를 판단하려면 최초 이벤트에 first_check_id를 직접 지정할 수 있습니다.

// 유저 ID를 최초 이벤트의 first_check_id로 설정하여 유저의 최초 활성화 이벤트를 수집
Dictionary<string, object> properties = new Dictionary<string, object>() { 
    { "status", 1} 
};
TDFirstEventModel firstEvent = new TDFirstEventModel("first_event", "any-user-id");
firstEvent.Properties = properties;
TDAnalytics.Track(firstEvent);

주의: 최초 여부 검증은 서버 측에서 이루어지므로 최초 이벤트는 기본적으로 1시간 지연되어 저장됩니다.

2.3 업데이트 가능 이벤트

업데이트 가능 이벤트를 사용하면 특정 시나리오에서 이벤트 데이터를 수정해야 하는 요구를 충족할 수 있습니다. 업데이트 가능 이벤트는 해당 이벤트를 식별하는 ID를 지정해야 하며, 업데이트 가능 이벤트 객체를 생성할 때 전달합니다. AE 백엔드는 이벤트 이름과 이벤트 ID를 기준으로 업데이트할 데이터를 결정합니다.

// 예시: 업데이트 가능한 이벤트를 전송합니다. 이벤트 이름은 UPDATABLE_EVENT라고 가정합니다
// 전송 후 이벤트 속성 status는 3, price는 100
TDUpdatableEventModel updatableEvent = new TDUpdatableEventModel("UPDATABLE_EVENT", "test_event_id");
updatableEvent.Properties = new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
};
TDAnalytics.Track(updatableEvent);

// 전송 후 이벤트 속성 status는 5로 업데이트되고 price는 변경되지 않음
TDUpdatableEventModel updatableEvent_new = new TDUpdatableEventModel("UPDATABLE_EVENT", "test_event_id");
updatableEvent_new.Properties = new Dictionary<string, object>{
    {"status", 5}
};
TDAnalytics.Track(updatableEvent_new);

2.4 덮어쓰기 가능 이벤트

덮어쓰기 가능 이벤트는 업데이트 가능 이벤트와 비슷하지만, 최신 데이터로 과거 데이터를 완전히 덮어쓴다는 점이 다릅니다. 효과 면에서는 이전 데이터를 삭제하고 최신 데이터를 저장하는 것과 같습니다. AE 백엔드는 이벤트 이름과 이벤트 ID를 기준으로 업데이트할 데이터를 결정합니다.

// 예시: 덮어쓰기 가능한 이벤트를 전송합니다. 이벤트 이름은 OVERWRITABLE_EVENT라고 가정합니다
// 전송 후 이벤트 속성 status는 3, price는 100
TDOverwritableEventModel overWritableEvent = new TDOverwritableEventModel("OVERWRITABLE_EVENT", "test_event_id");
overWritableEvent.Properties = new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
};
TDAnalytics.Track(overWritableEvent);

// 전송 후 이벤트 속성 status는 5로 업데이트되고 price 속성은 삭제됨
TDOverwritableEventModel overWritableEvent_new = new TDOverwritableEventModel("OVERWRITABLE_EVENT", "test_event_id");
overWritableEvent_new.Properties = new Dictionary<string, object>{
    {"status", 5}
};
TDAnalytics.Track(overWritableEvent_new);

2.5 공통 이벤트 속성

공통 이벤트 속성은 모든 이벤트에 함께 전송되는 속성입니다. 속성의 업데이트 빈도에 따라 공통 이벤트 속성은 정적 공통 이벤트 속성과 동적 공통 이벤트 속성으로 나뉩니다. 구체적인 비즈니스 시나리오에 따라 서로 다른 공통 이벤트 속성 설정 방법을 선택할 수 있으며, 이벤트를 보내기 전에 먼저 공통 이벤트 속성을 설정하는 것을 권장합니다. 같은 이벤트에서 공통 이벤트 속성, 이벤트 커스텀 속성, 시스템 속성의 Key가 같으면 다음 우선순위에 따라 값을 할당합니다: 커스텀 속성>동적 공통 이벤트 속성>정적 공통 이벤트 속성>시스템 속성.

2.5.1 정적 공통 이벤트 속성

정적 공통 이벤트 속성은 변화 빈도가 낮고 모든 이벤트에 포함되는 속성입니다(예: 유저 회원 등급). setSuperProperties로 정적 공통 이벤트 속성을 설정하면 SDK는 이벤트를 수집할 때 설정된 공통 이벤트 속성을 가져와 이벤트 속성으로 사용합니다.

Dictionary<string, object> superProperties = new Dictionary<string, object>(){ 
    {"vip_level", 2}
};
TDAnalytics.SetSuperProperties(superProperties);

정적 공통 이벤트 속성은 캐시에 저장되므로 앱을 시작할 때마다 호출할 필요가 없습니다. 해당 속성이 이미 있으면 다시 설정한 속성이 원래 속성 값을 덮어쓰고, 이전에 해당 속성이 없었다면 새 속성을 생성합니다. 속성 설정 외에도 일상적인 비즈니스 요구를 충족할 수 있도록 정적 공통 이벤트 속성을 관리하는 다른 API를 제공합니다.

// 속성 이름이 CHANNEL인 공통 속성 지우기
TDAnalytics.UnsetSuperProperty("CHANNEL");
// 모든 공통 속성 비우기
TDAnalytics.ClearSuperProperties();
// 모든 공통 속성 가져오기
TDAnalytics.GetSuperProperties();

2.5.2 동적 공통 이벤트 속성

동적 공통 이벤트 속성은 변화 빈도가 높고 모든 이벤트에 포함되는 속성입니다(예: 유저의 골드 수량). 동적 공통 속성을 설정하려면 먼저 동적 공통 속성 클래스를 새로 만들어 TDDynamicSuperPropertiesHandler 인터페이스를 구현하고 public Dictionary<string, object> GetDynamicSuperProperties() 메서드를 재정의합니다. 이 메서드의 반환값이 설정할 동적 공통 속성입니다. 그런 다음 SetDynamicSuperProperties를 호출하여 동적 공통 속성 객체를 전달합니다. 예시는 다음과 같습니다:

// 1.동적 공통 속성 구현 정의. 이 예시는 골드가 동적으로 변하는 경우를 설정하는 예시입니다
public class DynamicProp : TDDynamicSuperPropertiesHandler
{    
    int coin = 0;
    public Dictionary<string, object> GetDynamicSuperProperties()
    {  
         coin++;
         return new Dictionary<string, object>() {
             {"coin",coin}
         };
    }
}
// 2.동적 공통 속성 설정
TDAnalytics.SetDynamicSuperProperties(new DynamicProp());

2.6 이벤트 지속 시간 기록

특정 이벤트의 지속 시간을 기록해야 하는 경우 TimeEvent를 호출하여 시간 측정을 시작할 수 있습니다. 시간을 측정할 이벤트 이름을 설정하면 해당 이벤트를 업로드할 때 이벤트 속성에 #duration 속성이 자동으로 추가되어 기록된 시간을 나타내며, 단위는 초입니다. 같은 이벤트 이름에 대해서는 시간 측정 작업을 하나만 진행할 수 있다는 점에 유의하십시오.

//다음 예시는 유저가 특정 상품 페이지에 머문 시간을 집계합니다
//유저가 상품 페이지에 진입하면 시간 측정 시작
TDAnalytics.TimeEvent("stay_shop");
 /**do someting
    .......
 **/
//유저가 상품 페이지를 떠나면 시간 측정이 종료되며, "stay_shop" 이벤트에 이벤트 지속 시간을 나타내는 속성 #duration이 포함됩니다
TDAnalytics.Track("stay_shop");

3. 유저 속성

AE 플랫폼에서 지원하는 유저 속성 설정 API는 UserSet, UserSetOnce, UserAdd, UserUnset, UserDelete, UserAppend, UserUniqAppend입니다.

3.1 UserSet

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

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

3.2 UserSetOnce

전송하려는 유저 속성을 한 번만 설정하면 되는 경우 UserSetOnce를 호출하여 설정할 수 있습니다. 해당 속성에 이미 값이 있으면 이 정보는 무시됩니다.

//first_payment_time은 2018-01-01 01:23:45.678
TDAnalytics.UserSetOnce(new Dictionary<string, object>(){
    {"first_payment_time","2018-01-01 01:23:45.678"}
});
 //first_payment_time은 여전히 2018-01-01 01:23:45.678
TDAnalytics.UserSetOnce(new Dictionary<string, object>(){
    {"first_payment_time","2018-12-31 01:23:45.678"}
});

3.3 UserAdd

숫자형 속성을 전송할 때 UserAdd를 호출하여 해당 속성을 누적할 수 있습니다. 해당 속성이 아직 설정되지 않았으면 0을 할당한 후 계산합니다. 음수를 전달할 수도 있으며, 이는 빼기 연산과 같습니다.

//이때 total_revenue는 30
TDAnalytics.UserAdd(new Dictionary<string, object>(){
    {"total_revenue",30}
});
//이때 total_revenue는 678
TDAnalytics.UserAdd(new Dictionary<string, object>(){
    {"total_revenue",648}
});

설정하는 속성 key는 문자열이며, Value는 숫자만 허용됩니다.

3.4 UserUnset

유저의 특정 속성을 초기화해야 하는 경우 UserUnset을 호출하여 해당 유저의 지정한 유저 속성 값을 비울 수 있습니다. 이 인터페이스는 문자열 또는 리스트 타입의 파라미터를 지원합니다.

// 단일 유저 속성 삭제
TDAnalytics.UserUnset("userPropertyName");
// 여러 유저 속성 삭제
List<string> listProps = new List<string>();
listProps.Add("aaa");
listProps.Add("bbb");
listProps.Add("ccc");

TDAnalytics.UserUnset(listProps);

UserUnset: 전달하는 값은 비울 속성의 Key 값입니다.

3.5 UserDelete

특정 유저를 삭제하려면 UserDelete를 호출하여 해당 유저를 삭제할 수 있습니다. 삭제한 후에는 해당 유저의 유저 속성을 더 이상 조회할 수 없지만, 해당 유저가 발생시킨 이벤트는 여전히 조회할 수 있습니다.

TDAnalytics.UserDelete();

3.6 UserAppend

v1.4.0부터 UserAppend를 호출하여 List 타입의 유저 속성에 요소를 추가할 수 있습니다:

List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
// 속성 이름이 user_list인 유저 속성에 요소 2개 추가
TDAnalytics.UserAppend(new Dictionary<string, object>{
    {"user_list", stringList }
});

3.7 UserUniqAppend

v2.4.0부터 UserUniqAppend를 호출하여 List 타입의 유저 속성에 중복을 제거하여 요소를 추가할 수 있습니다. UserUniqAppend 인터페이스를 호출하면 추가하는 유저 속성의 중복이 제거되지만, UserAppend 인터페이스는 중복을 제거하지 않으므로 유저 속성에 중복 값이 존재할 수 있습니다.

//이때 user_list의 속성 값은 ["apple","ball"]
List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
TDAnalytics.UserAppend(new Dictionary<string, object>{
    {"user_list", stringList}
});

List<string> stringList1 = new List<string>();
stringList1.Add("apple");
stringList1.Add("cube");
//이때 user_list의 속성 값은 ["apple","apple","ball","cube"]
TDAnalytics.UserAppend(new Dictionary<string, object>{
    {"user_list", stringList1}
});
//이때 user_list의 속성 값은 ["apple","ball","cube"]
TDAnalytics.UserUniqAppend(new Dictionary<string, object>{
    {"user_list", stringList1}
});

4. 암호화 기능

v2.4.0부터 SDK는 AES+RSA를 사용한 데이터 암호화를 지원합니다. 데이터 암호화 기능은 클라이언트와 서버 측이 함께 구성해야 하므로, 구체적인 사용 방법은 고객 성공 담당자에게 문의하십시오.

TDConfig의 EnableEncrypt 메서드를 호출하여 공개 키와 기본 버전 번호를 전달합니다.

TDConfig tdConfig = new TDConfig(appId, serverUrl);
// 암호화 전송 활성화(iOS/Android만 지원), 기본 버전 번호와 공개 키 설정
tdConfig.EnableEncrypt("YOUR_ENCRYPT_PUBLIC_KEY", 1);
TDAnalytics.Init(tdConfig);

5. 기타 기능

5.1 디바이스 ID 가져오기

GetDeviceId를 호출하여 디바이스 ID를 가져올 수 있습니다:

TDAnalytics.GetDeviceId();
// 디바이스 ID를 게스트 ID로 사용
// TDAnalytics.SetDistinctId(TDAnalytics.GetDeviceId());

5.2 기본 시간대 설정

기본적으로 SDK는 인터페이스를 호출한 시점의 로컬 시간을 이벤트 발생 시간으로 전송합니다. 기본 시간대 설정 인터페이스로 기본 시간대를 지정할 수도 있으며, 이렇게 하면 모든 이벤트의 이벤트 시간이 설정한 시간대에 맞춰 정렬됩니다:

TDConfig tdConfig = new TDConfig(appId, serverUrl);
tdConfig.timeZone = TDTimeZone.UTC;
TDAnalytics.Init(tdConfig);

지정한 시간대로 이벤트 시간을 정렬하면 디바이스의 로컬 시간대 정보가 사라집니다. 디바이스의 로컬 시간대 정보를 유지해야 한다면 현재로서는 이벤트에 관련 속성을 직접 추가해야 합니다.

5.3 시간 보정

SDK는 기본적으로 로컬 시간을 이벤트 발생 시간으로 전송합니다. 유저가 디바이스 시간을 수동으로 변경하면 비즈니스 분석에 영향을 줄 수 있으므로, 이때는 시간 보정을 통해 이벤트 발생 시간의 정확성을 보장할 수 있습니다. 타임스탬프, NTP 두 가지 시간 보정 방식을 제공합니다.

서버 측에서 가져온 현재 타임스탬프로 SDK 시간을 보정할 수 있습니다. 이후 시간을 지정하지 않은 모든 호출(이벤트 데이터 및 유저 속성 설정 작업 포함)은 보정된 시간을 발생 시간으로 사용합니다.

// 1585633785954는 현재 unix 타임스탬프이며 단위는 밀리초로, 베이징 시간 2020-03-31 13:49:45에 해당합니다
TDAnalytics.CalibrateTime(1585633785954);

NTP 서버 주소를 설정할 수도 있습니다. 이후 SDK는 전달된 NTP 서비스 주소에서 현재 시간을 가져와 SDK 시간을 보정하려고 시도합니다. 기본 시간 초과 시간(3초) 내에 올바른 반환 결과를 얻지 못하면 이후 로컬 시간으로 데이터를 전송합니다.

// Apple의 NTP 서비스로 시간 보정
TDAnalytics.CalibrateTimeWithNtp("time.apple.com");

1. NTP 서비스를 사용한 시간 보정에는 어느 정도 불확실성이 있으므로, 타임스탬프 보정 방식을 우선 고려하는 것을 권장합니다

2. 네트워크 상태가 양호할 때 유저 디바이스가 서버 시간을 빠르게 가져올 수 있도록 NTP 서버 주소를 신중하게 선택해야 합니다

5.4 데이터 즉시 전송

일부 비즈니스 시나리오에서 데이터를 AE 서버에 즉시 전송하려면 Flush 인터페이스를 호출하면 됩니다

TDAnalytics.Flush();

5.5 국가/지역 코드 가져오기

일부 비즈니스 시나리오에서 유저 디바이스의 국가/지역 코드를 알아야 하는 경우 GetLocalRegion으로 가져올 수 있습니다

TDAnalytics.GetLocalRegion();

5.6 Lua 방식 호출 지원

Lua 파일에서 직접 호출해야 하는 경우 미리 래핑된 Lua API를 사용할 수 있습니다. 다운로드하려면 클릭하십시오

다운로드가 완료되면 TDAnalytics.lua와 TDAnalyticsProxy.cs를 프로젝트로 가져옵니다.

사용 예시는 다음과 같습니다:

local config = {
    appId = "AppId",
    serverUrl = "ServerUrl",
    enableLog = true, --로그 활성화 여부, 기본값은 false--
    mode = 'debug' --기본값은 normal--
}
--SDK 초기화--
TDAnalytics.init(config);

--유저가 로그인한 경우 유저의 계정 ID를 신원 고유 식별자로 설정할 수 있습니다
TDAnalytics.login("TA")

--공통 이벤트 속성을 설정하면 모든 이벤트에 공통 이벤트 속성이 포함됩니다
local superProperties = {}
superProperties["channel"] = "ta" -- 문자열
superProperties["age"] = 1 -- 숫자
superProperties["isSuccess"] = true -- 불리언
superProperties["birthday"] = os.date("%Y-%m-%d %H:%M:%S") -- 시간
superProperties["object"] = { key="value" } -- 객체
superProperties["object_arr"] = { { key="value" } } -- 객체 그룹
superProperties["arr"] = { "value" } -- 배열
TDAnalytics.setSuperProperties(superProperties) -- 공통 이벤트 속성 설정

--이벤트 전송
TDAnalytics.track("product_buy", {
    product_name="상품명"
});

--유저 속성 설정
TDAnalytics.userSet({
    user_name = "TE"
})

5.7 위챗 미니 게임 자동 수집 이벤트

위챗 미니 게임 플랫폼에서는 현재 show 이벤트, hide 이벤트, launch 이벤트의 자동 수집을 지원하며, 연동 방법은 다음과 같습니다:

위챗 미니 게임 플러그인 다운로드

메뉴 바: Window -> Package Manager -> + -> Add package from git url

PackageManager(git 설치 URL): https://github.com/wechat-miniprogram/minigame-tuanjie-transform-sdk.git

커스텀 매크로

메뉴 바: Edit -> Project Settings -> Scripting Define Symbols

전역 매크로 파라미터 TD_WEIXIN_GAME_MODE 추가

Apply 버튼을 클릭하여 설정을 완료합니다

어셈블리에 의존성 추가

Project 창: ThinkingAnalytics 폴더 -> TDAnalytics(Assembly Definition) -> Assembly Definition References -> + -> WxWasmSDKRuntime

사용 예시는 다음과 같습니다:

// 자동 수집 이벤트 활성화: AppStart는 ta_mg_show, AppEnd는 ta_mg_hide, AppInstall은 ta_mg_launch를 수집
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd | TDAutoTrackEventType.AppInstall);

5.8 IP로 데이터 전송 지원

DNS 하이재킹으로 클라이언트 데이터가 서버로 정상 전송되지 않는 문제를 예방하거나 해결하기 위해, SDK는 ServerUrl을 해석하여 IP를 얻은 다음 IP로 서버에 데이터를 직접 전송합니다. 활성화 예시는 다음과 같습니다.

using ThinkingData.Analytics;

TDConfig config = new TDConfig(appId, serverUrl);
config.EnableDNSService(
    TDDNSService.CloudAli,
    TDDNSService.CloudFlare,
    TDDNSService.CloudGoogle
);
TDAnalytics.Init(config);

열거형 TDDNSService

열거형 값	번호	설명
`CloudFlare`	0	Cloudflare DoH
`CloudAli`	1	Alibaba Cloud DoH
`CloudGoogle`	2	Google DoH

여러 서비스 제공업체를 전달할 수 있으며, SDK는 전달된 순서대로 차례로 시도합니다.

5.9 SDK 오류 콜백 지원

SDK 데이터 전송 또는 관련 작업의 실패를 수신하는 데 사용합니다. 반드시 Init 이후에 호출해야 합니다.

호출 예시 코드는 다음과 같습니다:

using UnityEngine;
using ThinkingData.Analytics;

public class GameAnalytics : MonoBehaviour, TDErrorCallbackHandler
{
    void Start()
    {
        TDConfig config = new TDConfig(appId, serverUrl);
        TDAnalytics.Init(config);
        TDAnalytics.RegisterErrorCallback(this);
        // 다중 인스턴스: TDAnalytics.RegisterErrorCallback(this, appId);
    }

    public void OnSDKErrorCallback(int code, string errorMsg, string ext)
    {
        Debug.Log("TDAnalytics error, code=" + code
            + ", errorMsg=" + errorMsg
            + ", ext=" + ext);
    }
}

파라미터 설명

파라미터	설명
`code`	네이티브 SDK 오류 코드
`errorMsg`	오류 설명 또는 서버 측 반환 정보
`ext`	추가 컨텍스트, 일반적으로 당시의 요청 데이터

오류 코드

오류 코드	플랫폼	설명
1001	Android	네트워크 오류
1002	Android	데이터베이스 삽입 실패
1003	Android	데이터베이스 예외
1004	Android	데이터 전송(Flush) 실패
1006	Android	네트워크 예외
10001	iOS	네트워크 오류

5.10 Douyin 미니 게임 자동 수집 이벤트

Douyin 미니 게임 플랫폼에서는 현재 show 이벤트, hide 이벤트, launch 이벤트의 자동 수집을 지원하며, 연동 방법은 다음과 같습니다:

Douyin 미니 게임 플러그인 설치
커스텀 매크로

메뉴 바: Edit -> Project Settings -> Scripting Define Symbols

전역 매크로 파라미터 TD_DOUYIN_GAME_MODE 추가

Apply 버튼을 클릭하여 설정을 완료합니다

사용 예시는 다음과 같습니다:

// 자동 수집 이벤트 활성화: AppStart는 ta_mg_show, AppEnd는 ta_mg_hide, AppInstall은 ta_mg_launch를 수집
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd | TDAutoTrackEventType.AppInstall);

6. 채널 SDK 호환

6.1 Tencent Ads

6.1.1 방안 개요

TDAnalytics SDK를 통합한 후에는 Tencent Ads SDK를 별도로 통합할 필요가 없습니다. TDAnalytics 초기화 메서드를 실행하면 시스템이 Tencent Ads SDK의 초기화를 자동으로 트리거합니다. 가입, 결제 등 주요 이벤트를 전송하면 시스템이 설정에 따라 이러한 이벤트 정보를 Tencent Ads에 자동으로 전송합니다.

6.1.2 연동 절차

Tencent Ads SDK 다운로드. 현재 1.5.4 버전을 사용하고 있으며, 다른 버전으로 바꿔도 됩니다.
초기화

노트

TDAnalytics SDK의 버전은 >= 3.1.1이어야 합니다

TDConfig config = new TDConfig("APPID","SERVER");
config.reportingToTencentSdk = 2; //1 Tencent에만 전송 2 Tencent와 AE에 전송 3 AE에만 전송
TDAnalytics.Init(config);

Tencent에 데이터를 전송하려면 다음 작업을 수행해야 합니다:

위챗 미니 게임 프로젝트를 내보낸 후 dn-sdk-minigame.js 파일을 프로젝트로 가져오고, game.js를 수정하여 dn-sdk를 불러온 다음 초기화를 완료합니다

import { SDK } from "./dn-sdk-minigame.js";
try {
  // 초기화
  GameGlobal.dnSDK = new SDK({
    user_action_set_id: 123xxxxxx,
    secret_key: 'xxxxxxxxxxxxxxxxxxx',
    appid: 'xxxxxxxxxxxxx',
  });
  // 시작 전송
  GameGlobal.dnSDK.onAppStart();
} catch {

}

유저 ID 설정

setOpenId

openid는 일반적으로 백엔드 인터페이스를 호출하여 비동기로 가져옵니다(openid 가져오는 방법). openid를 가져온 후 sdk.setOpenId() 메서드를 호출하여 설정하십시오. openid와 unionid는 하나만 설정할 수 있으며, openid를 우선 설정합니다.

openid를 가져온 후 호출합니다

TDAnalytics.login(openid);

setUnionId

unionid는 일반적으로 백엔드 인터페이스를 호출하여 비동기로 가져옵니다(unionid 가져오는 방법). unionid를 가져온 후 sdk.setUnionId() 메서드를 호출하여 설정하십시오. openid가 없는 경우에만 이 메서드로 unionid를 설정합니다.

unionid를 가져온 후 호출합니다

TDAnalytics.setDistinctId(unionid);

행동 전송

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

다음 특정 이벤트인 경우 지정된 이벤트 이름으로 전송해야 합니다

이벤트	이벤트 이름	이벤트 속성(다음 key를 포함해야 함)
미니 게임 시작	START_APP	없음
결제	PURCHASE	{ value: 600 }
가입	REGISTER
휴면 유저 재활성화	RE_ACTIVE	{ backFlowDay: 30 }
미니 게임 즐겨찾기	ADD_TO_WISHLIST	{ type: 'default', }
미니 게임 공유	SHARE	{ target: 'APP_MESSAGE' }
캐릭터 생성	CREATE_ROL	{ name: 'SuperMan' }
튜토리얼 완료	TUTORIAL_FINISH	없음
게임 레벨 상승	UPDATE_LEVEL	{ level: 2, power: 85, }
상점 페이지 조회	VIEW_CONTENT	{ // 주요 화면 방문: 상점 item: 'Mall', }
게임 이벤트 조회	VIEW_CONTENT	{ // 주요 화면 방문: 이벤트 item: 'Activity', }

예를 들어 게임 레벨 상승 이벤트는 다음과 같이 전송합니다

Dictionary<string, object> properties = new Dictionary<string, object>();
properties["level"] = 2;
properties["power"] = 85;
2TDAnalytics.Track("product_buy", properties);

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

1. 유저 ID 설정​

1.1 게스트 ID 설정​

1.2 계정 ID 설정​

1.3 계정 ID 지우기​

2. 이벤트 전송​

2.1 일반 이벤트​

2.2 최초 이벤트​

2.3 업데이트 가능 이벤트​

2.4 덮어쓰기 가능 이벤트​

2.5 공통 이벤트 속성​

2.5.1 정적 공통 이벤트 속성​

2.5.2 동적 공통 이벤트 속성​

2.6 이벤트 지속 시간 기록​

3. 유저 속성​

3.1 UserSet​

3.2 UserSetOnce​

3.3 UserAdd​

3.4 UserUnset​

3.5 UserDelete​

3.6 UserAppend​

3.7 UserUniqAppend​

4. 암호화 기능​

5. 기타 기능​

5.1 디바이스 ID 가져오기​

5.2 기본 시간대 설정​

5.3 시간 보정​

5.4 데이터 즉시 전송​

5.5 국가/지역 코드 가져오기​

5.6 Lua 방식 호출 지원​

5.7 위챗 미니 게임 자동 수집 이벤트​

5.8 IP로 데이터 전송 지원​

5.9 SDK 오류 콜백 지원​

5.10 Douyin 미니 게임 자동 수집 이벤트​

6. 채널 SDK 호환​

6.1 Tencent Ads​

6.1.1 방안 개요​

6.1.2 연동 절차​

미니 게임 시작

START_APP

결제

PURCHASE

가입

REGISTER

휴면 유저 재활성화

RE_ACTIVE

미니 게임 즐겨찾기

ADD_TO_WISHLIST

미니 게임 공유

SHARE

캐릭터 생성

CREATE_ROL

튜토리얼 완료

TUTORIAL_FINISH

게임 레벨 상승

UPDATE_LEVEL

상점 페이지 조회

VIEW_CONTENT

게임 이벤트 조회

VIEW_CONTENT

1. 유저 ID 설정

1.1 게스트 ID 설정

1.2 계정 ID 설정

1.3 계정 ID 지우기

2. 이벤트 전송

2.1 일반 이벤트

2.2 최초 이벤트

2.3 업데이트 가능 이벤트

2.4 덮어쓰기 가능 이벤트

2.5 공통 이벤트 속성

2.5.1 정적 공통 이벤트 속성

2.5.2 동적 공통 이벤트 속성

2.6 이벤트 지속 시간 기록

3. 유저 속성

3.1 UserSet

3.2 UserSetOnce

3.3 UserAdd

3.4 UserUnset

3.5 UserDelete

3.6 UserAppend

3.7 UserUniqAppend

4. 암호화 기능

5. 기타 기능

5.1 디바이스 ID 가져오기

5.2 기본 시간대 설정

5.3 시간 보정

5.4 데이터 즉시 전송

5.5 국가/지역 코드 가져오기

5.6 Lua 방식 호출 지원

5.7 위챗 미니 게임 자동 수집 이벤트

5.8 IP로 데이터 전송 지원

5.9 SDK 오류 콜백 지원

5.10 Douyin 미니 게임 자동 수집 이벤트

6. 채널 SDK 호환

6.1 Tencent Ads

6.1.1 방안 개요

6.1.2 연동 절차