본문으로 건너뛰기

고급 가이드

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

1. 유저 ID 설정​

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

1.1 게스트 ID 설정​

팁

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

App에서 유저별로 자체 게스트 ID 관리 체계를 갖추고 있다면 setDistinctId를 호출하여 게스트 ID를 설정할 수 있습니다:

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

현재 게스트 ID를 가져와야 하는 경우 getDistinctId를 호출합니다.

//게스트 ID 반환
let distinctId = TDAnalytics.getDistinctId();

설정이 필요한 경우 반드시 초기화 전에 이 인터페이스를 호출해야 합니다

1.2 계정 ID 설정​

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

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

이 메서드는 유저 로그인 이벤트를 업로드하지 않습니다

1.3 계정 ID 지우기​

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

// 전송 데이터에서 "#account_id"를 제거하며, 이후 데이터에는 "#account_id"가 포함되지 않습니다
TDAnalytics.logout();

이 메서드는 유저 로그아웃 이벤트를 업로드하지 않습니다

2. 이벤트 전송​

2.1 일반 이벤트​

track을 직접 호출하여 커스텀 이벤트를 업로드할 수 있습니다. 앞서 정리한 문서에 따라 이벤트 속성과 정보 전송 조건을 설정하는 것을 권장합니다. 여기서는 상품 구매를 예로 듭니다:

TDAnalytics.track({
    eventName: "product_buy", // 이벤트 이름
    properties: {
        product_name: "상품명"
    } //이벤트 속성
});
  • track 인터페이스에는 파라미터가 두 개 있습니다. 첫 번째 파라미터는 이벤트 이름이고, 두 번째 파라미터는 이벤트 속성입니다
  • 이벤트 이름은 문자열이며, 영문자로만 시작할 수 있고 숫자, 영문자, 밑줄 "_"을 포함할 수 있습니다. 최대 길이는 50자이며 대소문자를 구분하지 않습니다.
  • 이벤트 속성은 JS 객체이며, 각 요소가 하나의 속성을 나타냅니다.
  • 요소의 name은 속성 이름에 해당하며, 영문자로만 시작할 수 있고 숫자, 영문자, 밑줄 "_"을 포함할 수 있습니다. 최대 길이는 50자이며 대소문자를 구분하지 않습니다.
  • 요소의 Value는 해당 속성의 값으로, String, Number, Boolean, Date, Object, Array를 지원합니다. Object의 내용은 String, Number, Boolean, Date, Array(내용은 문자열)일 수 있고, Array의 내용은 Object와 String일 수 있습니다

2.2 최초 이벤트​

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

TDAnalytics.trackFirst({
    eventName: "device_activation",
    properties: { key: "value" }
});

디바이스 이외의 다른 차원으로 최초 여부를 판단하려면 최초 이벤트에 first_check_id를 설정할 수 있습니다. 예를 들어 특정 계정의 최초 이벤트를 기록해야 하는 경우 계정 ID를 최초 이벤트의 first_check_id로 설정할 수 있습니다:

// 유저 ID를 최초 이벤트의 first_check_id로 설정하여 유저의 최초 활성화 이벤트를 수집
TDAnalytics.trackFirst({
  eventName: "account_activation",
  firstCheckId: "TA",
  properties: { key: "value" }
});

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

2.3 업데이트 가능 이벤트​

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

// 예시: 업데이트 가능한 이벤트를 전송합니다. 이벤트 이름은 UPDATABLE_EVENT라고 가정합니다
// 전송 후 이벤트 속성 status는 3, price는 100
TDAnalytics.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id"
});

// 전송 후 이벤트 속성 status는 5로 업데이트되고 price는 변경되지 않음
TDAnalytics.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id"
});

2.4 덮어쓰기 가능 이벤트​

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

// 예시: 덮어쓰기 가능한 이벤트를 전송합니다. 이벤트 이름은 OVERWRITE_EVENT라고 가정합니다
// 전송 후 이벤트 속성 status는 3, price는 100
TDAnalytics.trackOverwrite({
  eventName: "OVERWRITE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id"
});

// 전송 후 이벤트 속성 status는 5로 업데이트되고 price 속성은 삭제됨
TDAnalytics.trackOverwrite({
  eventName: "OVERWRITE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id"
});

2.5 공통 이벤트 속성​

