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 內部預設會採集如下參數。

如果開發人員希望針對上表中的某幾個裝置標識符採集行為做控制，如：不採集或自行實現採集方法。可以實現對應block回調，如下樣本：

[QTConfigure customSetIdfaBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetIdfvBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetOpenUdidBlock:^NSString *{
  return @"custom-openudid";
}];
[QTConfigure customSetUtdidBlock:^NSString *{
  return @"custom-utdid";
}];
[QTConfigure customSetMccBlock:^NSString *{
  return @"custom-mcc";
}];
[QTConfigure customSetMncBlock:^NSString *{
  return @"custom-mnc";
}];

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

// 請在設定收數網域名稱之前，調用SDK預初始化函數之前，先調用採集工具類註冊函數
// 如果不需要對裝置標識採集行為做控制，就不需要實現自訂工具類並註冊它
[QTConfigure customSetIdfvBlock:^NSString *{
    return [[UIDevice currentDevice].identifierForVendor UUIDString];
}];
[QTConfigure setCustomDomain:@"您的收數網域名稱" standbyDomain:nil];
[QTConfigure initWithAppKey:@"您的appkey" channel:@"App Store"];

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

+ (void)setCustomDeviceId:(NSString *)devID;

使用樣本：

[QTConfigure setCustomDeviceId:@"xxxxxx"];

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

2.2 帳號ID設定

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

介面函數：

+ (void)profileSignInWithPUID:(NSString *)puid;

參數：

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

範例程式碼：

[QTMobClick profileSignInWithPUID:@"UserID"];

如果不再需要綁定使用者帳號，可以調用登出介面，調用後，不再發送帳號相關內容。

+ (void)profileSignOff;

範例程式碼：

[QTMobClick profileSignOff];

2.3 裝置ID擷取

介面函數：

+ (NSString *)umidString;

範例程式碼：

NSString *deviceID = [QTConfigure umidString];

3 使用者屬性上傳

1、使用事件編碼固定為"$$_user_profile"的自訂事件上傳，該事件所攜帶的事件屬性會被作為使用者屬性放在使用者表中。

NSDictionary *dict = @{@"sex" : @"girl", @"age" : @"8"};
[QTMobClick event:@"$$_user_profile" attributes:dict];

請注意：使用者屬性上傳一定要在帳號統計調用後

4 渠道屬性

渠道屬性生效後，後續觸發的所有事件都將自動包含這些屬性，並且這些屬性及屬性值存入緩衝，APP進程結束後清除。在分析資料時，可根據此屬性進行查看和篩選。

4.1 H5連結喚起App

1. 喚起App的URL Scheme中攜帶這些渠道屬性，且屬性key務必以“utm_”開頭，因為SDK識別的關鍵字為“utm_”。例如：<URL scheme>?utm_channel=gzh

2. 添加您的 URL Scheme 到專案中，URL Scheme 位於專案設定 target ->選項卡 Info ->URL Types。填入的scheme。在AppDelegate中調用函數[MobClick handleUrl:url]來接收 URL

AppDelegate調用：

- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
 if ([QTMobClick handleUrl:url]) {
 return YES;
 }

 return YES;
}

SceneDelegate調用：

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {

 for (UIOpenURLContext *context in connectionOptions.URLContexts) {
 [QTMobClick handleUrl:context.URL];
 }
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {

 [QTMobClick handleUrl:URLContexts.allObjects.firstObject.URL];
}

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 initWithAppkey:@"您的appkey" channel:@"App Store"];，在分析中可使用“系統屬性-升級渠道”查看。

5 全域屬性

註冊全域屬性後，後續觸發的所有事件都將自動包含這些屬性，並且這些屬性及屬性值儲存在記憶體中，APP進程結束後清除。在分析資料時，可根據此屬性進行查看和篩選。

5.1 註冊全域屬性

/**
 * 設定全域屬性 索引值對 
 * 如果和已經存在的全域屬性key重複，則更新已有值
 * 如果和已經存在的全域屬性key不一致，則插入新的全域屬性
 */
+(void) registerGlobalProperty:(NSDictionary *)property;

樣本：

NSDictionary *firstPropertyDict = @{
     @"a" : @"1",
     @"b" : @"2"
};
[QTMobClick registerGlobalProperty:firstPropertyDict];//當前globalproperty為a:1和b:2
    
NSDictionary *secondPropertyDict = @{
     @"b" : @"3",
     @"c" : @"4"
};
[QTMobClick registerGlobalProperty:secondPropertyDict];//當前globalproperty為a:1、b:3和c:4

5.2 擷取一個全域屬性

/**
 * 擷取一個全域屬性；如果不存在，則返回空。
 */
+(NSString *) getGlobalProperty:(NSString *)propertyName;

5.3 刪除一個全域屬性

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

