고급 가이드

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

1. 이벤트 전송

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

1.1 일반 이벤트

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

// 이벤트 속성 설정
TDProperties *properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("product_name", "goods_name", strlen("goods_name"), properties));
// 커스텀 속성을 포함한 이벤트 데이터 전송(마찬가지로 account_id와 distinct_id 중 하나 이상을 반드시 설정해야 함)
TD_ASSERT(TD_OK == td_track("account_id", "distinct_id", "product_buy", properties, ta));
td_free_properties(properties);

1.2 최초 이벤트

최초 이벤트는 특정 디바이스 또는 기타 차원의 ID에 대해 한 번만 기록되는 이벤트입니다. 예를 들어 특정 디바이스의 활성화 이벤트를 기록하려는 경우 최초 이벤트로 데이터를 전송할 수 있습니다.

TD_ASSERT(TD_OK == td_track_first_event("account_id", "distinct_id", "device_activation", "first_id", properties, ta));

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

1.3 업데이트 가능 이벤트

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

// 업데이트 가능 이벤트 전송. 이벤트 이름은 UPDATABLE_EVENT, 이벤트 ID는 event_id
// 전송 후 이벤트 속성 status는 3, price는 100
TDProperties *properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("price",100,properties));
TD_ASSERT(TD_OK == td_add_int("status",3,properties));
TD_ASSERT(TD_OK == td_track_update("account_id", "distinct_id", "UPDATABLE_EVENT", "event_id",properties, ta));
td_free_properties(properties);
// 전송 후 같은 이벤트 속성 status는 5로 업데이트되고 price는 변경되지 않음
TDProperties *new_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("status",5,new_properties));
TD_ASSERT(TD_OK == td_track_update("account_id", "distinct_id", "UPDATABLE_EVENT", "event_id",new_properties, ta));
td_free_properties(new_properties);

1.4 덮어쓰기 가능 이벤트

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

// 덮어쓰기 가능 이벤트 전송. 이벤트 이름은 OVERWRITE_EVENT, 이벤트 ID는 event_id
// 전송 후 이벤트 속성 status는 3, price는 100
TDProperties *properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("price",100,properties));
TD_ASSERT(TD_OK == td_add_int("status",3,properties));
TD_ASSERT(TD_OK == td_track_overwrite("account_id", "distinct_id", "OVERWRITE_EVENT", "event_id",properties, ta));
td_free_properties(properties);
// 전송 후 같은 이벤트 속성 status는 5로 업데이트되고 price 속성은 삭제됨
TDProperties *new_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("status",5,new_properties));
TD_ASSERT(TD_OK == td_track_overwrite("account_id", "distinct_id", "OVERWRITE_EVENT", "event_id",new_properties, ta));
td_free_properties(new_properties);

2. 유저 속성

AE 플랫폼에서 지원하는 유저 속성 설정 API는 다음과 같습니다: td_user_set, td_user_setOnce, td_user_add, td_user_unset, td_user_delete, td_user_append, td_user_uniq_append.

2.1 td_user_set

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

//이때 user_name은 TA
TDProperties *user_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("user_name", "TA", strlen("TA"), user_properties));
TD_ASSERT(TD_OK == td_user_set("account_id", "distinct_id", user_properties,ta));
td_free_properties(user_properties);

//이때 user_name은 AE
TDProperties *user_properties2 = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("user_name", "AE", strlen("AE"), user_properties2));
TD_ASSERT(TD_OK == td_user_set("account_id", "distinct_id", user_properties2,ta));
td_free_properties(user_properties2);

2.2 td_user_setOnce

전송하려는 유저 속성을 한 번만 설정하면 되는 경우 td_user_setOnce를 호출하여 설정할 수 있습니다. 해당 속성에 이미 값이 있으면 이 정보는 무시됩니다. 여기서는 최초 결제 시간 설정을 예로 듭니다.

//first_payment_time은 2018-01-01 01:23:45.678
TDProperties *user_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("first_payment_time", "2018-01-01 01:23:45.678", strlen("2018-01-01 01:23:45.678"), user_properties));
TD_ASSERT(TD_OK == td_user_setOnce("account_id", "distinct_id", user_properties,ta));
td_free_properties(user_properties);

//first_payment_time은 여전히 2018-01-01 01:23:45.678
TDProperties *user_properties2 = td_init_properties();
TD_ASSERT(TD_OK == td_add_string("first_payment_time", "2018-12-31 01:23:45.678", strlen("2018-12-31 01:23:45.678"), user_properties2));
TD_ASSERT(TD_OK == td_user_setOnce("account_id", "distinct_id", user_properties2,ta));
td_free_properties(user_properties2);

2.3 td_user_add

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

// 유저 속성 전송. 이때 "total_revenue"의 값은 30
TDProperties *user_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("total_revenue", 30, user_properties));
TD_ASSERT(TD_OK == td_user_add("account_id", "distinct_id", user_properties, ta));
td_free_properties(user_properties);

// 유저 속성 전송. 이때 "total_revenue"의 값은 678
TDProperties *new_user_properties = td_init_properties();
TD_ASSERT(TD_OK == td_add_int("total_revenue",648 , new_user_properties));
TD_ASSERT(TD_OK == td_user_add("account_id", "distinct_id", new_user_properties, ta));
td_free_properties(new_user_properties);

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

