Advanced guide

Last updated 10/03/2026

1. Send events

After the SDK is initialized, you can start tracking data to collect user behavior. In most cases, regular events meet business needs. You can also use first events, updatable events, and other event types based on your actual business scenarios.

1.1 Regular events

You can call Track to upload events. We recommend setting event properties and the conditions for sending events according to the document you prepared earlier. The following example tracks a user purchasing a product:

// Set event properties
Dictionary<string, object> properties = new Dictionary<string, object>();
// String
properties.Add("product_name", "goods_name");
properties.Add("price", "123");
// Set at least one of account_id and distinct_id
te.Track("accountId", "distinctId", "product_buy", properties);

1.2 First events

A first event is an event that is recorded only once for a given device or an ID of another dimension. For example, in some scenarios you may want to record the activation event on a device; you can report this data as a first event.

// Report a first event named device_activation
Dictionary<string, object> properties = new Dictionary<string, object>();
//Set event properties
properties.Add("price", 35);
//Set at least one of account_id and distinct_id; the value of first_check_id cannot be empty
te.TrackFirst("accountId", "distinctId", "device_activation", "first_check_id", properties);

Note: Because the first-event check is performed on the server, first events are stored with a 1-hour delay by default.

1.3 Updatable events

You can use updatable events to modify event data in specific scenarios. An updatable event requires an ID that identifies the event, which you pass in when you create the updatable event object. The AE backend determines which data to update based on the event name and event ID.

// Upload an updatable event named UPDATABLE_EVENT
// The event properties are status 3 and price 100
Dictionary<string, object> properties = new Dictionary<string, object>();
properties.Add("price", 100);
properties.Add("status", 3);
te.TrackUpdate("accountId", "distinctId", "UPDATABLE_EVENT", "event_id", properties);

// After reporting, status is updated to 5 and price stays the same
Dictionary<string, object> newProperties = new Dictionary<string, object>();
newProperties.Add("status", 5);
//Set at least one of account_id and distinct_id; event_id cannot be empty
te.TrackUpdate("accountId", "distinctId", "UPDATABLE_EVENT", "event_id", newProperties);

1.4 Overwritable events

Overwritable events are similar to updatable events, except that an overwritable event completely overwrites historical data with the latest data. In effect, the previous record is deleted and the latest data is ingested. The AE backend determines which data to update based on the event name and event ID.

// Report an overwritable event named OVERWRITE_EVENT
// After reporting, the event properties are status 3 and price 100
Dictionary<string, object> properties = new Dictionary<string, object>();
properties.Add("price", 100);
properties.Add("status", 3);
//Set at least one of account_id and distinct_id; event_id cannot be empty
te.TrackOverwrite("accountId", "distinctId", "OVERWRITE_EVENT", "event_id", properties);

// After reporting, status is updated to 5 and the price property is deleted
Dictionary<string, object> newProperties = new Dictionary<string, object>();
newProperties.Add("status", 5);
//Set at least one of account_id and distinct_id; event_id cannot be empty
te.TrackOverwrite("accountId", "distinctId", "OVERWRITE_EVENT", "event_id", newProperties);

2. User properties

The user property APIs supported by the AE platform are: UserSet, UserSetOnce, UserAdd, UserUnSet, UserDelete, UserAppend, and UserUniqAppend.

2.1 UserSet

For general user properties, you can call UserSet to set them. Properties uploaded through this API overwrite the original values. If the user property doesn't exist yet, it is created with the same type as the value passed in. The following example sets the username:

//user_name is now TA
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("user_name","TA");
te.UserSet("accountId","distinctId", properties);
//user_name is now AE
Dictionary<string, object> newProperties= new Dictionary<string, object>();
newProperties.Add("user_name","AE");
//Set user properties; set at least one of accountId and distinctId
te.UserSet("accountId","distinctId", newProperties);

2.2 UserSetOnce

If a user property only needs to be set once, you can call UserSetOnce to set it. If the property already has a value, this call is ignored. The following example sets the first payment time:

