1. 自定义事件

1.1. 功能介绍

自定义事件功能，是MTA为开发者提供的自助分析工具。通过代码埋点，对用户行为进行追踪，完成对用户行为细节的记录。我们提供了两种形式的自定义事件：普通事件、计算事件。

普通事件与计算事件的区别是什么？

普通事件可满足定性事件的统计需求，如登陆、注册、进入首页等行为。

计算事件可满足变量事件的统计需求，如充值金额、购买数量等。详情>>

1.1.1. 普通事件

在普通事件下，通过代码埋点，用户行为得到了量化：

• 统计次数：统计指定行为被触发的次数 如，点击“开始注册”等按钮的次数和点击“广告页”等页面的次数

• 统计时长：统计两个指定行为之间的消耗时间，单位为秒 如，用户从开始注册到注册成功的消耗时间

下面以音乐播放应用的播放事件为例说明普通事件如何完成统计。

事件ID及其参数形如：onPlay(Name=‘那些年’, singer=‘胡夏’)

1.统计每天的播放情况：

播放事件统计结果

2.统计每天“那些年”“老男孩”的播放量和播放时长：

播放事件 — Name参数统计结果

1.1.2. 计算事件

考虑以下情景：

一款手游，想统计游戏道具购买情况，包括：

1）每个道具的平均购买数量

2）不同等级下，不同角色的花费分布情况

来看看如何通过计算事件完成游戏道具购买情况统计。

在用户购买道具完成后，上报计算事件数据：

【例】onShop(playerId=98754515, playerLevel=3, playerRole=‘法师’, itemId=1027, itemNum=5, payment=175)

1）统计每个道具的平均购买数量

① 选择itemId参数作为统计维度

② 选择itemNum作为计算参数

③ 对itemNum选择求平均值计算方式

2）统计不同等级下，不同角色的花费分布情况

① 选择playerLevel、playerRole参数作为统计维度

② 选择payment作为计算参数

③ 对payment 选择累加计算方式

计算事件除了支持对事件参数做SUM（累加）、AVG（求平均值）计算外，还支持COUNT(DISTINCT)（去重）、MAX（求最大值）、MIN（求最小值），并且可以同时选择多个维度进行分析，满足深层次的分析需求。

1.1.3. 操作指南

通过MTA自定义事件功能获取业务特性统计结果只需要：

• 在MTA管理台新增自定义事件，填写事件id、事件名称，并按需选择事件类型；

• 在事件的参数配置页面新增参数，填写参数id，参数名称；

• 嵌入MTA SDK，把数据上报到MTA服务器；

• 普通事件可在管理台直接查看事件及参数统计数据；计算事件需在参数配置页面下设置参数组合，设置完成后，即可查看参数组合数据报表。

其中每类事件都有Key-Value参数类型和不定长字符串参数类型，由于Key-Value参数类型的接口能表达更丰富的内容，我们推荐优先使用Key-Value类参数接口。另外，如果代码同时使用了这2种参数类型，event_id最好不一样。

注意：event_id需要先在腾讯移动分析网站上面配置，才能参与正常的数据统计。event_id不能包含空格或转义字符。

新增事件的方法如图：

新增事件参数的方法如图：

1.2. Android自定义事件使用指南

1.2.1. 注册自定义事件

自定义事件的注册（配置）包括事件id的注册和事件id下参数信息的注册。

（1）登陆mta前台，选择左边选择“自定义事件”。

（2）选择“新增事件”，按照需求填写事件id、key、value等信息。

（3）可以在查看详情下的“参数”查看事件id下所有参数上报的明细。

1.2.2. 【次数统计】Key-Value参数的事件

void StatService.trackCustomKVEvent(Context ctx, String event_id, 
Properties properties)

（1）参数：

Ctx 页面的设备上下文

event_id 事件标识

properties Key-Value参数对，key和value都是String类型

（2）调用位置： 代码任意处

public void onOKBtnClick(View v) {
// 统计按钮被点击次数，统计对象：OK按钮
Properties prop = new Properties();
    prop.setProperty("name", " OK ");
    StatService.trackCustomKVEvent(this, " button_click", prop);
}
public void onBackBtnClick(View v) {
// 统计按钮被点击次数，统计对象：back按钮
Properties prop = new Properties();
    prop.setProperty("name", " back ");
    StatService.trackCustomKVEvent(this, " button_click", prop);
}

1.2.3. 【时长统计】Key-Value参数事件

可以指定事件的开始和结束时间，来上报一个带有统计时长的事件。

void StatService.trackCustomBeginKVEvent(
Context ctx, String event_id, Properties properties)
void StatService.trackCustomEndKVEvent(
Context ctx, String event_id, Properties properties)

（1）参数：