유저의 디바이스 ID, 유입 채널, 유저 상태 등 일부 중요한 속성은 모든 이벤트에 설정해야 합니다. 이때 이러한 속성을 공통 속성, 즉 모든 이벤트에 포함되는 속성으로 설정할 수 있습니다. 이벤트를 보내기 전에 먼저 공통 속성을 설정하는 것을 권장합니다.

공통 속성에는 이벤트 공통 속성과 동적 공통 속성 두 가지가 있습니다. 이벤트를 전송할 때 공통 속성은 데이터의 properties에 삽입됩니다. 이때 공통 속성과 이벤트에 설정한 커스텀 속성의 key 값이 같으면 다음 우선순위에 따라 값을 결정합니다: 커스텀 속성>동적 공통 이벤트 속성>정적 공통 이벤트 속성>시스템 속성

2.5.1 정적 공통 이벤트 속성​

이벤트 공통 속성은 정적 공통 속성을 의미하며, 설정할 때 상수만 전달할 수 있으므로 변하지 않는 안정적인 속성을 설정하는 데 적합합니다. setSuperProperties를 호출하여 공통 이벤트 속성을 설정할 수 있으며, 공통 이벤트 속성의 형식 요구 사항은 이벤트 속성과 같습니다.

속성 우선순위에 따라 커스텀 속성의 우선순위가 이벤트 공통 속성보다 높으므로, 이벤트 공통 속성을 특정 속성의 기본값으로 사용할 수도 있습니다. 수정이 필요한 이벤트에서 같은 이름의 Key를 설정하여 기본값을 덮어쓰면 됩니다.

// 공통 이벤트 속성을 설정하면 모든 데이터 이벤트에 이 속성들이 포함됩니다
TDAnalytics.setSuperProperties({
     channel: "채널명",
     user_name: "사용자 이름"
});

setSuperProperties를 여러 번 호출하여 공통 이벤트 속성을 설정하면 같은 이름의 필드는 나중 호출이 이전 값을 덮어쓰며, 이름이 다른 필드는 유지됩니다.

특정 공통 이벤트 속성을 삭제해야 하는 경우 unsetSuperProperty()를 호출하여 공통 이벤트 속성 하나를 지울 수 있습니다. 모든 공통 이벤트 속성을 비우려면 clearSuperProperties()를 호출하고, 모든 공통 이벤트 속성을 가져오려면 getSuperProperties를 호출할 수 있습니다.

// 정적 공통 이벤트 속성 가져오기
var superProperties = TDAnalytics.getSuperProperties();
// 정적 공통 이벤트 속성 하나 지우기(예: 이전에 설정한 'channel' 속성을 지우면 이후 데이터에는 해당 속성이 포함되지 않음)
TDAnalytics.unsetSuperProperty("channel");
// 모든 정적 공통 이벤트 속성 지우기
TDAnalytics.clearSuperProperties();

2.5.2 동적 공통 이벤트 속성​

동적 공통 속성은 이벤트를 전송할 때 function을 하나 실행하고, 반환값을 해당 동적 공통 속성의 값으로 이벤트에 추가합니다. setDynamicSuperProperties 인터페이스를 호출하여 동적 공통 속성을 설정할 수 있습니다. 이 인터페이스는 function 하나를 파라미터로 받습니다.

// 동적 공통 속성으로 UTC 시간을 이벤트 속성으로 설정하여 전송
TDAnalytics.setDynamicSuperProperties(() => {
  var localDate = new Date();
  return {
    utcTime: new Date(
      localDate.getTime() + localDate.getTimezoneOffset() * 60000
    )
  };
});

function은 반드시 JS 객체를 반환해야 하며, 그 안의 각 요소가 하나의 속성을 나타냅니다. 속성 형식 요구 사항은 이벤트 속성과 같습니다.

2.6 이벤트 지속 시간 기록​

timeEvent를 호출하여 시간 측정을 시작하고, 시간을 측정할 이벤트 이름을 설정할 수 있습니다. 해당 이벤트를 업로드하면 이벤트 속성에 기록된 시간을 나타내는 #duration 속성이 자동으로 추가되며, 단위는 초입니다.

