Quick Tracking：埋點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三個採集方法，如下樣本：

import com.quick.qt.commonsdk.DefaultDeviceInfo;

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採集，請謹慎決定是否實現對應方法，一旦您選擇自己實現採集方法，此裝置標識的採集工作就由您全權接管了，SDK不會再試圖採集此裝置標識。SDK能採集到的裝置標識越少，對統計資料的準確性和穩定性的負面影響越大。

自訂工具類註冊：

import com.quick.qt.commonsdk.QtConfigure;

// 請在設定收數網域名稱之前，調用SDK預初始化函數之前，先調用採集工具類註冊函數
// 如果不需要對裝置標識採集行為做控制，就不需要實現自訂工具類並註冊它。
QtConfigure.setDeviceInfo(new CustomDeviceInfo());
QtConfigure.setCustomDomain("您的收數服務網域名稱", null);

SDK支援自訂裝置ID，如果要使用自訂裝置ID需要在初始化前（即init前） 設定setCustomDeviceId 介面為有效值（非空）。

public static void setCustomDeviceId(Context var0, String var1)

使用樣本：

import com.quick.qt.commonsdk.QtConfigure;

QtConfigure.setCustomDeviceId(this, "xxxxxx");

注意：因此功能在未擷取裝置ID時生效，本地如果已存在裝置ID，設定後無效。如果本地已擷取到裝置ID可以通過卸載重裝方式驗證此功能。

2.2 裝置ID的擷取

可使用下述方法擷取：

import com.quick.qt.commonsdk.QtConfigure;

QtConfigure.getUMIDString(this)

2.3 帳號ID設定

1、在統計使用者時以裝置為標準，如果需要統計應用自身的帳號，請使用以下介面：

public static void onProfileSignIn(String ID);

注意：帳號ID設定後將被存入本機存放區，只有卸載App、清空應用資料或者調用下述的登入介面時，帳號ID才會失效，否則每一個事件都將攜帶帳號ID。

2、帳號登出時需調用此介面，調用之後不再發送帳號相關內容。

public static void onProfileSignOff();

樣本：

import com.quick.qt.analytics.QtTrackAgent;

//當使用者使用自有帳號登入時，可以這樣統計：
QtTrackAgent.onProfileSignIn("userID");

//登出
QtTrackAgent.onProfileSignOff();

import com.quick.qt.analytics.QtTrackAgent;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> user = new HashMap<String, Object>();
user.put("sex", "girl");//性別
user.put("age", "8"); //年齡
QtTrackAgent.onEventObject(mContext, "$$_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喚起事件”與“應用啟用事件”做關於“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-華為",QtConfigure.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。

3. 如果和已經存在的全域屬性key重複，則更新已有值；如果和已經存在的全域屬性key不一致，則插入新的全域屬性。

   樣本：

   import com.quick.qt.analytics.QtTrackAgent;
   import java.util.HashMap;
   import java.util.Map;
   
   Map firstMap = new HashMap<String, Object>();
   firstMap.put("a", "1");
   firstMap.put("b", "2");
   QtTrackAgent.registerGlobalProperties(mContext, firstMap);//當前globalproperty為a:1和b:2
   
   Map secondMap = new HashMap<String, Object>();
   secondMap.put("b", "3");
   secondMap.put("c", "4");
   QtTrackAgent.registerGlobalProperties(mContext, secondMap);//當前globalproperty為a:1、b:3和c:4

5.2 刪除一個全域屬性

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

樣本：

刪除一個特定的全域屬性，刪除後，後續觸發的所有事件都不再攜帶該屬性。

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.unregisterGlobalProperty(mContext, "lnch_Source");

5.3 根據Key擷取單個全域屬性

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

樣本：

import com.quick.qt.analytics.QtTrackAgent;

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

5.4 擷取所有全域屬性

public static String getGlobalProperties(Context context);

樣本：

import com.quick.qt.analytics.QtTrackAgent;

String allSuperProp = QtTrackAgent.getGlobalProperties(mContext);

5.5 清除所有的全域屬性

public static void clearGlobalProperties(Context context);

樣本：

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.clearGlobalProperties(mContext);

6 頁面瀏覽事件API

6.1 頁面手動採集

開發人員如果希望對Activity、Fragment、CustomView及其它自訂頁面的頁面路徑和頁面停留時間長度進行採集和統計。可以通過調用QtTrackAgent.onPageStart/QtTrackAgent.onPageEnd這組介面進行手動埋點。

public static void onPageStart(String viewName);
public static void onPageEnd(String viewName);

手動統計Fragemnt頁面路徑的例子代碼：

import com.quick.qt.analytics.QtTrackAgent;

// 一次成對的 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");
}

