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 渠道屬性

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