Advanced guide

Last updated 10/05/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
local properties = {}
--Set the time when the event occurred. If you don't set it, the current time is used by default
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

--Set the user's IP address. The AE system parses the user's geographic location from the IP address. If you don't set it, it is not reported by default
properties["#ip"] = "192.168.1.1"

properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--Upload the event with the user's distinct ID and account ID. Note the order of the account ID and the distinct ID
sdk:track("accountId", "distinctId", "payment", 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.

local properties = {}
--You need to set the value of first_check_id
sdk: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.

-- "price" is 80, "count" is 3
local properties = {}
properties["price"] = 80
properties["count"] = 3
sdk:trackUpdate("accountId", "distinctId", "eventName", "eventId", properties)

-- The "price" is still 80, The "count" has changed to 5
local newProperties = {}
newProperties["count"] = 5
sdk:trackUpdate("accountId", "distinctId", "eventName", "eventId", 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.

-- "price" is 80, "count" is 3
local properties = {}
properties["price"] = 80
properties["count"] = 3
sdk:trackOverwrite("accountId", "distinctId", "eventName", "eventId", properties)

-- The "count" has changed to 5，The "price" will be deleted
local newProperties = {}
newProperties["count"] = 5
sdk:trackOverwrite("accountId", "distinctId", "eventName", "eventId", newProperties)

2. User properties

The user property APIs supported by the AE platform are: userSet, userSetOnce, userAdd, userUnset, userDel, userAppend, and userUniqueAppend.

2.1 userSet

For general user properties, you can call userSet to set them. Properties uploaded through this API overwrite the existing property values. If the user property does not exist yet, it is created with the same type as the value passed in. The following example sets the user name:

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties
sdk:userSet("accountId", "distinctId", userSetProperties)

userSetProperties = {}
userSetProperties["user_name"] = "abc"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties again. The value of "user_name" is overwritten with "abc"
sdk:userSet("accountId", "distinctId", userSetProperties)

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. Again, take setting the user name as an example:

local userSetOnceProperties = {}
userSetOnceProperties["user_name"] = "ABC"
userSetOnceProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties. "user_name" is created with the value "ABC"
sdk:userSetOnce("accountId", "distinctId", userSetOnceProperties)

userSetOnceProperties = {}
userSetOnceProperties["user_name"] = "abc"
userSetOnceProperties["user_age"] = 18
userSetOnceProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties again. The value of "user_name" is not overwritten and remains "ABC". The value of "user_age" is 18
sdk:userSetOnce("accountId", "distinctId", userSetOnceProperties)

2.3 userAdd

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

local userAddProperties = {}
userAddProperties["total_revenue"] = 30
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties. The value of "total_revenue" is 30
sdk:userAdd("accountId", "distinctId", userAddProperties)

userAddProperties = {}
userAddProperties["total_revenue"] = 60
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties again. The value of "total_revenue" is accumulated to 90
sdk:userAdd("accountId", "distinctId", userAddProperties)

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

2.4 userAppend

You can call userAppend to append elements to an array-type user property.

local equips = {}
equips[1] = "weapon"
equips[2] = "hat"
local userAppendProperties = {}
userAppendProperties["equips"] = equips
userAppendProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties. The value of "equips" is ["weapon", "hat"]
sdk:userAppend("accountId", "distinctId", userAppendProperties)

equips = {}
equips[1] = "clothes"
userAppendProperties = {}
userAppendProperties["equips"] = equips
userAppendProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties again. "clothes" is added to the value of "equips": ["weapon", "hat", "clothes"]
sdk:userAppend("accountId", "distinctId", userAppendProperties)

2.5 userUniqueAppend

You can call userUniqueAppend to append values to a user property of the array type. userUniqueAppend deduplicates the appended user property values, whereas userAppend doesn't, so the user property may contain duplicates.

local profiles_append = {}
--After execution, the user property append is ["test_append"]
profiles_append["append"] = { "test_append" }
sdk:userAppend("accountId", "distinctId", profiles_append)

local profiles_uniq_append = {}
--After execution, the user property append is ["test_append", "test_append1"]
profiles_uniq_append["append"] = {"test_append", "test_append1"}
sdk:userUniqueAppend("accountId", "distinctId", profiles_uniq_append)

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 doesn't create it

local userUnsetProperties = {}
userUnsetProperties[1] = "total_revenue"
userUnsetProperties[2] = "equips"
--Upload user properties. The "total_revenue" and "equips" properties are reset
sdk:userUnset("accountId", "distinctId", userUnsetProperties)

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

2.7 userDel

To delete a user, you can call userDel. After that, you can no longer query the 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

sdk:userDel("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.

local tdAnalytics = require "ThinkingDataSdk"
local consumer = tdAnalytics.TDBatchConsumer("SERVER_URL", "APP_ID")
local sdk = tdAnalytics(consumer)

Parameters:

• APP_ID: The APP ID of your project, which you can find on the project management 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