注意：

onPageStart 是SDK記錄頁面進入的資訊，onPageStart不會上報事件，只有調用onPageEnd的時候才會上報頁面瀏覽事件。

onPageStart和onPageEnd必須成對調用，且傳值的page_name需要保持一致，如果沒有onPageEnd或者onPageEnd與onPageStart傳值的page_name不一致，則onPageStart記錄的資訊不會生效。

6.1.1 頁面屬性上傳

QtTrackAgent.setPageProperty()，支援給當前頁面附加自訂屬性。

介面：QtTrackAgent.setPageProperty

參數：

樣本：

Activity頁面開始展現時進行當前頁面屬性設定樣本：

import com.quick.qt.analytics.QtTrackAgent;

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

請注意：頁面屬性設定只支援頁面手動埋點

6.1.2 透傳頁面屬性

此外，QuickTracking SDK提供了SpmAgent.updateNextPageProperties介面，該介面支援給下一個頁面附加自訂屬性。

介面：SpmAgent.updateNextPageProperties

參數：

支援的類型：

/**
* 
此函數在跳轉到下⼀個⽬標⻚⾯時調⽤。
*/
public static void updateNextPageProperties(Map<String, Object> params)

傳值樣本：

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.spm.SpmAgent;

public class MainActivity extends AppCompatActivity {
    private static final String PAGE_NAME = "page_home"; // 頁面名
    private Button mGoNewsWithHole;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        setTitle("QuickTracking統計Home頁");
        setContentView(R.layout.activity_u4a_home);

        binding.btnGoToDetail.setOnClickListener(v -> {
            // 給下一個頁面添加自訂屬性
            Map<String, Object> params = new HashMap<>();
            params.put("my_transfer_arg1", "MainActivity帶過去的透傳屬性值");
            SpmAgent.updateNextPageProperties(params); //
            startActivity(new Intent(this, DetailActivity.class));
        });
    }
 }

取值樣本：

import com.quick.qt.spm.SpmAgent;

String transferValue = SpmAgent.getPageProperty(PAGE_NAME, "my_transfer_arg1", SpmAgent.transProperties);

請注意：透傳頁面屬性只支援頁面手動埋點

6.2 Activity頁面自動採集（全埋點）

Activity頁面預設開啟頁面自動採集，無須整合全埋點的gradle 外掛程式。SDK在採集會話資料時，預設會主動採集每個Activity頁面的路徑和頁面訪問時間長度資料並上報。如果開發人員同時調用頁面路徑手動採集API QtTrackAgent.onPageStart/onPageEnd，則會導致頁面資料重複上報，產生冗餘頁面路徑資料，可以在調用QtConfigure.preInit預初始化函數後緊接著調用QtTrackAgent.disableActivityPageCollection()函數禁止SDK自動採集Activity頁面路徑資料。

public static void disableActivityPageCollection();

若只需禁止某activity頁面的自動採集上報的介面，需要在activity的onCreate函數中調用此函數：

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

6.3 Fragment頁面自動採集（全埋點）

Fragment頁面預設沒有自動採集，需要整合全埋點的外掛程式並開啟自動採集開關才可以。具體操作可以查看

8.1 全埋點gradle外掛程式引入和開啟Fragment PV資料全埋點。

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)

事件上傳數量限制：

• 自訂屬性key字串長度上限：1024

• 自訂屬性value字串長度上限：1024*4

• 自訂屬性map長度（參數個數）：100 個索引值對

• 當自訂屬性值value為數組元素時，屬性值的數組長度上限：100

數實值型別說明：

樣本：

import com.quick.qt.analytics.QtTrackAgent;

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

備忘：

