埋点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，此默认实现类默认会采集如下标识。

如果开发者希望针对上表中的某几个设备标识符采集行为做控制，如：不采集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设置后将被存入本地存储，只有卸载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', // 选填，自定义参数
    ...
  }]
})

2. App下载后的第一次启动事件“应用激活事件（$$_app_install）”由QT App SDK自动采集上报。

3. 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);

注意：

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

2. 属性值可以是如下几种Java类型之一：String、Long、Integer、Float、Double、Short。

5.2 删除一个全局属性

public static void unregisterGlobalProperty(Context context, String propertyName);

示例：

删除一个特定的全局属性，删除后，后续触发的所有事件都不再携带该属性。

QtTrackAgent.unregisterGlobalProperty(mContext, "lnch_Source");

5.3 根据Key获取单个全局属性

public static Object getGlobalProperty(Context context, String propertyName);

示例：

String userId = QtTrackAgent.getGlobalProperty(this, "lnch_Source");

5.4 获取所有全局属性

public static String getGlobalProperties(Context context);

示例：

String allSuperProp = QtTrackAgent.getGlobalProperties(mContext);

5.5 清除所有的全局属性

public static void clearGlobalProperties(Context context);

示例：

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);

手动统计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); 

6.3 页面属性上传

QtTrackAgent.setPageProperty()，支持给当前页面附加自定义属性。

接口：QtTrackAgent.setPageProperty

参数：

示例：

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)

示例：

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