自定义事件
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;
接口参数说明:
参数
参数说明
eventId
自定义事件 Id
args
⾃定义属性,key 必须为 NSString 类型,value 仅支持使⽤ NSNumber ,bool ,NSString ,NSDate 4 种类型
接口示例:
@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;
接口参数说明:
参数
参数说明
eventId
自定义事件 Id
args
自定义属性,用于扩展统计需要,开始和结束接口传入的 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采集,开发者不可以修改):
字段名称
类型
说明
$country
字符串
国家
$city
字符串
城市
$province
字符串
省份
$app_version
字符串
应用的版本
$channel
字符串
渠道
$time
数值
事件产生时间
$lib_version
字符串
SDK版本
$manufacturer
字符串
设备制造商,例如Apple
$model
字符串
设备型号,例如iphone6
$os
字符串
操作系统,例如iOS
$os_version
字符串
操作系统版本,例如8.1.1
$screen_height
数值
屏幕高度,例如1920
$screen_width
数值
屏幕宽度,例如1080
$wifi
布尔值
是否使用wifi,例如true
$carrier
字符串
运营商名称,例如ChinaNet
$network_type
字符串
网络类型,例如4G
$duration
数值
计时事件时长
6.2 用户预置属性
用户预置属性允许开发者自己上传,除 $first_visit_time 为 sdk 采集。
字段名称
类型
说明
$country
字符串
国家
$city
字符串
城市
$province
字符串
省份
$name
字符串
姓名
$sex
字符串
性别
$phone
字符串
手机号
字符串
邮箱
$birthday
日期
出生日期
$signup_time
日期
注册时间
$first_visit_time
日期
首次访问时间