• 當前拉取事件採樣率配置依賴於自動採集開關，使用SDK時需要調用setAutoEventEnabled()方法；

  樣本：

  public class MyApplication extends Application {
  
      @Override
      public void onCreate() {
          super.onCreate();
  	QtConfigure.setCustomDomain("您的收數服務網域名稱", null);
          // 開啟調試log
          QtConfigure.setLogEnabled(true);
          // 採樣率拉取依賴全埋點開關設定，如需要事件採樣率控制功能，請按需調用此API
          QtTrackAgent.setAutoEventEnabled(false);        
          //...
      }
      //... 
  }

• 多參數類型事件能滿足原來計算事件/計數事件的分析情境；

• 對於計算型事件不同的參數類型對應不同的計算方式，總共可以分為兩大類，數值型和字元型

  • 數字型：支援累加值、最大值、最小值、平均值和去重數計算

  • 字元型：支援去重數計算

7.2 子進程埋點

SDK僅支援子進程自訂事件埋點，頁面等其他類型採集暫不支援。子進程埋點需要在SDK初始化完成後調用函數QtConfigure.setProcessEvent。

樣本：

public class MyApplication extends Application{
    @Override
    public void onCreate(){
        super.onCreate();
        // 初始化SDK
        QtConfigure.preInit(this, "您的appkey", "應用市場");
        
        // 支援在子進程中統計自訂事件
        QtConfigure.setProcessEvent(true);
        // ...

注意：

• 如果需要在某個子進程中統計自訂事件，則需保證在此子進程中進行SDK初始化。

8 全埋點（自動埋點）

8.1 全埋點gradle外掛程式引入

buildscript {
    repositories {
        maven { url 'https://repo1.maven.org/maven2/' } // QuickTracking倉庫
        jcenter()
            google()
        }
    
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.4'
            
            // 添加QuickTracking外掛程式 android-gradle-plugin 依賴
            // 適配 gradle 7.1.2 以下版本
            //classpath 'com.umeng.umsdk:android-gradle-plugin:1.0.0' 
            // 適配 gradle 7.1.2 ~ 7.5 版本
            classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:1.0.2'
            // 適配 gradle 7.5 ～ 8+ 版本
            // classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.0'
            // 適配 gradle 9+ 版本
            // classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.1'
        }
}

allprojects {
    repositories {
        maven { url 'https://repo1.maven.org/maven2/' } // QuickTracking倉庫
        jcenter()
            google()
        }
}

pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
        maven { url 'https://repo1.maven.org/maven2/' }// QuickTracking倉庫
    }

}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://repo1.maven.org/maven2/' }// QuickTracking倉庫
    }
}

buildscript {
    dependencies {
        classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.1'
    }
}

8.2 依賴使用gradle編譯外掛程式

在主 module 的 build.gradle 配置中應用全埋點外掛程式：

apply plugin: 'com.android.application'
//apply plugin: 'com.qt.analytics.plugin' // P版本外掛程式（全埋點情境）
apply plugin: 'com.quick.analytics.plugin' // PX版本外掛程式（全埋點情境）

dependencies {
   // 添加 QuickTracking 統計SDK，SDK版本需要與上述的gradle版本匹配
   //implementation 'com.umeng.umsdk:qt-common:1.4.4.P' //P版本（SDK版本為x.x.x.P）
   implementation 'com.lydaas.qtsdk:qt-px-common:1.8.6.PX'  // PX版本（SDK版本為x.x.x.PX）
}

8.3 全埋點API

8.3.1 全埋點開關

開啟Fragment PV資料全埋點

通過 enableFragmentPageCollection() 方法可以開啟全部 Fragment 頁面瀏覽事件的自動採集功能。

/**
* Fragment 頁面資料自動採集開關，SDK預設關閉
* @param enable true-開啟; false-關閉
*/
public static void enableFragmentPageCollection(boolean enable);

樣本：

import com.quick.qt.commonsdk.QtConfigure;
import com.quick.qt.analytics.QtTrackAgent;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
	QtConfigure.setCustomDomain("您的收數服務網域名稱", null);
        // 開啟調試log
        QtConfigure.setLogEnabled(true);
        // 開啟全部 Fragment 頁面瀏覽事件的自動採集功能
        QtTrackAgent.enableFragmentPageCollection(true);
        //...
    }
    //... 
}

開啟Activity PV資料開關

