---
code: corona_sdk_advanced
name: "进阶指南"
wikiToken: RVJ3wFYzKihJdTkZEwSchyxNnig
parentWikiToken: PVJhwxxtii9DDMkg45ecpCjJnge
updateTime: 1745310896000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=corona_sdk_advanced
---
# 进阶指南

### 一、设置用户ID

SDK 实例默认会使用随机数作为每个用户的默认访客 ID，该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是，访客 ID 在用户重新安装 App 以及更换设备时将会变更。

#### 1.1 设置访客 ID

::: tip 提示

 一般情况下，您不需要自定义访客 ID. 请确保已经理解用户识别规则，再进行访客 ID 的设置。

如果您需要替换访客 ID，则应当在初始化 SDK 结束之后立即进行调用，请勿多次调用，以免产生无用的账号

 :::

如果您的游戏对每个用户有自己的访客 ID 管理体系，则您可以调用 `setDistinctId` 来设置访客 ID：

```
-- 将访客ID设置为Thinker
TDAnalytics.setDistinctId("Thinker");
```

如果需要获得当前访客 ID，可以调用 `getDistinctId` 获取：

```
--返回访客ID
TDAnalytics.getDistinctId( function (ret)
    print( "distinctId = " .. ret )
end )
```

#### 1.2 设置账号 ID

在用户进行登录时，可调用 `login` 来设置用户的账号 ID， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 `logout` 之前一直保留。多次调用 `login` 将覆盖先前的账号 ID 。

```
--用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.login("TA");
```

<!-- unsupported block: 34 -->

**该方法不会上传登录事件**

#### 1.3 清除账号ID

在用户产生登出行为之后，可调用 `logout` 来清除账号 ID，在下次调用 `login` 之前，将会以访客 ID 作为身份识别 ID。

```
TDAnalytics.logout();
```

我们推荐您在显性的登出事件时调用 `logout`，比如用户产生了注销账号这一行为时才调用，而不需要在关闭 App 时调用。

<!-- unsupported block: 34 -->

**该方法不会上传登出事件**

### 二 、发送事件

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

#### 2.1 普通事件

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

```
local properties = { 
    product_name = "商品名"
}
TDAnalytics.track("product_buy", properties)
```

#### 2.2 首次事件

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

```
-- 示例：上报设备首次事件, 假设事件名为 device_activation
TDAnalytics.trackFirst("device_activation", {
    test_string="first_string"
})
```

如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件自定义first_check_id:

```
-- 将用户ID设置为首次事件的first_check_id，实现用户首次激活事件的采集
TDAnalytics.trackFirst("account_activation", {
    test_string="first_string"
} , "TA")
```

<!-- unsupported block: 34 -->

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

#### 2.3 可更新事件

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

```
-- 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
-- 上报后事件属性 status 为 3, price 为 100
TDAnalytics.trackUpdate("UPDATABLE_EVENT", {
    status = 3,
    price = 100
}, "Update_EventId")

-- 上报后事件属性 status 被更新为 5, price 不变
TDAnalytics.trackUpdate("UPDATABLE_EVENT", {
    status = 5
}, "Update_EventId")
```

#### 2.4 可重写事件

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

```
-- 示例： 上报可被重写的事件，假设事件名为 OVERWRITABLE_EVENT
TDAnalytics.trackOverwrite("OVERWRITABLE_EVENT", {
    status = 3,
    price = 100
}, "Overwrite_EventId")

-- 上报后事件属性 status 被更新为 5, price 属性被删除
TDAnalytics.trackOverwrite("OVERWRITABLE_EVENT", {
    status = 5
}, "Overwrite_EventId")
```

#### 2.5 公共事件属性

公共事件属性指的就是每个事件都会上传的属性。根据属性更新频率，公共事件属性分为`静态公共事件属性`和`动态公共事件属性`。您可以根据具体的业务场景需求，选择不同的公共事件属性设置方法；我们推荐您在发送事件前，先设置公共事件属性。针对同一事件，当公共事件属性、事件自定义属性、预置属性的Key相同时，我们会按照如下优先级进行赋值:`自定义属性>动态公共事件属性>静态公共事件属性>预置属性`。

##### 2.5.1 静态公共事件属性

静态公共事件属性是低频变化且每个事件都会带有的属性，如用户会员等级。通过`setSuperProperties`设置静态公共事件属性之后，SDK将会在事件采集时获取设置的公共事件属性作为事件的属性。

```
-- 设置公共属性
TDAnalytics.setSuperProperties({
    vip_level = 2
})
```

静态公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果该属性已存在，重新设置的属性将会覆盖原有属性值;如果之前不存在该属性，则会新建属性。除了属性设置，我们也提供其他API来操作静态公共事件属性，满足日常的业务需求。

```
-- 清除属性名为 trip 的公共属性
TDAnalytics.unsetSuperProperties("trip")
-- 清空所有公共属性
TDAnalytics.clearSuperProperties()
-- 获取所有公共属性
TDAnalytics.getSuperProperties( function (ret)
    local superProperties = ret
    print( "current superProperties = " .. superProperties )
end )
```

#### 2.6 记录事件时长

如果您需要记录某个事件的持续时长，可以调用 `timeEvent` 来开始计时。配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `#duration` 这一属性来表示记录的时长，单位为秒。需要注意的是，同一个事件名只能有一个在计时的任务。

```
--以下示例，完成用户在某个商品页面停留时长的统计
-- 用户进入商品页面，开始计时
TDAnalytics.timeEvent("stay_shop")
-- do some thing...
-- 用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性#duration
TDAnalytics.track("stay_shop")
```

### 三、用户属性

AE 平台支持的用户属性设置API有：`userSet`、`userSetOnce`、`userAdd`、`userAppend`、`userUnset`、`userDelete`。

#### 3.1 userSet

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

```
-- 此时username为TA
TDAnalytics.userSet({
    user_name = "TA"
})
-- 此时username为TE
TDAnalytics.userSet({
    user_name = "TE"
})
```

#### 3.2 userSetOnce

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

```
--first_payment_time为2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    first_payment_time = "2018-01-01 01:23:45.678"
})
-- first_payment_time仍然为2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    first_payment_time = "2018-12-31 01:23:45.678"
})
```

#### 3.3 userAdd

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

```
-- 此时total_revenue为30
TDAnalytics.userAdd({
    total_revenue = 30
})
-- 此时total_revenue为678
TDAnalytics.userAdd({
    total_revenue = 648
})
```

<!-- unsupported block: 34 -->

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

#### 3.4 userAppend

您可以调用 `userAppend` 为 `Array` 类型的用户属性追加元素:

```
-- 追加列表型用户属性
TDAnalytics.userAppend({
    weapon = {"m41", "bulldog"}
})
```

#### 3.5 userUnset

如果您需要重置用户的某个属性，可以调用 `userUnset` 将该用户指定用户属性的值清空，此接口支持传入字符串类型的参数:

```
-- 清除指定用户属性
TDAnalytics.userUnset("age")
```

<!-- unsupported block: 34 -->

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

#### 3.6 userDelete

如果您要删除某个用户，可以调用 `userDelete` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

```
-- 删除用户
TDAnalytics.userDelete()
```

### 四、其他功能

#### 4.1 获取设备ID

SDK 在初始化完成后，会自动生成设备 ID，并记录在本地缓存，对于同一应用或游戏，一台设备的设备 ID 是不变的，可以调用 `getDeviceId` 获取设备 ID：

```
-- 获取设备 ID
TDAnalytics.getDeviceId( function (ret)
    print( "deviceId = " .. ret )
end )
```