//다음 예시는 유저가 특정 상품 페이지에 머문 시간을 집계합니다
TDAnalytics.timeEvent({
    eventName: "stay_shop"
});
/**do someting
    .......
**/
//유저가 상품 페이지를 떠나면 시간 측정이 종료되며, "stay_shop" 이벤트에 이벤트 지속 시간을 나타내는 속성 #duration이 포함됩니다
TDAnalytics.track({
    eventName: "stay_shop",
    properties: {
        product_name: "상품명"
    }
});

3. 유저 속성​

3.1 userSet​

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

// username은 TA
TDAnalytics.userSet({
    properties: {
        username: "TA" 
    }
});
//username은 AE
TDAnalytics.userSet({
    properties: {
        username: "AE" 
    }
});

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

3.2 userSetOnce​

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

//first_payment_time은 2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    properties: {
        first_payment_time: "2018-01-01 01:23:45.678"
    }
});
//first_payment_time은 여전히 2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    properties: {
        first_payment_time: "2018-12-31 01:23:45.678"
    }
});

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

3.3 userAdd​

숫자형 속성을 업로드할 때 userAdd를 호출하여 해당 속성을 누적할 수 있습니다. 해당 속성이 아직 설정되지 않았으면 0을 할당한 후 계산합니다

//이때 total_revenue는 30
TDAnalytics.userAdd({
    properties: {
        total_revenue: 30
    }
});
//이때 total_revenue는 678
TDAnalytics.userAdd({
    properties: {
        total_revenue: 648
    }
});

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

3.4 userUnset​

유저의 특정 유저 속성 값을 비우려면 userUnset을 호출하여 지정한 속성을 비울 수 있습니다. 해당 속성이 아직 클러스터에 생성되지 않았다면 userUnset은 해당 속성을 생성하지 않습니다

// 이 유저의 유저 속성 이름이 userPropertykey인 유저 속성 값을 비웁니다(즉 NULL로 설정)
TDAnalytics.userUnset({
    property: "userPropertykey"
});

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

3.5 userDelete​

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

TDAnalytics.userDelete();

3.6 userAppend​

userAppend를 호출하여 Array (List) 타입의 유저 데이터에 요소를 추가할 수 있습니다.

TDAnalytics.userAppend({
    properties: {
        user_list: ["apple", "ball"]
    }
});

참고: 이 기능은 AE 플랫폼 2.5 이상 버전과 함께 사용해야 합니다

3.7 userUniqAppend​

v2.1.0부터 userUniqAppend를 호출하여 Array (List) 타입의 유저 데이터에 요소를 중복 제거 후 추가할 수 있습니다.

//이때 user_list의 속성 값은 ["apple"，"ball"]
TDAnalytics.userAppend({
    properties: {
        user_list: ["apple", "ball"]
    }
});
//이때 user_list의 속성 값은 ["apple","apple","ball","cube"]
TDAnalytics.userAppend({
    properties: {
        user_list: ["apple", "cube"]
    }
});
//이때 user_list의 속성 값은 ["apple"，"ball","cube"]
TDAnalytics.userUniqAppend({
    properties: {
        user_list: ["apple", "cube"]
    }
});

참고: 이 기능은 AE 플랫폼 3.6 이상 버전과 함께 사용해야 합니다

5. 기타 기능​

5.1 디바이스 ID 가져오기​

getDeviceId()를 호출하여 디바이스 ID를 가져올 수 있습니다. 실행 환경으로 인해 디바이스 ID는 로컬 캐시에 저장되며, 유저가 캐시를 삭제하면 디바이스 ID가 변경되므로 디바이스 ID가 항상 일정하다고 보장할 수 없습니다

var deviceId = TDAnalytics.getDeviceId();

5.2 onComplete 콜백 함수​

track, userSet, userSetOnce, userAdd, userDelete 등의 인터페이스는 onComplete 콜백 전달을 지원합니다.

원래 파라미터 목록 뒤에 onComplete를 직접 전달할 수도 있고, 파라미터 객체 방식을 사용할 수도 있습니다. 파라미터 객체를 사용하는 경우 파라미터 객체에 반드시 onComplete가 포함되어야 하며, 그렇지 않으면 파라미터 오류가 발생합니다.

이벤트 업로드를 예로 듭니다:

TDAnalytics.track({
  eventName: "test", // 필수
  properties: { testkey: 123 }, // 선택
  time: new Date(),
  onComplete: res => {
    console.log(res);
  }
});

onComplete의 파라미터 res는 object 타입이며, code와 msg 두 가지 속성이 있습니다.