預設開啟Activity頁面自動採集，SDK在採集會話資料時，預設會主動採集每個Activity頁面的路徑和頁面訪問時間長度資料並上報。如果開發人員同時調用頁面路徑手動採集API QtTrackAgent.onPageStart/onPageEnd，則會導數頁面資料重複上報產生冗餘頁面路徑資料，可以在調用QtConfigure.preInit預初始化函數後緊接著調用QtTrackAgent.disableActivityPageCollection()函數禁止SDK自動採集Activity頁面路徑資料。

public static void disableActivityPageCollection();

若只需禁止某activity頁面的自動採集上報的介面，需要在activity的onCreate函數中調用此函數：

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

關閉某個頁面的自動採集

若只需禁止某activity頁面的自動採集上報的介面，需要在activity的onCreate函數中調用此函數：

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

開啟控制項點擊資料全埋點

/**
 * 拉取事件採樣率配置。
 * 設定是否自動採集控制項點擊事件, SDK預設不自動採集。
 * @param enable true-自動採集; false-不自動採集
 */
public static void setAutoEventEnabled(boolean enable);

樣本：

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.commonsdk.QtConfigure;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
	QtConfigure.setCustomDomain("您的收數服務網域名稱", null);
        // 開啟調試log
        QtConfigure.setLogEnabled(true);
        QtTrackAgent.enableFragmentPageCollection(true);
        // 開啟控制項點擊事件的自動採集功能。
        QtTrackAgent.setAutoEventEnabled(true);
        //...
    }
    //...
    
}

支援自動監控的控制項類型列表：

8.3.2 自動Activity/Fragment PV設定自訂屬性

通過給特定Activity/Fragment 實現介面 com.umeng.analytics.autotrack.PageAutoTracker，可以給自動採集的Activity/Fragment頁面定製化屬性、頁面名、或者來源頁面名。

public interface PageAutoTracker {
    /**
     * 返回當前頁面名
     * @return 如果不需要自訂頁面名則返回null或者Null 字元串
     */
    String getPageName();

    /**
     * 返回來源頁面名
     * @return 如果不需要自訂來源頁面名則返回null或者Null 字元串
     */
    String getRefPageName();

    /**
     * 返回自訂屬性索引值對，Key和Value都需要是字串類型，如果沒有自訂屬性請返回null
     *
     * @return 如果沒有自訂屬性請返回null
     */
    Map<String, String> getTrackProperties();
}

樣本：

import com.quick.qt.analytics.QtTrackAgent;

/**
 * 給FragmentContacts指定 自訂頁面名 及 自訂頁面屬性
 */
public static class FragmentContacts extends Fragment implements PageAutoTracker {
        private final String mPageName = "FragmentContacts";

        static FragmentSimple newInstance(int num) {
            FragmentSimple f = new FragmentSimple();

            // Supply num input as an argument.
            Bundle args = new Bundle();
            args.putInt("num", num);
            f.setArguments(args);

            return f;
        }

        /**
         * The Fragment's UI is just background simple text view showing its instance
         * number.
         */
        @Override
        public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {

            FrameLayout fl = new FrameLayout(getActivity());
            fl.setLayoutParams(new FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT,
                    FrameLayout.LayoutParams.MATCH_PARENT));
            fl.setBackgroundColor(Color.LTGRAY);
            TextView tv = new TextView(getActivity());
            tv.setText("Fragment Contacts");
            tv.setTextColor(Color.BLACK);
            tv.setOnClickListener(new View.OnClickListener() {
                @Override
                public void onClick(View v) {
                    QtTrackAgent.ignoreView(v); // 禁止TextView控制項的自動採集資料上報
                    Toast.makeText(getActivity(), "文字框被點擊了", Toast.LENGTH_LONG).show();
                }
            });
            fl.addView(tv);
            return fl;
        }

        // 自訂FragmentContacts頁面名
        @Override
        public String getPageName() {
            return "FragmentContacts";
        }

    	// 不需要自訂FragmentContacts的來源頁面名，所以直接返回null
        @Override
        public String getRefPageName() {
            return null;
        }

    	// 自訂FragmentContacts頁面自訂屬性
        @Override
        public Map<String, String> getTrackProperties() {
            Map<String, String> properties = new HashMap<>();
            properties.put("fragment_arg1", "fragment_value111");
            properties.put("fragment_arg2", "fragment_value222");
            return properties;
        }
    }

