自定义事件

1. 功能介绍

自定义事件可以统计某些用户自定义埋点的发生时间以及次数，例如广告点击、短信数量等。通常 event_id 用于表示某种行为或功能的统计（如统计“发送”按钮被触发多少次），而参数则用于标识统计的具体对象（如功能为“下载”的按钮），由 event_id 唯一标识一个事件。

自定义事件主要分为三种：

（1）次数统计：统计指定行为被触发的次数。

（2）时长统计：统计指定行为消耗的时间，单位为秒。需要 eventBegin 和 eventEnd 接口成对使用才可生效。

（3）用户属性统计：统计对应用户的相关信息。

每类事件都支持使用 jsonObject 参数类型。其中 key 为字符串类型，且不能与 SDK 预置属性重复(具体预置属性见文末)，value 目前支持类型有 String、 Number 、 Boolean 、 Date 。

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

2.1 次数统计事件

在事件执行开始时调用次数统计方法，SDK 会根据事件 ID ，统计该事件被点击的次数。

void GsManager.getInstance().onEvent(String eventId, JSONObject jsonObject)

参数：

• eventId :自定义事件 Id ，用于标识事件的唯一
• jsonObject : key-value ，自定义属性，用于扩展统计需求

使用代码：

public void onClick(View v) {
    // jsonObject 可不传
        try {
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("buttonId", "onclick");
            GsManager.getInstance().onEvent("eventId", jsonObject);
        } catch (JSONException e) {
            e.printStackTrace();
        }
}

2.2 时长统计事件

在事件开始和结束时调用对应方法，可以获取并上传事件的时间。

void GsManager.getInstance().onBeginEvent(String eventId, JSONObject jsonObject)

void GsManager.getInstance().onEndEvent(String eventId, JSONObject jsonObject)

参数：

• eventId :自定义事件 Id ，用于标识事件的唯一
• jsonObject : key-value ，自定义属性，用于扩展统计需求，开始和结束点的 jsonObject 必须一致计时事件才会生效

使用代码：

public void onClick(View v) {
    // jsonObject 可不传
        try {
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("type", "download");
            GsManager.getInstance().onBeginEvent("eventId", jsonObject);
            GsManager.getInstance().onEndEvent("eventId", jsonObject);
        } catch (JSONException e) {
            e.printStackTrace();
        }
}

2.3 用户属性设置

设置⽤户属性，记录的是用户的基本固定不变的属性，例如性别、年龄、注册时间、注册地域、注册渠道等。

void GsManager.getInstance().setProfile(JSONObject jsonObject)

参数：

• jsonObject : key-value ，自定义用户属性，用于扩展统计需求

使用代码

public void onClick(View v) {
        try {
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("sex","男");
            jsonObject.put("age", 22);
            GsManager.getInstance().setProfile(jsonObject);
        } catch (JSONException e) {
            e.printStackTrace();
        }
}

2.4 Hybrid 埋点

需要在 WebViewClient 的 shouldOverrideUrlLoading 方法中调用 SDK 方法：

/**
* 拦截个数专用url跳转
* @param webView 当前WebView
* @param url 当前url
* 返回值 true：该url为个数特有url并处理；false：其它url，需要继续处理
*/
boolean GsManager handleWebViewUrl(WebView webView, String url);

使用代码：

public class MyWebViewClient extends WebViewClient {
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, String url) {
        if(GsManager.handleWebViewUrl(view, url)){
            return true;
        }       
        super.shouldOverrideUrlLoading(view, url);
        return true;
    }
}

2.4.1 次数统计事件

GsManager.onEventWithProperties(event_id, param_json);

2.4.2 时长统计事件

GsManager.onEventWithPropertiesBegin(event_id, param_json);
GsManager.onEventWithPropertiesEnd(event_id, param_json);

2.4.3 用户属性设置

GsManager.setProfile(param_json);

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

3.1. 次数统计事件

接口描述:

在事件执行开始时调用次数统计方法，SDK 会根据事件 Id ，统计该事件被点击的次数。

接口定义:

/**
 计数事件统计

 @param eventId 事件 Id
 @param args ⾃定义属性，key 必须为 NSString 类型，value 仅⽀持使用 NSNumber ，bool ， NS String ，NSDate 4 种类型。
 */
+ (void)trackCountEvent:(NSString *)eventId withArgs:(NSDictionary *)args;

接口参数说明:

接口示例:

@implementation TrackCountEventController
 - (IBAction)clickCount:(id)sender {
 [GTCountSDK trackCountEvent:@"test" withArgs:@{@"time":[NSDate date],@"number":@(34.0),@"string":@"str",@"BOOL":@YES}];}
 @end

3.2. 时长统计事件

接口描述:

在事件开始和结束时调用对应方法，可以获取并上传事件的时长。

接口定义:

/**
 记录⾃定义事件的开始
注意:需要跟 trackCustomKeyValueEventEnd:withArgs: 配对使⽤ 若多次调用则以最后一次开始的时间为准
@param eventId 自定义事件 Id
@param args ⾃定义属性，key 必须为 NSString 类型，value 仅⽀持使用 NSNumber ，bool ， NS String ，NSDate 4 种类型。需与接口 trackCustomKeyValueEventEnd:withArgs: 传入的参数一致 。
  */
 + (void)trackCustomKeyValueEventBegin:(NSString *)eventId withArgs:(NSDictionary *
 )args;