/**
 *
 * 刪除指定全域屬性
 @param key
 */
+(void) unregisterGlobalProperty:(NSString *)propertyName;

5.4 擷取所有全域屬性

/**
 * 擷取所有全域屬性；如果不存在，則返回空。
 */
+(NSDictionary *)getGlobalProperties;

5.5 清除所有的全域屬性

/**
 * 清空所有全域屬性。
 */
+(void)clearGlobalProperties;

6 頁面瀏覽事件API

SDK提供頁面自動採集和頁面手動採集兩種方式上報頁面瀏覽事件，兩種方式也可以混用。

6.1 頁面自動採集

頁面自動採集是hook系統viewWillAppear和viewWillDisappear，擷取className 實現。SDK預設不開啟頁面自動採集，如果需要開啟，建議在初始化之前調用。

介面函數：

+ (void)setAutoPageEnabled:(BOOL)value;

範例程式碼：

//設定為開啟頁面自動採集
[QTMobClick setAutoPageEnabled:YES];

6.1.1 禁止單個頁面的自動上報

如果全域設定了開啟頁面自動採集，可以通過此介面設定跳過單個頁面的自動採集。建議在viewWillAppear最開始調用，如只不統計當前自動頁面採集，可以將pageName參數設定成nil。

介面函數：

+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

樣本：

#import <QTCommon/UMSpmHybrid.h>

- (void)viewWillAppear:(BOOL)animated
{
  
    [super viewWillAppear:animated];

    //不統計當前class自動頁面採集
    [UMSpmHybrid skipMe:[self class] pageName:nil];
}

6.2 頁面手動採集

介面函數：

/** 自動頁面時間長度統計, 開始記錄某個頁面展示時間長度.
 使用方法：必須配對調用beginLogPageView:和endLogPageView:兩個函數來完成自動統計，若只調用某一個函數不會產生有效資料。
 在該頁面展示時調用beginLogPageView:，當退出該頁面時調用endLogPageView:
 @param pageName 統計的頁面名稱.
 @return void.
 */
+ (void)beginLogPageView:(NSString *)pageName;

/** 自動頁面時間長度統計, 結束記錄某個頁面展示時間長度.
 使用方法：必須配對調用beginLogPageView:和endLogPageView:兩個函數來完成自動統計，若只調用某一個函數不會產生有效資料。
 在該頁面展示時調用beginLogPageView:，當退出該頁面時調用endLogPageView:
 @param pageName 統計的頁面名稱.
 @return void.
 */
+ (void)endLogPageView:(NSString *)pageName;

參數：

注意：

• 必須配對調用beginLogPageView：和endLogPageView：兩個函數來完成自動統計，若只調用某一個函數不會產生有效資料；

• 在該頁面展示時調用beginLogPageView：，當退出該頁面時調用endLogPageView：。

範例程式碼：

在ViewController類的viewWillAppear: 和 viewWillDisappear：中配對調用如下方法：

- (void)viewWillAppear:(BOOL)animated
{
 [super viewWillAppear:animated];
 [QTMobClick beginLogPageView:@"Pagename"]; //("Pagename"為頁面名稱，可自訂)
}

- (void)viewWillDisappear:(BOOL)animated 
{
 [super viewWillDisappear:animated];
 [QTMobClick endLogPageView:@"Pagename"];
}

您也可以根據您自己的業務情境，在viewDidAppear：和viewDidDisappear：等方法中配對調用beginLogPageView：和endLogPageView：兩個函數來完成自動統計。

6.2.1 頁面屬性設定

iOS端頁面屬性設定介面updatePageProperties，支援給當前頁面附加自訂屬性。 介面：

/**
 * @brief 更新頁面業務參數.
 *
 * @param pageName 頁面名稱,如Page_Detail
 * @param pProperties 業務參數,kv對
 *
 * @warning 調用說明:必須在viewWillDisappear之前調用
 *
 * 最佳位置:在viewWillDisappear之前調用即可
 */
+(void) updatePageProperties:(NSString *)pageName properties:(NSDictionary *) pProperties;

參數：

請注意：請在調用beginLogPageView之後設定頁面屬性。

引入標頭檔：

#import <QTCommon/UMSpm.h>

樣本：

[UMSpm updatePageProperties:@"page_home" properties: @{@"page_home_key":@"page_home_val"}];

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

6.2.2 透傳頁面屬性

此外，QuickTracking SDK還提供透傳頁面屬性埋點介面updateNextPageProperties，支援給下一個頁面附加自訂屬性。

/**
 * @brief  更新下一個頁面業務參數.
 *
 * @param properties 傳給下一個頁面業務參數,kv對
 *
 * @warning  調用說明：必須在下一個頁面pageAppear之前調用,否則會攜帶錯誤
 *
 * 最佳位置：必須在下一個頁面pageAppear之前調用
 */