8.3.3 設定控制項點擊事件自訂屬性

通過 setViewProperties() 方法，可以對特定控制項設定自訂屬性，自訂屬性可以設定多個K-V索引值對，Key和Value都需要是字串類型。自訂屬性和值會包含在此控制項全埋點點擊事件數目據中。

/**
* 設定控制項自訂屬性，自訂屬性可以設定多個K-V索引值對，Key和Value都需要是字串類型
* @param view 控制項對象
* @param properties 自訂屬性
*/
public static void setViewProperties(View view, JSONObject properties);

樣本：

import com.quick.qt.analytics.QtTrackAgent;

@QtDataTrackViewOnClick
public void onClick(View v) {
    int id = v.getId();
    Intent in = null;
    if (id == R.id.normal) {
        // 對Resource ID為 normal 的Button控制項設定自訂事件ID ekv_normal。
        // 設定後，點擊此控制項是SDK上報資料中事件ID就為"ekv_normal"。
        QtTrackAgent.setViewEventID(v, "ekv_normal");
        // 針對 normal Button控制項點擊事件(即ekv_normal 事件)，設定自訂屬性值。
        // customArgs內屬性和屬性值會包含在"ekv_normal"事件數目據中一起上報。
        JSONObject customArgs = new JSONObject();
        try {
            customArgs.put("customArg1", "value1111");
            customArgs.put("customArg2", "value2222");
        } catch (JSONException e) {
        
        }
        QtTrackAgent.setViewProperties(v, customArgs);
      }
   }

8.3.4 給控制項點擊事件設定自訂事件編碼

通過 setViewEventID() 方法，給特定控制項的點擊事件設定自訂事件編碼。

/**
* 針對自動採集的控制項點擊事件，設定自訂事件編碼
* @param view 控制項對象
* @param eventID 自訂事件編碼
*/
public void setViewEventID(View view, String eventcode);

樣本：

import com.quick.qt.analytics.QtTrackAgent;

@QtDataTrackViewOnClick
public void onButtonClick(View v) {
    int id = v.getId();
    Intent in = null;
    if (id == R.id.normal) {
       // 對Resource ID為 normal 的Button控制項設定自訂事件編碼 ekv_normal。
       // 設定後，點擊此控制項是SDK上報資料中事件編碼就為"ekv_normal"。
       QtTrackAgent.setViewEventID(v, "ekv_normal");
       //...
    }
}

8.3.5 處理通過 onClick 屬性設定的點擊事件

通過布局檔案中 android:onClick 屬性配置的點擊回調方法執行時無法自動觸發控制項點擊事件。此時可以給 android:onClick 屬性對應的方法加上 @QtDataTrackViewOnClick 註解，這樣在方法執行時，SDK就可以自動觸發控制項點擊事件。例如：

布局檔案：

<Button
    android:id="@+id/normal"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginTop="24dp"
    android:onClick="onButtonClick"
    android:text="@string/ana_name"/>

onClick事件自訂處理函數：

import com.quick.qt.analytics.autotrack.QtDataTrackViewOnClick;

@QtDataTrackViewOnClick
public void onButtonClick(View v) {
    //...
}

8.3.6 忽略特定類型控制項點擊事件的自動採集

通過 ignoreViewType() 方法忽略特定類型控制項點擊事件的自動採集。

/**
* 忽略viewType類型控制項點擊事件的自動採集行為。
* 該方法支援多次調用，對設定結果合集進行忽略。
* @param viewType
*/
public static void ignoreViewType(Class viewType);

樣本：

import com.quick.qt.analytics.QtTrackAgent;

// 忽略Button類型控制項點擊事件
QtTrackAgent.ignoreViewType(Button.class);

8.3.7 忽略特定控制項點擊事件的自動採集

通過 ignoreView() 方法忽略特定控制項點擊事件的自動採集。

/**
* 忽略某個 View 對象的點擊事件自動採集行為。
*
* @param view 對象
*/
public static void ignoreView(View view);

樣本：

import com.quick.qt.analytics.QtTrackAgent;

Button myButton = (Button)findViewById(R.id.testButton);
// 忽略myButton控制項點擊事件
QtTrackAgent.ignoreView(myButton);