/**

记录⾃定义事件的结束
注意:需要跟 trackCustomKeyValueEventBegin:withArgs: 配对使用 若多次调用则以第一次结束的时间为准
@param eventId 自定义事件 Id
@param args ⾃定义属性，key 必须为 NSString 类型，value 仅支持使用 NSNumber ，bool ， NS String ，NSDate 4 种类型。需与接口 trackCustomKeyValueEventBegin:withArgs: 传⼊的参数一致。
  */
 + (void)trackCustomKeyValueEventEnd:(NSString *)eventId withArgs:(NSDictionary *)args;

接口参数说明:

接口示例:

 @interface TrackCustomKeyValueEventController ()
 @end

 @implementation TrackCustomKeyValueEventController
 -(void) viewDidAppear:(BOOL)animated {
     self.eventProperty = @{@"key":@"value1"};
     [GTCountSDK trackCustomKeyValueEventBegin:@"eid1" withArgs:@{@"time":[NSDate date],@"number":@(34.0),@"string":@"str",@"BOOL":@YES}];
         [super viewDidAppear:animated];
 }
 - (void)viewWillDisappear:(BOOL)animated {
     [GTCountSDK trackCustomKeyValueEventEnd:@"eid1" withArgs:@{@"time":[NSDate date],@"number":@(34.0),@"string":@"str",@"BOOL":@YES}];
     [super viewWillDisappear:animated];
 }
@end

3.3. 用户属性设置

接⼝描述:

设置用户属性，记录的是用户的基本固定不变的属性，例如性别、出生年份、注册时间、注册地域、注册渠道等。

接⼝定义:

/**
用户属性设置
@param profiles ⽤户属性参数，key 必须为 NSString 类型，value 仅⽀持使⽤ NSNumber ，bool ，NSString ，NSDate 4 种类型。
*/
 + (void)setProfile:(NSDictionary *)profiles;

接⼝示例:

NSMutableDictionary *profiles = [NSMutableDictionary new]; 
[profiles setObject:@"username001" forKey:@"$name"]; 
[profiles setObject:@"男" forKey:@"$sex"];
[GTCountSDK setProfile:profiles.copy];
return YES;

3.4 Hybrid 埋点

在 UIWebView 的 delegate 中添加以下代码

- (BOOL)webView:(UIWebView *)webView
    shouldStartLoadWithRequest:(NSURLRequest *)request
    navigationType:(UIWebViewNavigationType)navigationType {
    // 处理混合统计请求的代码
    if ([GeShuHybird handleRequest:request
        webView:webView]) {
        return NO;
    }

    // 原有的代码
    return YES;
}

在 WKWebView 的 navigationDelegate 中添加以下代码

- (void)webView:(WKWebView *)webView
    decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
    decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
    // 处理混合统计请求的代码
    if ([GeShuHybird handleAction:navigationAction
        fromWKWebView:webView]) {
        decisionHandler(WKNavigationActionPolicyCancel);
        return;
    }

    // 原有的代码
    decisionHandler(WKNavigationActionPolicyAllow);
}

3.4.1 次数统计事件

GsManager.onEventWithProperties(event_id, param_json);

3.4.2 时长统计事件

GsManager.onEventWithPropertiesBegin(event_id, param_json);
GsManager.onEventWithPropertiesEnd(event_id, param_json);

3.4.3 用户属性设置

GsManager.setProfile(param_json);

4. 快应用自定义事件使用指南

4.1 次数统计事件

在事件执行开始时调用次数统计方法，SDK 会根据事件 ID ，统计该事件被点击的次数。

trackCountEvent (eventId, args) 

参数：

• eventId :自定义事件 Id ，用于标识事件的唯一
• args : key-value ，自定义属性，用于扩展统计需求
• key 和 value 都是 String 类型

使用代码：

this.$app.GsManager().trackCountEvent('eventid',{'key':'value'})

4.2 时长统计事件

在事件开始和结束时调用对应方法，可以获取并上传事件的时间。

trackEventBegin (eventId, args) 

trackEventEnd (eventId, args) 

参数：

• eventId :自定义事件 Id ，用于标识事件的唯一
• args : key-value ，自定义属性，用于扩展统计需求，key 和 value 都是 String 类型

使用代码：

this.$app.GsManager().trackEventBegin('eventid',{'key':'value'})

this.$app.GsManager().trackEventEnd('eventid',{'key':'value'})

5. 小程序自定义事件使用指南

5.1 次数统计事件

在事件执行开始时调用次数统计方法，SDK 会根据事件 ID ，统计该事件被点击的次数。

trackCountEvent (eventId, args) 

参数：

• eventId :自定义事件 Id ，用于标识事件的唯一
• args : key-value ，自定义属性，用于扩展统计需求
• key 和 value 都是 String 类型

使用代码：

GsManager().trackCountEvent('eventid',{'key':'value'})

5.2 时长统计事件

在事件开始和结束时调用对应方法，可以获取并上传事件的时间。

trackEventBegin (eventId, args) 
trackEventEnd (eventId, args) 

参数：

• eventId :自定义事件 Id ，用于标识事件的唯一
• args : key-value ，自定义属性，用于扩展统计需求，key 和 value 都是 String 类型

使用代码：

GsManager().trackEventBegin('eventid',{'key':'value'})
GsManager().trackEventEnd('eventid',{'key':'value'})

6. 预置属性说明

6.1 事件预置属性

事件预置属性用 $ 标记（预置属性由sdk采集，开发者不可以修改）:

6.2 用户预置属性

用户预置属性允许开发者自己上传，除 $first_visit_time 为 sdk 采集。