# 行为事件上报

> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/track-events
> 说明如何使用 Gravity Engine 快游戏 SDK 上报业务事件，并管理事件公共属性。



本文档详细介绍了 SDK 提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。

通过上报应用内用户行为事件，您可以：

* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础

## 1. 自定义事件上报 [#1-自定义事件上报]

> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**

您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：

```js
ge.track(
  "$purchase", // 追踪事件的名称
  {
    Item: "商品A",
    ItemNum: 1,
    Cost: 100,
    Elements: ["apple", "ball", "cat"],
  } // 需要上传的事件属性
);
```

* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。

## 2. 公共属性 [#2-公共属性]

> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败！**

公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。

本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：

用户自定义事件属性 > 动态公共属性 > 事件公共属性

您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。

根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。

### 设置公共属性 [#设置公共属性]

```js
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });

// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
  "Purchase", // 追踪事件的名称
  {
    Item: "商品A",
    ItemNum: 1,
    Cost: 100,
  } // 需要上传的事件属性
);

/* 等价于在事件中加入这些公共属性
ge.track(
  "Purchase", // 追踪事件的名称
  {
    Item: "商品A",
    ItemNum: 1,
    Cost: 100,
    channel: "渠道" // 相当于在事件中加入这个属性
  }
);
*/
```

如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。

### 删除公共属性 [#删除公共属性]

如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性：

```js
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```

### 清空公共属性 [#清空公共属性]

如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`：

```js
// 清除公共事件属性
ge.clearSuperProperties();
```

### 获取公共属性 [#获取公共属性]

如果您想要获取所有公共事件属性，可以调用 `getSuperProperties()`：

```js
// 获取静态公共事件属性
ge.getSuperProperties();
```

## 3. 设置事件上报时间 [#3-设置事件上报时间]

事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：

> **第三个参数为事件触发时间，必须是 `Date` 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间**

```js
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());

// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```

## 4. 记录事件时长 [#4-记录事件时长]

您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。

```js
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");

// ...

// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```

## 5. 立即上报事件 [#5-立即上报事件]

如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。

```js
ge.flush()
```