跳到主要内容

进阶指南

最近更新 2026/08/27

一、发送事件​

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

1.1 普通事件​

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

let trackEvent = {
    accountId: '2222',
    distinctId: '1111',
    event: 'test_event',
    time: new Date(),
    ip: '202.38.64.1',
    properties: {
        prop_double: 134.1,
    },
    callback(e) {
        if (e) {
            console.log(e);
        }
    }
};

teSDK.track(trackEvent)

1.2 首次事件​

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

let trackFirstEvent = {
    accountId: '2222',
    distinctId: '1111',
    event: 'test_event',
    firstCheckId: 'first_check_id',
    time: new Date(),
    properties: {
        prop_date: new Date(),
        prop_double: 134.1,
        prop_string: 'hello world',
        prop_int: 67,
    },
    callback(e) {
        if (e) {
            console.log(e);
        }
    }
};

teSDK.trackFirst(trackFirstEvent);

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

1.3 可更新事件​

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

let trackUpdateEvent = {
    accountId: '2222',
    distinctId: '1111',
    event: 'test_event',
    eventId: 'event_id',
    time: new Date(),
    properties: {
        prop_date: new Date(),
        prop_double: 134.1,
        prop_string: 'hello world',
        prop_int: 67,
    },
    callback(e) {
        if (e) {
            console.log(e);
        }
    }
};

teSDK.trackUpdate(trackUpdateEvent);

1.4 可重写事件​

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

let trackOverwriteEvent = {
    accountId: '2222',
    distinctId: '1111',
    event: 'test_event',
    eventId: 'event_id',
    time: new Date(),
    properties: {
        prop_date: new Date(),
        prop_double: 134.1,
        prop_string: 'hello world',
        prop_int: 67,
    },
    callback(e) {
        if (e) {
            console.log(e);
        }
    }
};

teSDK.trackOverWrite(trackOverwriteEvent);

二、用户属性​

AE 平台支持的用户属性设置API有: userSet、userSetOnce、userAdd、

userUnset、userDel、userAppend、userUniqAppend。

2.1 userSet​

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

let userSetData = {
    accountId: 'node_test',
    properties: {
        prop_date: new Date(),
        prop_double: 134.12,
        prop_string: 'hello',
        prop_int: 666,
        prop_array: ['str1', 'str2'],
    },
    callback(e) {
        if (e) {
            console.log(e);
        }
    }
};

teSDK.userSet(userSetData);

2.2 userSetOnce​

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

teSDK.userSetOnce({
    accountId: 'node_test',
    properties: {
        setOnceProperty: "set_once",
    }
});

2.3 userAdd​

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

teSDK.userAdd({
    accountId: 'node_test',
    properties: {
        prop_double: 0.6,
        prop_int: 222,
    }
});

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

2.4 userAppend​

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

teSDK.userAppend({
    accountId: 'node_test',
    properties: {
        prop_array: ['str3', 'str4']
    }
});

2.5 userUniqAppend​

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

teSDK.userUniqAppend({
    accountId: 'node_test',
    properties: {
        prop_array: ['str3', 'str4']
    }
});

2.6 userUnset​

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

teSDK.userUnset({
    accountId: 'node_test',
    property: 'set_once_property'
});

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

2.7 userDel​

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

teSDK.userDel({
  // 账号 ID （可选)
  accountId: "node_test",
  // 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
  distinctId: "node_distinct_id"
});

三、其他功能​

3.1 BatchMode​

注意

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

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

let teSDK = ThinkingData.initWithBatchMode('APP_ID', 'SERVER_URL', {
    batchSize: 2,
    compress: false // enable compress or not, default true
});

参数说明:

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

  • SERVER_URL: 数据上传的 URL

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