8.4 曝光埋點

使用自動曝光埋點功能時，使用者需要在配置項手動開啟自動曝光功能

import com.quick.qt.analytics.QtTrackAgent;

// 開啟曝光統計
QtTrackAgent.enableExposureCollection();

當然您也可以在需要的時候關閉自動曝光功能

// 關閉曝光統計
QtTrackAgent.disableExposureCollection();

8.4.1 曝光配置項

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.QtTrackAgent;

// 通用曝光設定
QTExposureConfig config = new QTExposureConfig.Builder()
                .setMinDuration(300) // 曝光最小顯示時間(毫秒)
                .setMinVisibleRatio(0.5f) /// 最小顯示百分比
                .setRepeated(true) // 是否重複曝光
                .setCallback(new QTExposureConfig.ExposureCallback() { // 曝光回調
                    @Override
                    public void onExposure(View view) {
                        Toast.makeText(mContext, "曝光成功", Toast.LENGTH_SHORT).show();
                    }
                })
                .build();
        
QtTrackAgent.setExposureConfig(config);

QTExposureConfig為曝光配置屬性其詳細參數如下：

8.4.2 設定全域曝光配置

通過QtTrackAgent.setExposureConfig(config)方法可以設定全域曝光屬性，建議在初始化SDK之前調用

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.QtTrackAgent;

// 通用曝光設定
QTExposureConfig config = new QTExposureConfig.Builder()
                .setMinDuration(300) // 曝光最小顯示時間(毫秒)
                .setMinVisibleRatio(0.5f) /// 最小顯示百分比
                .setRepeated(true) // 是否重複曝光
                .setCallback(new QTExposureConfig.ExposureCallback() { // 曝光回調
                    @Override
                    public void onExposure(View view) {
                        Toast.makeText(mContext, "曝光成功", Toast.LENGTH_SHORT).show();
                    }
                })
                .build();
        
QtTrackAgent.setExposureConfig(config);

8.4.3 標記曝光元素

要使用曝光功能，您需要手動綁定曝光元素，您可以調用QtTrackAgent.addExposureView()方法來實現曝光元素的綁定

import com.quick.qt.analytics.QtTrackAgent;

  /**
   * 標記曝光元素
   *
   * @param view          需要統計曝光的視圖對象
   * @param exposureData  包含曝光資料參數的對象
   * @return              無傳回值
   */
public static void addExposureView(View view, QTExposureData data) {
    QtTrackAgent.addExposureView(view, data);
}

參數說明：

QTExposureData API：

// 引入包名
import com.quick.qt.analytics.exposure.QTExposureData;

/**
 *使用指定的事件名稱初始化曝光資料。
 *
 * @param event 事件名稱
 */
public QTExposureData(String event) 

/**
 * 使用指定的事件名稱和自訂屬性初始化曝光資料。
 *
 * @param event     事件名稱
 * @param properties 自訂事件屬性
 */
public QTExposureData(String event, Map<String, Object> properties) 

/**
 * 使用指定的事件名稱、自訂屬性和曝光配置初始化曝光資料。
 *
 * @param event        事件名稱
 * @param properties   自訂事件屬性
 * @param exposureConfig 曝光配置
 */
public QTExposureData(String event,  Map<String, Object>  properties, QTExposureConfig exposureConfig) 

參數說明：

注意：

1. 屬性名稱、String類型的屬性值，只支援大小寫字母、數字及底線！

2. 屬性值可以是如下幾種Java類型之一：String、Long、Integer、Float、Double、Short。

3. 如果和已經存在的全域屬性key重複，則更新已有值；如果和已經存在的全域屬性key不一致，則插入新的全域屬性。

   樣本：

   import com.quick.qt.analytics.exposure.QTExposureData;
   
   Map<String, Object> properties = new HashMap<>();
   properties.put("param1", item.text); // 自訂參數1
   properties.put("param2", position); // 自訂參數2
   
   QTExposureData exposureData = new QTExposureData("事件編碼", properties))

普通元素標記

範例程式碼：

import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// 構造曝光資料
QTExposureData exposureData = new QTExposureData("exposure_view_click");
QtTrackAgent.addExposureView(imageView, exposureData);

列表類元素標記

