埋点API

1 如何查看埋点方案

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

image

在埋点方案中,明确的所需埋点内容有:

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”的模糊匹配。

  1. 当H5唤起App时,上报“应用唤起事件($$_app_link)”,在事件中需要携带唤起App的appkey

//示例
aplus_queue.push({
  action:'aplus.recordAppLink',
  arguments:[{
    targetAppKey: '要唤起的应用appKey',  // 必填,要唤起的应用appKey
    custom1: 'custom1', // 选填,自定义参数
    ...
  }]
})
  1. App下载后的第一次启动事件“应用激活事件($$_app_install)”由QT App SDK自动采集上报。

  2. 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

属性值。

注意:

  1. 属性名、String类型的属性值,只支持大小写字母、数字及下划线!

  2. 属性值可以是如下几种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接口进行事件的统计,参数值可以是如下几种类型之一:StringLongIntegerFloatDoubleShort

接口:

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初始化。

阿里云首页 全域采集与增长分析 相关技术圈