进阶指南

最近更新 2026/08/27

一、发送事件

在 SDK 初始化完成之后，您就可以进行数据埋点，收集用户的的行为信息。一般情况下普通事件即可满足业务场景需求，您也可以根据自己的实际业务场景使用首次、可更新等事件。

1.1 普通事件

您可以调用 track 来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送事件的条件，此处以用户购买某商品作为范例：

distinct_id = "ABCDEF123456"
account_id = "TE10001"
properties = {
    "#time": datetime.datetime.now(),
    # 设置这条event发生的时间，如果不设置的话，则默认是当前时间
    "#ip": "192.168.1.1",
    # 设置用户的IP，tda会自动根据该IP解析省份、城市
    # "#uuid":uuid.uuid1(),#选填，如果上面enable_uuid开关打开，不需要填
    "Product_Name": "商品名",
    "Price": 30,
    "OrderId": "订单号abc_123"
}

# 上传事件，包含账号ID与访客ID
try:
    te.track(distinct_id, account_id, "Payment", properties)
    # 您也可以只上传访客ID
    # te.track(distinct_id = distinct_id, event_name = "Payment", properties = properties)
    # 或者只上传账号ID
    # te.track(account_id = account_id, event_name = "Payment", properties = properties)
except Exception as e:
    # 异常处理
    print(e)

1.2 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上的激活事件，则可以用首次事件来上报数据。

# 调用首次事件
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:
    # 异常处理
    raise TDIllegalDataException(e)

注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。

1.3 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。

# 示例: 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
distinct_id = "65478cc0-275a-4aeb-9e6b-861155b5aca7"
account_id = "123"
event_name = "UPDATABLE_EVENT"
event_id = "123"
properties = {
    "price": 100,
    "status": 3
}
# 上报后事件属性 status 为 3, price 为 100
te.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                properties=properties)

# 上报后同样event_name + event_id 的事件属性 status 被更新为 5, price 不变
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 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。

# 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
distinct_id = "65478cc0-275a-4aeb-9e6b-861155b5aca7"
account_id = "123"
event_name = "OVERWRITE_EVENT"
event_id = "123"
properties = {
    "price": 100,
    "status": 3
}
# 上报后事件属性 status 为 3, price 为 100
te.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                   properties=properties)

# 上报后事件属性 status 被更新为 5, price 属性被删除
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)

二、用户属性

AE 平台支持的用户属性设置API有: user_set、user_setOnce、user_add、

user_unset、user_del、user_append、user_uniq_append。

2.1 user_set

对于一般的用户属性，您可以调用 user_set 来进行设置。使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

properties = {"user_name": "ABC"}
# 上传用户属性，"user_name"的值为"ABC"
try:
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
    properties = {"user_name": "XYZ"}
    # 再次上传用户属性，此时"user_name"的值会被覆盖为"XYZ"
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 异常处理
    print(e)

2.2 user_setOnce

如果您要上传的用户属性只要设置一次，则可以调用user_setOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息，再以设置用户名为例：

properties = {"user_name": "ABC"}
# 上传用户属性，"user_name"的值为"ABC"
try:
    te.user_setOnce(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 异常处理
    print(e)
properties = {
    "user_name": "XYZ",
    "user_age": 18
}
# 再次上传用户属性，此时"user_name"已存在值，因此不进行修改，仍为"ABC"；"user_age"的值为18
try:
    te.user_setOnce(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 异常处理
    print(e)

2.3 user_add

当您要上传数值型的属性时，您可以调用user_add来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。此处以累计付费金额为例：

properties = {
    "total_revenue": 30,
    "vip_level": 1
}
# 上传用户属性，此时"total_revenue"的值为30,"vip_level"的值为1
te.user_add(account_id="account_id", distinct_id="distinct_id", properties=properties)

properties = {"total_revenue": 90}
# 上传用户属性，此时"total_revenue"的值为90,"vip_level"的值为1
try:
    te.user_add(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 异常处理
    print(e)

设置的属性key为字符串，Value 只允许为数值。

2.4 user_append

您可以调用 user_append 对数组类型的用户属性进行追加操作。

list1 = ['Google']
# 为arrKey1, 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:
    # 异常处理
    print(e)

2.5 user_uniq_append

您可以调用 user_uniq_append 对 数组类型的用户属性进行追加操作。调用 user_uniq_append 接口会对追加的用户属性进行去重， user_append 接口不做去重，用户属性可存在重复。

arrayValue = ['Google', 'True', '2.222']
properties = {'arrKey4': arrayValue, 'arrKey3': ['appendList', '222'], 'dict1': {'name': 'Tom', 'Age': 28}}
try:
    # 执行之后用户属性arrKey4为['Google', True, 2.222], arrKey3为['appendList', '222']
    te.user_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 异常处理
    raise TDIllegalDataException(e)

properties = {'arrKey4': ['addValue', 'True'], 'arrKey3': ['appendList', '222']}
try:
    # 执行之后用户属性arrKey4为['Google', True, 2.222, 'addValue'], arrKey3为['appendList', '222']
    te.user_uniq_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 异常处理
    raise TDIllegalDataException(e)

2.6 user_unset

当您要清空用户的用户属性值时，您可以调用user_unset来对指定属性进行清空操作，如果该属性还未在集群中被创建，则user_unset不会创建该属性

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

user_unset: 的传入值为被清空属性的 Key 值。

2.7 user_del

如果您要删除某个用户，可以调用user_del将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到，该操作可能产生不可逆的后果，请慎用。

try:
    te.user_del(account_id="account_id", distinct_id="distinct_id")
except Exception as e:
    # 异常处理
    print(e)

三、其他功能

3.1 TDBatchConsumer

注意

当数据量过大或者网络异常时，有数据丢失的风险，不建议在正式环境中使用

批量实时地向 AE 服务器传输数据，不需要搭配传输工具。

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

参数说明:

• APP_ID: 您的项目的 APP ID，可通过在 AE 后台项目管理页面获取

• SERVER_URL: 数据上传的 URL

  • 如果您对接的是云服务，填入: https://global-receiver-ta.thinkingdata.cn
  • 如果您使用私有化部署版本，请为数据采集地址绑定域名，并配置 HTTPS 证书：https://数据采集地址绑定域名