標記全部元素

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// 構造曝光資料
public void onBindViewHolder(@NonNull ViewHolder holder, final int position) {
    View view = holder.xxxx; 
    Map<String, Object> properties = new HashMap<>();
    properties.put("param1", item.text); // 自訂參數1
    properties.put("param2", position); // 自訂參數2
    QtTrackAgent.addExposureView(convertView, new QTExposureData(item.text, properties));
}

標記單個元素：

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// 構造曝光資料
public void onBindViewHolder(@NonNull ViewHolder holder, final int position) {
     View view = holder.xxxx; 
     if(item.text.contains("New")){
          Map<String, Object> properties = new HashMap<>();
          properties.put("$$item_reused_id","自訂id"); // 單個元素需要標記當前元素的自訂id，避免重複
          properties.put("text", item.text); // 自訂參數1
          properties.put("position", position); // 自訂參數1
          QtTrackAgent.addExposureView(convertView, new QTExposureData(item.text, properties));
     }
}

8.4.4 移除曝光元素

元素本身被移除即會移除對應埋點監控（如刪除某一列表）

當然您可以使用QtTrackAgent.removeExposureView()來移除不需要曝光採集的元素

import com.quick.qt.analytics.QtTrackAgent;

/**
 * 使用指定的事件名稱和自訂屬性初始化曝光資料。
 *
 * @param view        已經標註的元素
 * @param item_reused_id 自訂id (如果有自訂元素id 傳入id) 
 */
QtTrackAgent.removeExposureView(view,"自訂id");

9 分享裂變

分享裂變是增長駭客策略的一個關鍵概念，它依靠使用者之間的社交聯絡來實現資訊的相互傳遞，從而促進新使用者的擷取。

完成分享裂變的SDK功能整合，您將可以使用QuickTracking平台分享趨勢模型，通過分享迴流相關指標衡量營銷活動的拉新效益。

1. 支援查看TOP分享使用者和不同分享迴流層級的分享迴流效果指標。

2. 支援迴流指標靈活組合配置，查看最具裂變拉新能力和分享迴流轉化能力的TOP使用者，追蹤使用者分享裂變鏈路與分享迴流關係，快速定位關鍵意見消費者。

9.1 擷取來源分享參數

import com.quick.qt.analytics.QtTrackAgent;
/**
 * 來源分享參數擷取API
 * @param context 宿主App的ApplicationContext對象。必須傳入
 * */
public static Map<String, String> getRefShareParams(Context context);

版本

Android SDK v1.6.0.PX版本及以上

功能

在請求分享參數之前，用於擷取來源分享id 和來源分享 url 的 API

請求參數

返回參數

調用樣本

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