2.4 td_user_append

td_user_append를 호출하여 배열 타입의 유저 속성에 요소를 추가할 수 있습니다.

// 이때 user_list의 속성 값은 ["apple","ball"]
TDProperties *array_properties = td_init_properties();
TD_ASSERT(TD_OK == td_append_array("user_list", "apple", strlen("apple"), array_properties));
TD_ASSERT(TD_OK == td_append_array("user_list", "ball", strlen("ball"), array_properties));
TD_ASSERT(TD_OK == td_user_append("account_id", "distinct_id", array_properties, ta));
td_free_properties(array_properties);

// 이때 user_list의 속성 값은 ["apple","apple","ball","cube"]
TDProperties *new_array_properties = td_init_properties();
TD_ASSERT(TD_OK == td_append_array("user_list", "apple", strlen("apple"), new_array_properties));
TD_ASSERT(TD_OK == td_append_array("user_list", "cube", strlen("cube"), new_array_properties));
TD_ASSERT(TD_OK == td_user_append("account_id", "distinct_id", new_array_properties, ta));
td_free_properties(new_array_properties);

2.5 td_user_uniq_append

td_user_uniq_append를 호출하여 배열 타입의 유저 속성에 요소를 추가할 수 있습니다. td_user_uniq_append 인터페이스를 호출하면 추가하는 유저 속성의 중복을 제거합니다. td_user_append 인터페이스는 중복을 제거하지 않으므로 유저 속성에 중복이 있을 수 있습니다.

// 이때 user_list의 속성 값은 ["apple","ball"]
TDProperties *array_properties = td_init_properties();
TD_ASSERT(TD_OK == td_append_array("user_list", "apple", strlen("apple"), array_properties));
TD_ASSERT(TD_OK == td_append_array("user_list", "ball", strlen("ball"), array_properties));
TD_ASSERT(TD_OK == td_user_append("account_id", "distinct_id", array_properties, ta));
td_free_properties(array_properties);

// 이때 user_list의 속성 값은 ["apple","ball","cube"]
TDProperties *new_array_properties = td_init_properties();
TD_ASSERT(TD_OK == td_append_array("user_list", "apple", strlen("apple"), new_array_properties));
TD_ASSERT(TD_OK == td_append_array("user_list", "cube", strlen("cube"), new_array_properties));
TD_ASSERT(TD_OK == td_user_uniq_append("account_id","distinct_id", new_array_properties, ta));
td_free_properties(new_array_properties);

2.6 td_user_unset

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

TD_ASSERT(TD_OK == td_user_unset("account_id", "distinct_id", "test", ta));

td_user_unset: 전달 값은 비울 속성의 Key 값입니다.

2.7 td_user_delete

특정 유저를 삭제하려면 td_user_delete를 호출하여 해당 유저를 삭제할 수 있습니다. 삭제한 후에는 해당 유저의 유저 속성을 더 이상 조회할 수 없지만, 해당 유저가 발생시킨 이벤트는 여전히 조회할 수 있습니다. 이 작업은 되돌릴 수 없는 결과를 초래할 수 있으므로 신중하게 사용하십시오

TD_ASSERT(TD_OK == td_user_delete("account_id", "distinct_id", ta));

3. 기타 기능

3.1 BatchConsumer

주의

데이터양이 너무 많거나 네트워크에 이상이 있으면 데이터가 유실될 위험이 있으므로 운영 환경에서는 사용하지 않는 것을 권장합니다

데이터를 AE 서버로 실시간 일괄 전송하며, 별도의 전송 도구가 필요하지 않습니다. 버퍼 크기를 설정할 수 있으며 기본값은 20입니다. 즉, 버퍼에 보관되는 데이터 총수는 최대 20건입니다(20은 1회 업로드당 batch 값이며 설정 가능).

// 먼저 CMakeLists.txt 파일을 수정하여 TDBatchConsumer 타입의 라이브러리 파일을 패키징

struct TDAnalytics* ta = NULL;
struct TDConsumer* consumer = NULL;

//config 생성
TDConfig *config = td_init_config();
// appid와 url 설정
char* appid = "APPID";
char* serverURL = "SERVER_URL";
TD_ASSERT(TD_OK == td_add_string("push_url", serverURL, strlen(serverURL), config));
TD_ASSERT(TD_OK == td_add_string("appid", appid, strlen(appid), config));

// SDK 인스턴스 생성
if (TD_OK != td_init_consumer(&consumer, config)) {
    fprintf(stderr, "Failed to initialize the consumer.");
    return 1;
}
td_free_properties(config);
if (TD_OK != td_init(consumer, &ta)) {
    fprintf(stderr, "Failed to initialize the SDK.");
    return 1;
}

파라미터 설명:

• APPID: 프로젝트의 APPID로, AE 백엔드의 프로젝트 관리 페이지에서 확인할 수 있습니다

• SERVER_URL: 데이터 전송 URL

  • 클라우드 서비스를 사용하는 경우 다음을 입력합니다: https://global-receiver-ta.thinkingdata.cn
  • 프라이빗 배포 버전을 사용하는 경우 데이터 수집 주소에 도메인을 바인딩하고 HTTPS 인증서를 설정하십시오: https://데이터 수집 주소에 바인딩한 도메인