进阶指南

最近更新 2026/10/05

一、发送事件

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

1.1 普通事件

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

--设置事件属性
local properties = {}
--设置事件发生的时间，如果不设置的话，则默认使用为当前时间
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

--设置用户的ip地址，AE系统会根据IP地址解析用户的地理位置信息，如果不设置的话，则默认不上报
properties["#ip"] = "192.168.1.1"

properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--上传事件，包含用户的访客ID与账号ID，请注意账号ID与访客ID的顺序
sdk:track("accountId", "distinctId", "payment", properties)

1.2 首次事件

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

local properties = {}
--需要设置first_check_id的值
sdk:trackFirst("accountId", "distinctId", "device_activation", "first_check_id", properties)

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

1.3 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。AE 后台将根据事件名和事件 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 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。AE 后台将根据事件名和事件 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)

二、用户属性

AE 平台支持的用户属性设置API有: userSet、userSetOnce、userAdd、userUnset、userDel、userAppend、userUniqueAppend。

2.1 userSet

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

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--上传用户属性
sdk:userSet("accountId", "distinctId", userSetProperties)

userSetProperties = {}
userSetProperties["user_name"] = "abc"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--再次上传用户属性，此时"user_name"的值会被覆盖为"abc"
sdk:userSet("accountId", "distinctId", userSetProperties)

2.2 userSetOnce

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

local userSetOnceProperties = {}
userSetOnceProperties["user_name"] = "ABC"
userSetOnceProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--上传用户属性，新建"user_name"，值为"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")
--再次上传用户属性，此时"user_name"的值不会被覆盖，仍为"ABC"，"user_age"的值为18
sdk:userSetOnce("accountId", "distinctId", userSetOnceProperties)

2.3 userAdd

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

local userAddProperties = {}
userAddProperties["total_revenue"] = 30
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--上传用户属性，此时"total_revenue"的值为30
sdk:userAdd("accountId", "distinctId", userAddProperties)

userAddProperties = {}
userAddProperties["total_revenue"] = 60
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--再次上传用户属性，此时"total_revenue"的值会累加为90
sdk:userAdd("accountId", "distinctId", userAddProperties)

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

2.4 userAppend

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

local equips = {}
equips[1] = "weapon"
equips[2] = "hat"
local userAppendProperties = {}
userAppendProperties["equips"] = equips
userAppendProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--上传用户属性，此时"equips"的值为["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")
--再次上传用户属性，此时"equips"的值会增加一个"clothes":["weapon", "hat", "clothes"]
sdk:userAppend("accountId", "distinctId", userAppendProperties)

2.5 userUniqueAppend

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

local profiles_append = {}
--执行之后用户属性append为["test_append"]
profiles_append["append"] = { "test_append" }
sdk:userAppend("accountId", "distinctId", profiles_append)

local profiles_uniq_append = {}
--执行之后用户属性append为["test_append", "test_append1"]
profiles_uniq_append["append"] = {"test_append", "test_append1"}
sdk:userUniqueAppend("accountId", "distinctId", profiles_uniq_append)

2.6 userUnset

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

local userUnsetProperties = {}
userUnsetProperties[1] = "total_revenue"
userUnsetProperties[2] = "equips"
--上传用户属性，此时将会重置"total_revenue"和"equips"两个属性
sdk:userUnset("accountId", "distinctId", userUnsetProperties)

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

2.7 userDel

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

sdk:userDel("accountId", "distinctId")

三、其他功能

3.1 TDBatchConsumer

注意

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

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

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

参数说明:

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

• SERVER_URL: 数据上传的 URL

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