+(void) updateNextPageProperties:(NSDictionary *) properties;

參數：

樣本：

必須在下一個頁面beginLogPageView之前調用。

[UMSpm updateNextPageProperties:@{@"news_next_key":@"news_next_val"}];

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

7 事件埋點

自訂事件可以用於追蹤使用者行為，記錄行為發生的具體細節。

7.1 事件埋點

介面：

+ (void)event:(NSString *)eventCode; 

+ (void)event:(NSString *)eventCode attributes:(NSDictionary *)attributes;

+ (void)event:(NSString *)eventId pageName:(NSString *)pageName attributes:(NSDictionary *)attributes;

參數說明：

事件上傳數量限制：

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

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

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

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

• 單條日誌報文的總長度限制：2MB

樣本1：

統計應用中”轉寄”事件發生的次數，那麼在轉寄的函數裡調用：

[QTMobClick event:@"Forward"];

樣本2：

統計應用中“購買”事件發生的次數，以及購買的商品類型及數量，那麼在購買的函數裡調用：

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"};
[QTMobClick event:@"purchase" attributes:dict];

樣本3:

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"};
[QTMobClick event:@"purchase" pageName:@"ViewController" attributes:dict];

8 全埋點（自動埋點）

8.1 全埋點適用範圍

SDK適用於iOS 8.0及以上作業系統。

8.2 全埋點介面說明

8.2.1 自動頁面採集介面

/** 設定是否自動採集頁面, 預設NO(不自動採集).
 @param value 設定為YES, QT SDK 會自動採集頁面資訊
 */
+ (void)setAutoPageEnabled:(BOOL)value;

樣本：

 [QTMobClick setAutoPageEnabled:YES];
 //設定網域名稱
 [QTConfigure setCustomDomain:@"您的收數網域名稱" standbyDomain:nil]; 
 //初始化appkey
 [QTConfigure initWithAppkey:@"您應用的appKey" channel:@"App Store"];

關閉某個頁面的自動頁面採集

/**
 * @brief                   跳過當前頁面統計.
 *
 * @param     PageObject    容器物件（自動擷取頁面時使用，預設手動可填nil）
 * @param     pageName      頁面名稱（手動設定頁面時使用，當設定自動擷取頁面時可填nil）
 * @warning                 建議在設定頁面之前調用此介面，調用後設定的native頁面將不發送資料
 *                          
 */
+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

樣本：

[UMSpmHybrid skipMe:self pageName:nil];

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

建議在初始化之前調用，預設是關閉

/** 設定是否自動採集點擊事件, 預設NO(不自動採集)
 @param value 設定為YES, QT SDK 會將自動採集點擊事件
 */
+ (void)setAutoEventEnabled:(BOOL)value;

樣本：

 [QTMobClick setAutoEventEnabled:YES];
 //設定網域名稱
 [QTConfigure setCustomDomain:@"您的收數網域名稱" standbyDomain:nil]; 
 //初始化appkey
 [QTConfigure initWithAppkey:@"您應用的appKey" channel:@"App Store"];

支援的控制項：

忽略某個容器的點擊事件

/**
 * @abstract
 * 忽略某一頁面的點擊
 *
 * @param PageObject 對應容器
 */
+(void)ignorePageView:(id)PageObject;

例：

// 該方法支援多次調用，對合集進行忽略    
[QTAutoTrack ignorePageView:self];

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

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

/**
 * @abstract
 * 忽略某一類型的點擊
 *
 * @param aClass View 對應的 Class
 */
+(void)ignoreViewType:(Class)aclass;

樣本：

// 該方法支援多次調用，對合集進行忽略    
[QTAutoTrack ignoreViewType:[UIButton class]];    
[QTAutoTrack ignoreViewType:[UISwitch class]];

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

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

button.UMAnalyticsIgnoreView=YES;

8.2.3 版面設定自訂資訊

版面設定自訂編碼

通過實現 -(NSString *)getUMPageName 方法，返回一個自訂編碼

-(NSString *)getUMPageName
{
   return @"testPageCode";
}

版面設定自訂屬性

通過實現 -(NSDictionary *)getUMPageProperties 方法，給版面設定自訂屬性

-(NSDictionary *)getUMPageProperties
{
   return @{@"key1":@"val1",@"key2":@"val2"};
}

版面設定來源（page_referrer）資訊

通過實現 -(NSString *) getUMScreenUrl 方法，返回一個自訂來源資訊

- (NSString *)getUMScreenUrl {
    return @"um//um/page";
}

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

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

button.UMAnalyticsViewProperties=@{@"key11":@"val11"};

控制項設定Event Code

通過該方法，可以對特定控制項設定事件編碼

button.UMAnalyticsEventCode=@"abcd123";