# 行为事件上报

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



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

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

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

## 上报自定义事件 [#上报自定义事件]

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

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

```ts
GravityEngineSDK.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`。

## 立即上报事件 [#立即上报事件]

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

```ts
GravityEngineSDK.flush()
```

## 记录事件时长 [#记录事件时长]

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

```ts
// 调用 timeEvent 开启对 TIME_EVENT 事件的计时
GravityEngineSDK.timeEvent("TIME_EVENT");

// do some thing...

// 通过 track 上传 TIME_EVENT 事件时，会在属性中添加 $event_duration 属性
GravityEngineSDK.track("TIME_EVENT", {});
```