public class DemoActivity {
    ...
    public void onShare() {
        Context context = DemoActivity.this;
        Map<String, String> refShareParams = QtTrackAgent.getRefShareParams(context);
        String $$_ref_share_id = refShareParams.get("$$_ref_share_id");
        
        Map<String, String> shareParams = new HashMap<String, String>();
        shareParams.put("shareId", $$_ref_share_id);
        shareParams.put("title", "分享活動A");
        shareParams.put("campaign", "分享活動A");
        QtTrackAgent.requestShareParams(context, "https://www.taobao.com/productId", shareParams, 0, new ShareResultHandler() {
            @Override
            public void onShareResultSuccess(final JSONObject result) {
                try {
                    Log.i("Test", "shareParams = " + result.toString());
                    String $sid = result.getString("shareId");
                    Map<String, Object> properties = new HashMap<String, Object>();
                    properties.put("$$_share_id", $sid);
                    properties.put("$$_share_url", "https://www.taobao.com/productId"); 
                    properties.put("$$_share_title","分享活動A"); 
                    properties.put("$$_share_campaign_id", "這是一個自訂分享活動");
                      // 
                    properties.put("$$_share_type", "使用者自訂分享目標平台");
                    QtTrackAgent.onEventObject(this, "$$_share", properties);
                    // 假設這是後台線程中的某個操作
                    new Thread(new Runnable() {
                        @Override
                        public void run() {
                            // 執行一些背景工作...

                            // 需要更新UI，切回主線程
                            runOnUiThread(new Runnable() {
                                @Override
                                public void run() {
                                    // 在主線程上顯示對話方塊
                                    AlertDialog.Builder builder = new AlertDialog.Builder(context);
                                    builder.setTitle("分享參數");
                                    builder.setMessage(result.toString());
                                    builder.show();
                                }
                            });
                        }
                    }).start();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }

            @Override
            public void onShareResultFail(Throwable t) {
                Log.i("Test", "fail = " + t.getMessage());
            }
        });
    }
    ...
}

9.2 請求分享參數

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

/**
 * 分享 url 擷取API
 * @param context 宿主App的ApplicationContext對象。必須傳入
 * @param url 頁面的地址，必須傳入
 * @param params 可能的分享參數，可為 null
 *    {
 *      title: 分享標題, 可為 null, 最大長度 4*1024
 *    campaign: 分享活動, 可為 null, 最大長度 4*1024
 *    shareId: 來源分享Id, 可為 null
 *      ... 待擴充
 *  }
 * @params timeout 請求逾時時間，單位秒，有效值範圍：0~10（包含0和10），如果傳入0，則使用sdk內部預設值3秒
 * @param callback 結果回調對象，必須傳入，不能為null
 * */
public static void requestShareParams(Context context, String url, Map<String, String> params, int timeout,final ShareResultHandler callback)

版本

Android SDK v1.6.0.PX版本及以上

功能

請求用於構建分享鏈需要的分享id

請求參數

其中 callback 的回調介面 ShareResultHandler 定義如下：

public interface ShareResultHandler {
    //本方法在分享參數成功返回時會回調
    void onShareResultSuccess(JSONObject result);
    //本方法在分享參數失敗返回時會回調, 可通過t.getMessage 擷取失敗原因
    void onShareResultFail(Throwable t);
}

返回參數

調用樣本

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

public class DemoActivity {
    ...
    public void onShare() {
        Context context = DemoActivity.this;
        Map<String, String> shareParams = new HashMap<String, String>();
        shareParams.put("shareId", "");
        shareParams.put("title", "分享活動A");
        shareParams.put("campaign", "分享活動A");
        QtTrackAgent.requestShareParams(context, "https://www.taobao.com/productId", shareParams, 0, new ShareResultHandler() {
            @Override
            public void onShareResultSuccess(final JSONObject result) {
                try {
                    Log.i("Test", "shareParams = " + result.toString());
                    String $sid = result.getString("shareId");

                    Map<String, Object> properties = new HashMap<String, Object>();
                    properties.put("$$_share_id", $sid);
                    properties.put("$$_share_url", "https://www.taobao.com/productId"); 
                    properties.put("$$_share_title","分享活動A"); 
                    properties.put("$$_share_campaign_id", "這是一個自訂分享活動");
                    properties.put("$$_share_type", "使用者自訂分享平台");
                    QtTrackAgent.onEventObject(this, "$$_share", properties);
                    
                    // 假設這是後台線程中的某個操作
                    new Thread(new Runnable() {
                        @Override
                        public void run() {
                            // 執行一些背景工作...

                            // 需要更新UI，切回主線程
                            runOnUiThread(new Runnable() {
                                @Override
                                public void run() {
                                    // 在主線程上顯示對話方塊
                                    AlertDialog.Builder builder = new AlertDialog.Builder(context);
                                    builder.setTitle("分享參數");
                                    builder.setMessage(result.toString());
                                    builder.show();
                                }
                            });
                        }
                    }).start();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }

            @Override
            public void onShareResultFail(Throwable t) {
                Log.i("Test", "fail = " + t.getMessage());
            }
        });
    }
}

9.3 上報分享事件

通過預置事件編碼 $$_share 上報分享事件

樣本

import com.quick.qt.analytics.QtTrackAgent;

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("$$_share_id", "通過請求分享參數API擷取到的分享ID");
properties.put("$$_share_url", "https://www.taobao.com/productId"); 
properties.put("$$_share_title","分享活動A"); 
properties.put("$$_share_campaign_id", "這是一個自訂分享活動");
properties.put("$$_share_type", "使用者自訂分享平台");
QtTrackAgent.onEventObject(this, "$$_share", properties);

請注意：喚起的連結需要攜帶key為"$sid"，value為分享Id的參數，如：https://example.aliyun.com/path/to/content?$sid=123456"