Ctx 页面的设备上下文

event_id 事件标识

properties Key-Value参数对，key和value都是String类型

（2）调用位置：

代码任意处

public void onClick(View v) {
Properties prop = new Properties();
    prop.setProperty("level", "5");
// 统计用户通关所花时长，关卡等级： 5
// 用户通关前
StatService.trackCustomBeginKVEvent(this, " playTime", prop);
    // 用户正在游戏中….
    // …….
    // 用户通关完成时
StatService.trackCustomEndKVEvent(this, " playTime", prop);
}

1.2.4. 【时长统计】带有统计时长的自定义参数事件

可以指定事件的开始和结束时间，来上报一个带有统计时长的事件。

void StatService.trackCustomBeginEvent(
Context ctx, String event_id, String... args)
void StatService.trackCustomEndEvent(
Context ctx, String event_id, String... args)

（1）参数：

Ctx 页面的设备上下文

event_id 事件标识

args 事件参数

（2）调用位置：

代码任意处

public void onClick(View v) {
    // 统计用户通关所花时长
// 用户通关前
StatService.trackCustomBeginEvent(this, " playTime", "level5");
    // 用户正在游戏中….
    // …….
    // 用户通关完成时
StatService.trackCustomEndEvent(this, " playTime", " level5");

注意：trackCustomBeginEvent和trackCustomEndKvent必须成对出现，且参数列表完全相同，才能正常上报事件。

1.3. iOS自定义事件使用指南

1.3.1. NSDictionary为参数的自定义事件

/**
 上报自定义事件

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param kvs 事件的参数，参数需要先在MTA前台配置好才能生效
 */
+ (void)trackCustomKeyValueEvent:(NSString *)event_id props:(NSDictionary *)kvs;

/**
 上报自定义事件
 并且指定上报方式

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param kvs 事件的参数，参数需要先在MTA前台配置好才能生效
 @param appkey 需要上报的appKey，若传入nil，则上报到启动函数中的appkey
 @param isRealTime 是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。
 */
+ (void)trackCustomKeyValueEvent:(NSString *)event_id
    props:(NSDictionary *)kvs
    appkey:(NSString *)appkey
    isRealTime:(BOOL)isRealTime;

/**
 开始统计自定义时长事件
 此接口需要跟trackCustomKeyValueEventEnd配对使用
 多次调用以第一次开始时间为准

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param kvs 事件的参数，参数需要先在MTA前台配置好才能生效
 */
+ (void)trackCustomKeyValueEventBegin:(NSString *)event_id props:(NSDictionary *)kvs;

/**
 开始统计自定义时长事件
 并指定上报方式
 此接口需要跟trackCustomKeyValueEventEnd配对使用
 多次调用以第一次开始时间为准

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param kvs 事件的参数，参数需要先在MTA前台配置好才能生效
 @param appkey 需要上报的appKey，若传入nil，则上报到启动函数中的appkey
 */
+ (void)trackCustomKeyValueEventBegin:(NSString *)event_id
    props:(NSDictionary *)kvs
    appkey:(NSString *)appkey;

/**
 结束统计自定义时长事件
 此接口需要跟trackCustomKeyValueEventBegin配对使用
 多次调用以第一次结束时间为准

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param kvs 事件的参数，参数需要先在MTA前台配置好才能生效
             参数中的key和value必须跟开始统计时传入的参数一样才能正常配对
 */
+ (void)trackCustomKeyValueEventEnd:(NSString *)event_id props:(NSDictionary *)kvs;

/**
 结束上报自定义时长事件
 并指定上报方式
 此接口需要跟trackCustomKeyValueEventBegin配对使用
 多次调用以第一次结束时间为准

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param kvs 事件的参数，参数需要先在MTA前台配置好才能生效
             参数中的key和value必须跟开始统计时传入的参数一样才能正常配对
 @param appkey 需要上报的appKey，若传入nil，则上报到启动函数中的appkey
 @param isRealTime 是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。
 */
+ (void)trackCustomKeyValueEventEnd:(NSString *)event_id
    props:(NSDictionary *)kvs
    appkey:(NSString *)appkey
    isRealTime:(BOOL)isRealTime;


/**
 直接统计自定义时长事件
 这个方法用于上报统计好的时长事件

 @param seconds 自定义事件的时长，单位秒
 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param kvs 事件的参数，参数需要先在MTA前台配置好才能生效
 */
+ (void)trackCustomKeyValueEventDuration:(uint32_t)seconds
    withEventid:(NSString *)event_id
    props:(NSDictionary *)kvs;

/**
 直接上报自定义时长事件
 并指定上报方式
 这个方法用于上报统计好的时长事件

 @param seconds 自定义事件的时长，单位秒
 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param kvs 事件的参数，参数需要先在MTA前台配置好才能生效
 @param appkey 需要上报的appKey，若传入nil，则上报到启动函数中的appkey
 @param isRealTime 是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。
 */
+ (void)trackCustomKeyValueEventDuration:(uint32_t)seconds
    withEventid:(NSString *)event_id
    props:(NSDictionary *)kvs
    appKey:(NSString *)appkey
    isRealTime:(BOOL)isRealTime;

示例

// 次数统计
- (IBAction)clickKVButton:(id)sender {
    [MTA trackCustomKeyValueEvent:@"KVEvent"
        props:[NSDictionary dictionaryWithObject:@"Value" forKey:@"Key"]];
}

// 时长统计
- (IBAction)clickStartKvButton:(id)sender {
    [MTA trackCustomKeyValueEventBegin:@"KVEvent"
        props:[NSDictionary dictionaryWithObject:@"Value" forKey:@"TimeKey"]];
}

- (IBAction)clickEndKvButton:(id)sender {
    [MTA trackCustomKeyValueEventEnd:@"KVEvent"
        props:[NSDictionary dictionaryWithObject:@"Value" forKey:@"TimeKey"]];
}

1.3.2. NSArray为参数的自定义事件

接口

/**
 上报自定义事件

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param array 事件的参数，参数需要先在MTA前台配置好才能生效
 */
+ (void)trackCustomEvent:(NSString *)event_id args:(NSArray *)array;


/**
 上报自定义事件
 并指定上报方式

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param array 事件的参数，参数需要先在MTA前台配置好才能生效
 @param appkey 需要上报的appKey，若传入nil，则上报到启动函数中的appkey
 @param isRealTime 是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。
 */
+ (void)trackCustomEvent:(NSString *)event_id
    args:(NSArray *)array
    appkey:(NSString *)appkey
    isRealTime:(BOOL)isRealTime;

/**
 开始统计自定义时长事件
 此接口需要跟trackCustomEventEnd配对使用
 多次调用以第一次开始时间为准

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param array 事件的参数，参数需要先在MTA前台配置好才能生效
 */
+ (void)trackCustomEventBegin:(NSString *)event_id args:(NSArray *)array;

/**
 开始统计自定义时长事件
 并指定上报方式
 此接口需要跟trackCustomEventEnd配对使用
 多次调用以第一次开始时间为准

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param array 事件的参数，参数需要先在MTA前台配置好才能生效
 @param appkey 需要上报的appKey，若传入nil，则上报到启动函数中的appkey
 */
+ (void)trackCustomEventBegin:(NSString *)event_id
    args:(NSArray *)array
    appkey:(NSString *)appkey;

/**
 结束统计自定义时长事件
 此接口需要跟trackCustomKeyValueEventBegin配对使用
 多次调用以第一次结束时间为准

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param array 事件的参数，参数需要先在MTA前台配置好才能生效
                 参数中的各项必须跟开始统计时传入的参数一样才能正常配对
 */
+ (void)trackCustomEventEnd:(NSString *)event_id args:(NSArray *)array;

/**
 结束统计自定义时长事件
 并指定上报方式
 此接口需要跟trackCustomKeyValueEventBegin配对使用
 多次调用以第一次结束时间为准

 @param event_id 事件的ID，ID需要先在MTA前台配置好才能生效
 @param array 事件的参数，参数需要先在MTA前台配置好才能生效
                 参数中的各项必须跟开始统计时传入的参数一样才能正常配对
 @param appkey 需要上报的appKey，若传入nil，则上报到启动函数中的appkey
 @param isRealTime 是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。
 */
+ (void)trackCustomEventEnd:(NSString *)event_id
    args:(NSArray *)array
    appkey:(NSString *)appkey
    isRealTime:(BOOL)isRealTime;

示例

// 次数统计
- (IBAction)clickNormaltButton:(id)sender {
    [MTA trackCustomEvent:@"NormalEvent" args:[NSArray arrayWithObject:@"arg0"]];
}

// 时长统计
- (IBAction)clickStartButton:(id)sender {
    [MTA trackCustomEventBegin:@"TimeEvent" args:[NSArray arrayWithObject:@"arg0"]];
}

- (IBAction)clickEndButton:(id)sender {
    [MTA trackCustomEventEnd:@"TimeEvent" args:[NSArray arrayWithObject:@"arg0"]];
}

1.3.3. 上报当前缓存的事件

接口

/**
 上报当前缓存的数据
 若当前有缓存的事件（比如上报策略不为实时上报，或者有事件上报失败）时
 调用此方法可以上报缓存的事件

 @param maxStatCount 最大上报事件的条数
 */
+ (void)commitCachedStats:(int32_t)maxStatCount;