---
code: erlang_sdk_advanced
name: "进阶指南"
wikiToken: CfkMwrwsui8Wu7kh73Xc0mR8nuV
parentWikiToken: FT65wwPGgiXLEpkeW4IcZeEHnCd
updateTime: 1745309881000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=erlang_sdk_advanced
---
# 进阶指南

### 一、发送事件

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

#### 1.1 普通事件

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

```
%% 注意account_id 和 distinct_id 必须至少设置其中一个
%% 设置用户的ip地址，TE系统会根据IP地址解析用户的地理位置信息，如果不设置的话，则默认不上报
%% 设置事件发生的时间，如果不设置的话，则默认使用为当前时间。注意：#time的类型必须是timestamp()类型

%% 上报事件
td_analytics:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct", #{"key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),
```

#### 1.2 首次事件

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

```
FirstCheckId = "first_check_id",
%% 首次事件
td_analytics:track_first_instance(TE_SDK, "account_id_Erlang", "distinct_id", "first_login", FirstCheckId, #{"key1" => "value1", "key2" => "value2"}),
```

<!-- unsupported block: 34 -->

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

#### 1.3 可更新事件

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

```
EventName = "event_name",
EventId = "event_id",
%% 上报后，事件属性 status 为 3, price 为 100
td_analytics:track_update_instance(TE_SDK, "account_id_Erlang", "distinct_id", EventName, EventId, #{"price" => 100, "status" => 3}),

%% 上报后，事件属性 status 为 5, price 为 100 不变
td_analytics:track_update_instance(TE_SDK, "account_id_Erlang", "distinct_id", EventName, EventId, #{"status" => 5}),
```

#### 1.4 可重写事件

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

```
EventName = "overWrite_event",
EventId = "event_id",
%% 上报后，事件属性 price 为 100, status 为 5
td_analytics:track_overwrite_instance(TE_SDK, "account_id_Erlang", "distinct_id", EventName, EventId, #{"price" => 100, "status" => 5}),

%% 上报后，事件属性 price 为 20, status 属性被删除
td_analytics:track_overwrite_instance(TE_SDK, "account_id_Erlang", "distinct_id", EventName, EventId, #{"price" => 20}),
```

### 二、用户属性

AE 平台支持的用户属性设置API有: `user_set_instance`、`user_set_once_instance`、`user_add_instance`、`user_unset_instance`、`user_del_instance`、`user_append_instance`、`user_unique_append_instance`。

#### 2.1 user_set_instance

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

```
%% "name" is "A"
td_analytics:user_set_instance(TE_SDK, "account_id", "distinct_id", #{"name" => "A", "abc" => ["a", "b", "c"]}),
%% "name" is "B"
td_analytics:user_set_instance(TE_SDK, "account_id", "distinct_id", #{"name" => "B", "abc" => ["a", "b", "c"]}),
```

#### 2.2 user_set_once_instance

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

```
%% "name" is "A"
td_analytics:user_set_once_instance(TE_SDK, "account_id", "distinct_id", #{"name" => "A"}),
%% "name" is still "A"
td_analytics:user_set_once_instance(TE_SDK, "account_id", "distinct_id", #{"name" => "B"}),
```

#### 2.3 user_add_instance

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

```
%% "amount" is 30
td_analytics:user_add_instance(TE_SDK, "account_id", "distinct_id", #{"amount" => 30}),
%% "amount" is 90
td_analytics:user_add_instance(TE_SDK, "account_id", "distinct_id", #{"amount" => 60}),
```

<!-- unsupported block: 34 -->

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

#### 2.4 user_append_instance

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

```
%% "array" is ["arr1", "arr3"]
td_analytics:user_append_instance(TE_SDK, "account_id", "distinct_id", #{"array" => ["arr1", "arr3"]}),
%% "array" is ["arr1", "arr3", "arr2", "arr3"]
td_analytics:user_append_instance(TE_SDK, "account_id", "distinct_id", #{"array" => ["arr2", "arr3"]}),
```

#### 2.5 user_unique_append_instance

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

```
%% "array" is ["arr1", "arr3"]
td_analytics:user_unique_append_instance(TE_SDK, "account_id", "distinct_id", #{"array" => ["arr1", "arr3"]}),
%% "array" is ["arr1", "arr3", "arr2"]
td_analytics:user_unique_append_instance(TE_SDK, "account_id", "distinct_id", #{"array" => ["arr2", "arr3"]}),
```

#### 2.6 user_unset_instance

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

```
td_analytics:user_unset_instance(TE_SDK, "account_id", "distinct_id", ["age", "abc"]),
```

<!-- unsupported block: 34 -->

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

#### 2.7 user_del_instance

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

```
td_analytics:user_del_instance(TE_SDK, "account_id", "distinct_id"),
```
