Skip to main content

Advanced guide

Last updated 08/27/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:

distinct_id = "ABCDEF123456"
account_id = "TE10001"
properties = {
    "#time": datetime.datetime.now(),
    # Set the time when this event occurred. If not set, the current time is used by default
    "#ip": "192.168.1.1",
    # Set the user's IP. tda automatically resolves the province and city from this IP
    # "#uuid":uuid.uuid1(),# Optional. Not needed if the enable_uuid switch above is turned on
    "Product_Name": "Product name",
    "Price": 30,
    "OrderId": "Order abc_123"
}

# Upload an event with both the account ID and the distinct ID
try:
    te.track(distinct_id, account_id, "Payment", properties)
    # You can also upload only the distinct ID
    # te.track(distinct_id = distinct_id, event_name = "Payment", properties = properties)
    # Or upload only the account ID
    # te.track(account_id = account_id, event_name = "Payment", properties = properties)
except Exception as e:
    # Exception handling
    print(e)

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
try:
    properties = {'name': 'hello'}
    te.track_first(account_id="account_id", distinct_id="distinct_id", event_name='first_event', first_check_id='first_flag_id', properties=properties)
except Exception as e:
    # Exception handling
    raise TDIllegalDataException(e)

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.

# Example: report an updatable event, assuming the event name is UPDATABLE_EVENT
distinct_id = "65478cc0-275a-4aeb-9e6b-861155b5aca7"
account_id = "123"
event_name = "UPDATABLE_EVENT"
event_id = "123"
properties = {
    "price": 100,
    "status": 3
}
# After reporting, the event properties are status 3 and price 100
te.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                properties=properties)

# After reporting, the status property of the event with the same event_name + event_id is updated to 5, and price stays unchanged
new_properties = {
    "status": 5
}
te.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                properties=new_properties)

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.

# Example: report an overwritable event, assuming the event name is OVERWRITE_EVENT
distinct_id = "65478cc0-275a-4aeb-9e6b-861155b5aca7"
account_id = "123"
event_name = "OVERWRITE_EVENT"
event_id = "123"
properties = {
    "price": 100,
    "status": 3
}
# After reporting, the event properties are status 3 and price 100
te.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                   properties=properties)

# After reporting, the event property status is updated to 5, and the price property is deleted
new_properties = {
    "status": 5
}
te.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                   properties=new_properties)

2. User properties​

The user property APIs supported by the AE platform are: user_set, user_setOnce, user_add,

user_unset、user_del、user_append、user_uniq_append。

2.1 user_set​

For general user properties, you can call user_set 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:

properties = {"user_name": "ABC"}
# Upload user properties. The value of "user_name" is "ABC"
try:
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
    properties = {"user_name": "XYZ"}
    # Upload user properties again. The value of "user_name" is overwritten with "XYZ"
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # Exception handling
    print(e)

2.2 user_setOnce​

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

properties = {"user_name": "ABC"}
# Upload user properties. The value of "user_name" is "ABC"
try:
    te.user_setOnce(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # Exception handling
    print(e)
properties = {
    "user_name": "XYZ",
    "user_age": 18
}
# Upload user properties again. "user_name" already has a value, so it is not modified and remains "ABC"; the value of "user_age" is 18
try:
    te.user_setOnce(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # Exception handling
    print(e)

2.3 user_add​

To upload a numeric property, you can call user_add 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:

properties = {
    "total_revenue": 30,
    "vip_level": 1
}
# Upload user properties. The value of "total_revenue" is 30 and the value of "vip_level" is 1
te.user_add(account_id="account_id", distinct_id="distinct_id", properties=properties)

properties = {"total_revenue": 90}
# Upload user properties. The value of "total_revenue" is 90 and the value of "vip_level" is 1
try:
    te.user_add(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # Exception handling
    print(e)

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

2.4 user_append​

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

list1 = ['Google']
# Append values to the array properties arrKey1 and arrKey2
properties = {'arrKey1': list1, 'arrKey2': ['11', '22']}
try:
    te.user_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # Exception handling
    print(e)

2.5 user_uniq_append​

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

arrayValue = ['Google', 'True', '2.222']
properties = {'arrKey4': arrayValue, 'arrKey3': ['appendList', '222'], 'dict1': {'name': 'Tom', 'Age': 28}}
try:
    # After execution, the user property arrKey4 is ['Google', True, 2.222] and arrKey3 is ['appendList', '222']
    te.user_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # Exception handling
    raise TDIllegalDataException(e)

properties = {'arrKey4': ['addValue', 'True'], 'arrKey3': ['appendList', '222']}
try:
    # After execution, the user property arrKey4 is ['Google', True, 2.222, 'addValue'] and arrKey3 is ['appendList', '222']
    te.user_uniq_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # Exception handling
    raise TDIllegalDataException(e)

2.6 user_unset​

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

try:
    te.user_unset("distinct_id", "account_id", ["string1", "lastTime"])
except Exception as e:
    # Exception handling
    print(e)

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

2.7 user_del​

To delete a user, you can call user_del. 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.

try:
    te.user_del(account_id="account_id", distinct_id="distinct_id")
except Exception as e:
    # Exception handling
    print(e)

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.

te = TDAnalytics(TDBatchConsumer("SERVER_URL", "APP_ID"))

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
Was this page helpful?
On this page