# 行为事件上报

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





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

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

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

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

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

> **事件名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 “\_”，长度最大为 50 个字符**

您可以调用 `track` 方法，记录用户自定义事件。

您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加自定义事件，然后在游戏中指定位置埋点调用 `track` 方法上报自定义事件，此处以用户购买某商品作为范例。

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    NSDictionary *eventProperties = @{ @"product_name": @"商品名"};
    [instance track:@"product_buy" properties:eventProperties];
    ```
  </Tab>

  <Tab value="Swift">
    ```swift
    let properties = ["product_name": "商品名"] as [String: Any]
    instance?.track("product_buy", properties: properties)
    ```
  </Tab>
</Tabs>

## 2. 设置公共事件属性 [#2-设置公共事件属性]

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

对于一些重要的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用 `setSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    NSMutableDictionary *superProperties = [NSMutableDictionary new];
    [superProperties setValue:@"ta" forKey:@"channel"];//字符串
    [superProperties setValue:@1 forKey:@"age"];//数字
    [superProperties setValue:@YES forKey:@"isSuccess"];//布尔
    [superProperties setValue:[NSDate now] forKey:@"birthday"];//时间
    [superProperties setValue:@[@{@"key":@"value"}] forKey:@"object_arr"];//对象组
    [superProperties setValue:@[@"value"] forKey:@"arr"];//数组

    [instance setSuperProperties:superProperties];//设置公共事件属性
    ```
  </Tab>

  <Tab value="Swift">
    ```swift
    var superProperties: [AnyHashable : Any] = [:]
    superProperties["channel"] = "ta" //字符串
    superProperties["age"] = 1 //数字
    superProperties["isSuccess"] = true //布尔
    superProperties["birthday"] = Date() //时间
    superProperties["object_arr"] = [["key": "value"]] // 对象组
    superProperties["arr"] = ["value"] // 数组

    //设置公共事件属性
    instance.setSuperProperties(superProperties)
    ```
  </Tab>
</Tabs>

公共事件属性将会被保存到缓存中，无需每次启动 APP 时调用。如果调用 `setSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 `track()` 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。

* 事件的属性是一个 `NSDictionary` 对象，其中每个元素代表一个属性。
* `Key` 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "\_"，长度最大为 50 个字符。
* `Value` 为该属性的值，支持字符串、数字、布尔、时间、对象组、数组。
* 如果您需要上传布尔型的属性，则请以 `@YES` 与 `@NO` 或 `[NSNumber numberWithBool:YES]` 与 `[NSNumber numberWithBool:NO]` 来赋值。不可以使用 `@true`、 `@false`、 `@TRUE` 和 `@FALSE` 赋值布尔型数据。
* 如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty` 清除其中一个公共事件属性；
* 如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties`;

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    //以下示例，完成用户在某个商品页面停留时长的统计
    [instance timeEvent:@"stay_shop"];
     /**do someting
        .......
     **/
    //用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性$event_duration
    [instance track:@"stay_shop"];
    ```
  </Tab>

  <Tab value="Swift">
    ```swift
    //以下示例，完成用户在某个商品页面停留时长的统计
    instance.timeEvent("stay_shop")
     /**do someting
        .......
     **/
    //用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性$event_duration
    instance.track("stay_shop")
    ```
  </Tab>
</Tabs>

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    [instance flush];
    ```
  </Tab>

  <Tab value="Swift">
    ```swift
    instance?.flush()
    ```
  </Tab>
</Tabs>