//first_payment_time is 2018-01-01 01:23:45.678
Dictionary<string, object> properties = new Dictionary<string, object>();
properties.Add("first_payment_time", "2018-01-01 01:23:45.678");
te.UserSetOnce("accountId", "distinctId", properties);
//first_payment_time is still 2018-01-01 01:23:45.678
Dictionary<string, object> newProperties = new Dictionary<string, object>();
newProperties.Add("first_payment_time", "2018-12-31 01:23:45.678");
te.UserSetOnce("accountId", "distinctId", newProperties);

2.3 UserAdd

To upload a numeric property, you can call UserAdd to accumulate its value. If the property hasn't been set yet, it is assigned 0 before the calculation. You can pass a negative value, which is equivalent to subtraction. The following example accumulates the total payment amount:

//Upload user properties; the value of "total_revenue" is now 30
Dictionary<string, object> properties = new Dictionary<string, object>();
properties.Add("total_revenue", 30);
te.UserAdd("accountId", "distinctId", properties);

//Upload user properties again; the value of "total_revenue" accumulates to 678
Dictionary<string, object> newProperties = new Dictionary<string, object>();
newProperties.Add("total_revenue", 648);
te.UserAdd("accountId", "distinctId", newProperties);

The property key is a string, and the Value can only be a number.

2.4 UserAppend

You can call UserAppend to append values to an array-type user property.

Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list = new List<string>();
list.Add("ball");
dictionary.Add("user_list", list);
te.UserAppend("accountId", "distinctId", dictionary);

2.5 UserUniqAppend

You can call UserUniqAppend to append elements to an array-type user property. Calling UserUniqAppend deduplicates the appended user property values, whereas the UserAppend API doesn't deduplicate, so the user property may contain duplicates.

//The value of user_list is now ["apple","ball"]     
Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list = new List<string>();
list.Add("apple");
list.Add("ball");
dictionary.Add("user_list", list);
te.UserAppend("accountId", "distinctId", dictionary);

//The value of user_list is now ["apple","apple","ball","cube"]
Dictionary<string, object> newDictionary = new Dictionary<string, object>();
List<string> newList = new List<string>();
newList.Add("apple");
newList.Add("cube");
newDictionary.Add("user_list", newList);
te.UserAppend("accountId", "distinctId", newDictionary);

//The value of user_list is now ["apple","ball","cube"]
te.UserUniqAppend("accountId", "distinctId", newDictionary);

2.6 UserUnSet

To clear the value of a user property, you can call UserUnSet to clear the specified property. If the property hasn't been created in the cluster yet, UserUnSet does not create it

// Delete a property of this user. The argument must be a collection of strings, for example:
List<string> list = new List<string>();
list.Add("nickname");
list.Add("age");
te.UserUnSet("accountId", "distinctId", list);

user_unset: The value passed in is the Key of the property to clear.

2.7 UserDelete

To delete a user, you can call UserDelete. After that, you can no longer query this user's user properties, but the events generated by the user can still be queried. This operation may have irreversible consequences, so use it with caution

te.UserDelete("accountId", "distinctId");

3. Other features

3.1 TDBatchConsumer

Note

When the data volume is too large or the network is abnormal, data may be lost. We don't recommend using it in the production environment

Transfers data to the AE server in batches in real time, without a transfer tool.

TDAnalytics te = new(new TDBatchConsumer("SERVER_URL", "APPID", true));

Parameters:

• APPID: The APPID of your project, which you can find on the Project Settings page in the AE backend

• SERVER_URL: The URL that data is uploaded to

  • If you use the cloud service, enter: https://global-receiver-ta.thinkingdata.cn
  • If you use an on-premises deployment, bind a domain name to the data collection URL and configure an HTTPS certificate: https://your-domain-for-data-collection

3.2 Scheduled flush

By default, the SDK reports data automatically based only on the current data size. You can configure the TDLoggerConsumer.TDConfig parameter to enable scheduled data submission.

using ThinkingData.Analytics;

 TDLoggerConsumer.TDConfig config = new TDLoggerConsumer.TDConfig();
 //Submit data every 3S (default: 10S)
 config.BatchSec = 3;

 TDAnalytics te = new(new TDLoggerConsumer("LOG_DIRECTORY", config));