---
code: php_sdk_advanced
name: "进阶指南"
wikiToken: XK7Fw4spoiDXdokeievcRH5FnTd
parentWikiToken: XjWfwdvmliurf5k9Tr7cevp3nhc
updateTime: 1745309910000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=php_sdk_advanced
---
# 进阶指南

### 一、发送事件

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

#### 1.1 普通事件

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

```
//设置事件属性
$properties = array();
$properties["product_name"] = "book";
try {
    $te->track("distinctId", "accountId", "productBuy", $properties);
} catch (Exception $e) {
    echo $e;
}
```

#### 1.2 首次事件

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

```
// 示例： 上报首次事件，假设事件名为 device_activation
$properties = array();
$properties["price"] = 100;
$properties["status"] = 3;
$firstCheckId = "first_flag_id";
try {
    $te->track_first("distinctId", "accountId", "device_activation", $firstCheckId, $properties);
} catch (Exception $e) {
    echo $e;
}
```

<!-- unsupported block: 34 -->

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

#### 1.3 可更新事件

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

```
// 示例： 上报可被更新的事件，假设事件名为 eventName
// 上报后事件属性 status 为 3, price 为 100
$properties = array();
$properties["price"] = 100;
$properties["status"] = 3;
$eventId = "eventId";
try {
    $te->track_update("distinctId", "accountId", "eventName", $eventId, $properties);
} catch (Exception $e) {
    echo $e;
}

// 上报后，事件id为：eventId 且事件名为：eventName 的事件属性 status 被更新为 5, price 不变
$properties1 = array();
$properties1["status"] = 5;
try {
    $te->track_update("distinctId", "accountId", "eventName", $eventId, $properties1);
} catch (Exception $e) {
    echo $e;
}
```

#### 1.4 可重写事件

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

```
// 示例： 上报可被更新的事件，假设事件名为 eventName
// 上报后事件属性 status 为 3, price 为 100
$properties = array();
$properties["price"] = 100;
$properties["status"] = 3;
$eventId = "eventId";
try {
    $te->track_overwrite("distinctId", "accountId", "eventName", $eventId, $properties);
} catch (Exception $e) {
    echo $e;
}

// 上报后，事件id为：eventId 且事件名为：eventName 的事件属性 status 被更新为 5, price 属性被删除
$properties1 = array();
$properties1["status"] = 5;
try {
    $te->track_overwrite("distinctId", "accountId", "eventName", $eventId, $properties1);
} catch (Exception $e) {
    echo $e;
}
```

### 二、用户属性

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

`user_unset`、`user_del`、`user_append`、`user_uniqAppend`。

#### 2.1 user_set

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

```
$properties = array();

//上传用户属性，新建属性"user_name"，值为"ABC"
$properties["user_name"] = "ABC";
try{
    $te->user_set('distinct_id', 'account_id', $properties);
}catch (Exception $e){
    //异常处理
    echo $e;
}
//再次上传用户属性，此时"user_name"的值会被覆盖为"XYZ"
$properties["user_name"] = "XYZ";
try{
    $te->user_set('distinct_id', 'account_id', $properties);
}catch (Exception $e){
    //异常处理
    echo $e;
}
```

#### 2.2 user_setOnce

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

```
$properties = array();

//同样的，上传用户属性，新建属性"user_name"，值为"ABC"
$properties["user_name"] = "ABC";
try{
    $te->user_setOnce('distinct_id', 'account_id', $properties);
} catch (Exception $e){
    //异常处理
    echo $e;
}

//再次上传用户属性，此时"user_name"已存在值，因此不进行修改，仍为"ABC"；"user_age"的值为18
$properties["user_name"] = "XYZ";
$properties["user_age"] = 18;
try{
    $te->user_setOnce('distinct_id', 'account_id', $properties);
} catch (Exception $e){
    //异常处理
    echo $e;
}
```

#### 2.3 user_add

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

```
try{
    $properties = array();
    $properties['level'] = 2;
    $te->user_add($distinct_id, $account_id, $properties);
}catch (Exception $e){
    //handle except
    echo $e;
}
```

<!-- unsupported block: 34 -->

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

#### 2.4 user_append

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

```
//user_append 追加一个用户的某一个或者多个集合
try{
    $properties = array();
    $properties['arr'] = ['str3','str4'];//为集合类型追加多个值，key-array形式，array里面都是字符串类型
    $te->user_append('distinct_id', 'account_id', $properties);
}catch (Exception $e){
    //handle except
    echo $e;
}
```

#### 2.5 user_uniq_append

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

```
//user_uniq_append 追加一个用户的某一个或者多个集合(对于重复元素进行去重处理)
try{
    $properties = array();
    $properties['arr'] = ['str3','str4'];//为集合类型追加多个值，key-array形式，array里面都是字符串类型
    $te->user_uniq_append('distinct_id', 'account_id', $properties);
}catch (Exception $e){
    //handle except
    echo $e;
}
```

#### 2.6 user_unset

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

```
$properties1 = array(
    'age', "update_time"
);
try {
    $te->user_unset(null, 'account_id', $properties1);
} catch (Exception $e) {
    //handle except
    echo $e;
}
```

<!-- unsupported block: 34 -->

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

#### 2.7 user_del

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

```
try{
    $te->user_del('distinct_id', 'account_id');
} catch (Exception $e){
    //异常处理
    echo $e;
}
```

### 三、其他功能

#### 3.1 TDBatchConsumer

::: warning 注意

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

:::

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

```
require "TaPhpSdk.php";
$te = new TDAnalytics(new TDBatchConsumer("SERVER_URL","APP_ID"));
```

参数说明:

- `APP_ID`: 您的项目的 APP ID，可通过在 AE 后台项目管理页面获取
- `SERVER_URL`: 数据上传的 URL
- 如果您对接的是云服务，填入: https://global-receiver-ta.thinkingdata.cn 
- 如果您使用私有化部署版本，请为数据采集地址绑定域名，并配置 HTTPS 证书：https://数据采集地址绑定域名