res.code는 int 타입이며, 정의는 다음과 같습니다:

  • 0: 성공
  • -1: 데이터 형식이 올바르지 않음
  • -2: APP ID가 유효하지 않음
  • -3: 네트워크 또는 서버 측 오류

Debug 모드의 정의는 다음과 같습니다:

  • 0: 성공
  • -1: 파라미터 또는 권한 검증 문제
  • 1: 필드의 기본 오류를 나타내며, 상세한 오류 필드와 원인을 제공합니다
  • 2: 데이터 전체 오류를 나타냅니다
  • -3: 네트워크 또는 서버 측 오류

res.msg는 res.code에 대한 텍스트 설명입니다.

5.3 이벤트 캐시 전송 설정​

v2.2.0부터 초기화할 때 이벤트 캐시 전송을 활성화하도록 설정할 수 있습니다.

// AE SDK 설정 객체
var config = {
  appId: "YOU-APP-ID", // 프로젝트의 APP ID
  serverUrl: "https://youserverurl.com", // 데이터 전송 주소
  enableBatch: true, // 이벤트 캐시 일괄 전송 활성화 여부(true=활성화, false=비활성화)
  batchConfig: {
    size: 5, // 이벤트 캐시 전송 건수
    interval: 5000 // 이벤트 캐시 전송 간격(밀리초)
  }
};
// 초기화
TDAnalytics.init(config);

6. 채널 SDK 호환​

6.1 Tencent Ads​

6.1.1 방안 개요​

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

6.1.2 연동 절차​

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

dn-sdk-minigame.cjs.js 파일을 TDAnalytics SDK와 같은 디렉터리에 넣습니다.

  1. 초기화
노트

TDAnalytics SDK 버전은 >= 3.0.4여야 합니다

TDAnalytics.init({
    appId: 'AppId',
    serverUrl: 'ServerUrl',
    tgaInitParams: {
        user_action_set_id: 100001,// 데이터 소스 ID, 숫자, 필수
        secret_key: '5e853xxxxxxd57a690xxxxxxxxxx',// 암호화 key, 필수
        appid: 'wx123xyz123xyz123x',//위챗 미니 게임 APPID, wx로 시작, 필수
    },
    reportingToTencentSdk: 2,//1 Tencent에만 전송 2 Tencent와 AE에 동시 전송 3 AE에만 전송
    debugMode: 'debug'// debug 모드이면 Tencent Ads SDK의 로컬 디버그 로그를 출력합니다
})
  1. 유저 ID 설정
  • setOpenId

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

wx.request({
    url: 'openid를 가져오고 가입 유저 여부를 판단하는 백엔드 인터페이스 url', 
    success: function(res){
        if(res.openid){ 
          // opneid 설정. 반드시 openid를 먼저 설정한 후 가입 행동을 전송해야 합니다. setOpenId는 동기 메서드이므로 설정 후 바로 가입 행동을 전송할 수 있습니다.            
          TDAnalytics.login(res.openid);
          
          //가입 행동 전송. 백엔드 인터페이스에서 가입 유저 여부를 판단합니다
          if(res.isRegisterUser){
           TDAnalytics.track({
                eventName: "REGISTER"
            });
          }
        }
    }
});
  • setUnionId

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

wx.request({
    url: 'openid를 가져오고 가입 유저 여부를 판단하는 백엔드 인터페이스 url', 
    success: function(res){
        if(res.unionid){ 
          // unionid 설정. openid를 우선 사용하고, openid가 없거나 백엔드에서 unionid를 일괄 사용하는 경우에만 설정합니다.           
          TDAnalytics.setDistinctId(res.unionid);
          
          //가입 행동 전송. 백엔드 인터페이스에서 가입 유저 여부를 판단합니다
          if(res.isRegisterUser){
           TDAnalytics.track({
                eventName: "REGISTER"
            });
          }
        }
    }
});
  1. 행동 전송
TDAnalytics.track({
    eventName: "product_buy", // 이벤트 이름
    properties: {
        product_name: "상품명"
    } //이벤트 속성
});

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

이벤트이벤트 이름이벤트 속성(다음 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',

}

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

TDAnalytics.track({
    eventName: "UPDATE_LEVEL", 
    properties: {
        level: 2,
        power: 85,
    }
});
이 문서가 도움이 되었나요?
이 페이지의 내용