埋点API
1 如何查看埋点方案
在进行埋点前,需要确定在哪里埋点、埋哪些点等,即需要梳理清楚明确的埋点需求。在QuickTracking平台中将明确的埋点需求称为埋点方案,并为埋点方案设计了规范模板。如下:

在埋点方案中,明确的所需埋点内容有:
1、事件主体:指“谁”触发了这个事件,分为设备ID和账号ID,上报的事件务必具备其中之一。
设备ID:Android设备和iOS设备的默认设备ID为应用级别唯一的设备ID,由Quicktracking自动生成:
Android9及以下设备:SDK自动采集imei、wifimac、androidid、SN生成设备ID,生成后存入本地,只有卸载应用或者删除应用数据才会重新生成设备ID。
Android10级以上设备:SDK自动采集oaid、gaid、androidid、SN生成设备ID,生成后存入本地,只有卸载应用或者删除应用数据才会重新生成设备ID。
iOS设备:SDK自动采集openudid生成设备ID,生成后放入keychain中,只有恢复出厂设置或者删除应用数据才会重新生成设备ID。
使用应用的C端用户同意采集idfa和oaid,QuickTracking SDK才会采集,只有QuickTracking app SDK可以采集到oaid、gaid、imei、wifimac、androidid、SN、idfa、idfv。
账号ID:客户端用户登录后账号标识,当一个用户在不同的设备进行登录时,设备ID会发生变化,但是账号ID不会发生变化。例如一个用户使用手机和pad分别登录。
2、用户属性:针对账号ID的属性,例如账号ID为“testdemo@111”的用户,“生日”为“1999-02-13”,“会员等级”为“铂金”等。“生日”和“会员”等级就为用户属性。
3、渠道属性:广告投放的属性,例如投放渠道、投放方式、投放内容等。
4、全局属性:在全局设置一次后,每一个事件都会携带的属性
5、页面浏览事件:页面加载时上报的事件(埋点方案中页面编码和事件编码相等的事件,也是标记为蓝色的事件)
6、点击、曝光、自定义事件:客户端用户与客户端发生任意交互时上报的事件。
2 设置设备ID&账号ID
2.1 设备ID设置
SDK 在com.quick.qt.commonsdk 包路径下实现了默认的设备标识符采集工具类DefaultDeviceInfo,此默认实现类默认会采集如下标识。
设备标识或设备信息 | 采集方法 | 备注 |
AndroidID | String getAndroidID(Context context) | Android ID |
Serial | String getSerial() | Android手机设备序列号 |
IMEI | String getImei(Context context) | IMEI |
IMSI | String getImsi(Context context) | IMSI |
WiFi-Mac | String getWifiMac(Context context) | WiFi-Mac |
OAID | String getOaid(Context context) | 广告ID(国内) |
GAID | String getGaid(Context context) | Google广告ID |
MCCMNC | String getMCCMNC(Context context) | MCC:移动国家编码 MNC:移动网号 接口返回值:MCC值和MNC值拼接结果,MCC是3位整数,MNC为两位整数。例如:46011 |
如果开发者希望针对上表中的某几个设备标识符采集行为做控制,如:不采集IMEI字段和Serial字段,自行实现OAID的采集方法。就可以实现一个DefaultDeviceInfo类的子类,重载getImei,getSerial,getOaid三个采集方法,如下示例:
public class CustomDeviceInfo extends DefaultDeviceInfo {
@Override
public String getImei(Context context) {
return null;
}
@Override
public String getSerial() {
return null;
}
@Override
public String getOaid(Context context) {
String oaid = "";
// oaid = getOaidMethod(); // 您自己的 oaid 获取方法
return oaid;
}
}
注意:如果不进行重载,则默认由QuickTracking SDK采集。
2.2 账号ID设置
1、在统计用户时以设备为标准,如果需要统计应用自身的账号,请使用以下接口:
public static void onProfileSignIn(String ID);
参数 | 含义 |
ID | 用户账号ID,长度小于64字节 |
注意:账号ID设置后将被存入本地存储,只有卸载App、清空应用数据或者调用下述的登录接口时,账号ID才会失效,否则每一个事件都将携带账号ID。
2、账号登出时需调用此接口,调用之后不再发送账号相关内容。
public static void onProfileSignOff();
示例:
//当用户使用自有账号登录时,可以这样统计:
QtTrackAgent.onProfileSignIn("userID");
//登出
QtTrackAgent.onProfileSignOff();
2.3 设备ID获取
设备id的获取
可使用下述方法获取:
QtConfigure.getUMIDString()
3 设置用户属性
通过预置事件编码 $$_user_profile 上报用户属性。
在上报用户属性之前,需要先设置_user_id上报用户账号,否则QuickTracking流量分析对用户属性不会进行关联计算。确认上报用户的账号ID后,上报用户属性示例如下:
Map<String, Object> user = new HashMap<String, Object>();
user.put("sex", "girl");//性别
user.put("age", "8"); //年龄
QtTrackAgent.onEventObject(this, "$$_user_profile", user);
4 渠道属性
4.1 H5链接唤起App
渠道属性无需进行任何埋点,但是需要唤起小程序或App的URL中携带这些渠道属性,且属性key务必以“utm_”开头,因为SDK识别的关键字为“utm_”。例如:
<URL scheme>?utm_channel=gzh
PS:如果渠道属性已经与市面上渠道投放公司进行了合作,无法使用utm_开头,可以使用全局属性API将渠道属性进行埋点上报(属性key依然需要以“utm_”开头)。
4.2 H5链接唤起应用市场下载并启动App
该场景下,如果仅是H5链接中携带“utm_”参数,已经无法做到下载App后的启动事件携带“utm_”参数。所以需要进行“H5唤起事件”与“App启动事件”做关于“IP地址和浏览器UserAgent”的模糊匹配。
当H5唤起App时,上报“应用唤起事件($$_app_link)”,在事件中需要携带唤起App的appkey
//示例
aplus_queue.push({
action:'aplus.recordAppLink',
arguments:[{
targetAppKey: '要唤起的应用appKey', // 必填,要唤起的应用appKey
custom1: 'custom1', // 选填,自定义参数
...
}]
})
App下载后的第一次启动事件“应用激活事件($$_app_install)”由QT App SDK自动采集上报。
QuickTracking系统进行应用唤起事件($$_app_link)和应用激活事件($$_app_install)关于“IP地址和浏览器UserAgent”的模糊匹配。您使用时,可以直接在app应用中分析“应用激活(预置)”的渠道属性即可。
4.3 App各应用市场活跃数据统计
在初始化函数中的第三个入参Channel即为设置该应用的应用市场:QtConfigure.preInit(this,"您的appkey","Channel-华为");
,QtConfigure.init(this,"您的appkey","Channel-华为",UMConfigure.DEVICE_TYPE_PHONE, "");
5 全局属性
注册全局属性后,后续触发的所有事件都将自动包含这些属性;且这些属性及属性值存入缓存,APP退出后清除。在分析数据时,可根据此属性进行查看和筛选。
5.1 注册一个全局属性
public static void registerGlobalProperties(Context var0, Map<String, Object> var1);
参数 | 含义 |
var0 | 当前宿主进程的ApplicationContext上下文。 |
propertyName | 属性名。 |
propertyValue | 属性值。 |
注意:
属性名、String类型的属性值,只支持大小写字母、数字及下划线!
属性值可以是如下几种Java类型之一:String、Long、Integer、Float、Double、Short。
5.2 删除一个全局属性
public static void unregisterGlobalProperty(Context context, String propertyName);
参数 | 含义 |
context | 当前宿主进程的ApplicationContext上下文。 |
propertyName | 属性名,只支持大小写字母、数字及下划线! |
示例:
删除一个特定的全局属性,删除后,后续触发的所有事件都不再携带该属性。
QtTrackAgent.unregisterGlobalProperty(mContext, "lnch_Source");
5.3 根据Key获取单个全局属性
public static Object getGlobalProperty(Context context, String propertyName);
参数 | 含义 |
context | 当前宿主进程的ApplicationContext上下文。 |
propertyName | 属性名,只支持大小写字母、数字及下划线! |
Object(返回值) | 返回的全局属性值类型可以是如下几种Java类型之一:String、Long、 Integer、Float、Double、Short。必须和注册此全局属性时传入参数类型一致。 |
示例:
String userId = QtTrackAgent.getGlobalProperty(this, "lnch_Source");
5.4 获取所有全局属性
public static String getGlobalProperties(Context context);
参数 | 含义 |
context | 当前宿主进程的ApplicationContext上下文。 |
String(返回值) | 返回字符串中包含所有全局属性及对应的属性值,以 K-V键值对 形式表示全局属性-属性值。多个键值对间用逗号分割。数据外层是大括号。如:{"id":"SA1375","userName":"Mike","account_type":"vip", "MemberLevel":"Level1"} |
示例:
String allSuperProp = QtTrackAgent.getGlobalProperties(mContext);
5.5 清除所有的全局属性
public static void clearGlobalProperties(Context context);
参数 | 含义 |
context | 当前宿主进程的ApplicationContext上下文。 |
示例:
QtTrackAgent.clearGlobalProperties(mContext);
6 页面浏览事件API
6.1 页面手动采集
开发者如果希望对Activity、Fragment、CustomView及其它自定义页面的页面路径和页面停留时长进行采集和统计。可以通过调用MobclickAgent.onPageStart/MobclickAgent.onPageEnd这组接口进行手动埋点。
public static void onPageStart(String viewName);
public static void onPageEnd(String viewName);
参数 | 含义 |
viewName | 自定义页面名。 |
手动统计Fragemnt页面路径的例子代码:
// 一次成对的 onPageStart -> onPageEnd 调用,对应一次非Activity页面(如:Fragment)生命周期统计。
// Fragment页面onResume函数重载
public void onResume() {
super.onResume();
QtTrackAgent.onPageStart("MainScreen"); //统计页面("MainScreen"为页面编码,可自定义)
}
// Fragment页面onResume函数重载
public void onPause() {
super.onPause();
QtTrackAgent.onPageEnd("MainScreen");
}
6.2 页面自动采集
页面自动采集模式,仅支持activity页面的自动采集和上报,对于非activity页面需要调用QtTrackAgent.onPageStart和QtTrackAgent.onPageEnd这组接口手动埋点。
默认开启页面自动采集,SDK在采集会话数据时,默认会主动采集每个Activity页面的路径和页面访问时长数据并上报。如果开发者同时调用页面路径手动采集API QtTrackAgent.onPageStart/onPageEnd,则会导数页面数据重复上报产生冗余页面路径数据,可以在调用QtConfigure.preInit预初始化函数后紧接着调用QtTrackAgent.disableActivityPageCollection()
函数禁止SDK自动采集Activity页面路径数据。
public static void disableActivityPageCollection();
若只需禁止某activity页面的自动采集上报的接口,需要在activity的onCreate函数中调用此函数:
QtTrackAgent.skipMe(this, null);
参数 | 类型 | 备注 |
this | Activity对象 | WebView宿主Activity对象,该参数控制当前页面的自动页面数据是否上报,传this则表示不上报。 |
viewName | 字符串 | 手动埋点时的自定义页面编码,该参数控制当前页面的手动埋点页面数据是否上报,传空则表示上报,传自定义页面编码则表示不上报。 |
6.3 页面属性上传
QtTrackAgent.setPageProperty(),支持给当前页面附加自定义属性。
接口:QtTrackAgent.setPageProperty
参数:
参数 | 含义 |
context | 当前Application的上下文。 |
pageName | 目标页面名,必须和当前页面名一致。如不一致,函数执行无效。 |
pageProperty | 需要关联到页面的k-v键值对参数。value值支持String,Integer,Long,Float,Short,Double类型。 |
示例:
Activity页面开始展现时进行当前页面属性设置示例:
private static final String PAGE_NAME = "page_home"; // 页面名
@Override
public void onResume() {
super.onResume();
QtTrackAgent.onPageStart(PAGE_NAME); // 页面开始展现打点
Map<String, Object> params = new HashMap<>();
params.put("home_param_1", "value11"); // 当前页面相关属性设置
QtTrackAgent.setPageProperty(mContext, PAGE_NAME, params);
}
7 事件埋点
自定义事件可以用于追踪用户行为,记录行为发生的具体细节。
7.1 事件埋点
使用onEventObject接口进行事件的统计,参数值可以是如下几种类型之一:String、Long、Integer、Float、Double、Short。
接口:
public static void onEventObject(Context context, String eventID, Map<String, Object> map)
public static void onEventObject(Context context, String eventID, Map<String, Object> map, String pageName)
参数 | 含义 |
context | 当前宿主进程的ApplicationContext上下文。 |
eventId | 为当前统计的事件ID。 |
map | 对当前事件的参数描述,定义为“参数名:参数值”的HashMap“<键-值>对”。 |
pageName | 事件发生时的页面编码 |
示例:
Map<String, Object> music = new HashMap<String, Object>();
music.put("music_type", "popular");//自定义参数:音乐类型,值:流行
music.put("singer", "JJ"); //歌手:(林俊杰)JJ
music.put("song_name","A_Thousand_Years_Later"); //歌名:一千年以后
music.put("song_price",100); //价格:100元
QtTrackAgent.onEventObject(this, "play_music", music, "home_page");
备注:
多参数类型事件能满足原来计算事件/计数事件的分析场景;
对于计算型事件不同的参数类型对应不同的计算方式,总共可以分为两大类,数值型和字符型
数字型:支持累加值、最大值、最小值、平均值和去重数计算
字符型:支持去重数计算
7.2 子进程埋点
SDK仅支持子进程自定义事件埋点,页面等其他类型采集暂不支持。子进程埋点需要在SDK初始化完成后调用函数QtConfigure.setProcessEvent。
示例:
public class UmengApplication extends Application{
@Override
public void onCreate(){
super.onCreate();
// 初始化SDK
QtConfigure.preInit(this, "您的appkey", "应用市场");
// 支持在子进程中统计自定义事件
QtConfigure.setProcessEvent(true);
// ...
注意:
如果需要在某个子进程中统计自定义事件,则需保证在此子进程中进行SDK初始化。