行为事件上报

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

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

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

上报自定义事件

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

您需要先在元事件中添加自定义事件，然后在游戏中指定位置埋点调用 track 方法上报自定义事件。

JSONObject jsonObject = new JSONObject();
jsonObject.put("guild_id", "100");
jsonObject.put("guild_level", 10);
jsonObject.put("guild_name", "北方之狼");
gravityEngineSDKInstance.track("AddGuild", jsonObject);

• 事件名称是 String 类型，只能以字母开头，可包含数字，字母和下划线 “_”，长度最大为 50 个字符。
• 事件属性是 Map<String, Object> 类型，其中每个元素代表一个属性；
  • 事件属性 Key 为属性名称，为 String 类型，规定只能以字母开头，包含数字，字母和下划线 “_”，长度最大为 50 个字符；
  • 属性 Value 支持String、int、float、boolean、Date、List<String>；当事件属性为列表类型时，您需要使用 JSONArray 传入，不要使用 ArrayList，否则会校验失败！

当您调用 track 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 Date 类型的参数来设置事件触发时间。

SDK 提供了时间校准接口，允许使用服务器时间对 SDK 时间进行校准，具体请参考进阶功能中关于时间校准章节的说明。

设置公共事件属性

公共属性需要先在事件属性中添加，否则会上报失败!

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

JSONObject superProperties = new JSONObject();
superProperties.put("AGE",29);
superProperties.put("CHANNEL","xiaomi");
gravityEngineSDKInstance.setSuperProperties(superProperties);

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

删除公共事件属性

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

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

清空公共事件属性

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

// 清空所有公共属性
gravityEngineSDKInstance.clearSuperProperties();

获取公共事件属性

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

// 获取所有公共属性
gravityEngineSDKInstance.getSuperProperties();

记录事件时长

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

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

// do some thing...

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

立即上报事件

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

// 调用 flush() 上报缓存事件
gravityEngineSDKInstance.flush();