Quick Tracking：埋點API

1 如何查看埋點方案

在進行埋點前，需要確定在哪裡埋點、埋哪些點等，即需要梳理清楚明確的埋點需求。在Quick Tracking平台中將明確的埋點需求稱為埋點方案，並為埋點方案設計了規範模板。如下：

在埋點方案中，明確的所需埋點內容有：

1、事件主體：指“誰”觸發了這個事件，分為裝置ID和帳號ID，上報的事件務必具備其中之一。

• 裝置ID：macOS裝置預設裝置ID為應用層級唯一的裝置ID，由Quick Tracking SDK自動產生或者通過調用setCustomDeviceId介面設定。

• 帳號ID：用戶端使用者登入體系的帳號標識，當一個使用者在不同的裝置進行登入時，裝置ID會發生變化，但是帳號ID不會發生變化。例如一個使用者分別使用兩台電腦登入。

2、使用者屬性：針對帳號ID的屬性，例如帳號ID為“testdemo@111”的使用者，“生日”為“1999-02-13”，“會員等級”為“鉑金”等。“生日”和“會員”等級就為使用者屬性。

3、全域屬性：在全域設定一次後，每一個事件都會攜帶的屬性

4、頁面瀏覽事件：頁面載入時上報的事件（埋點方案中頁面編碼和事件編碼相等的事件，也是標記為藍色的事件）

5、點擊、曝光、自訂事件：用戶端使用者與用戶端發生任意互動時上報的事件。

埋點須知

• 傳入參數大小限制：

2. 應用預製事件

2.1 手動觸發應用啟動事件

介面函數：

// 手動觸發應用啟動事件
-(void)trackAppStart:(NSDictionary *_Nullable)properties;

參數：

樣本：

NSDictionary *appStartProperties = @{
    @"appStartTest": @"appStartTest",
    @"times": @1024,
    @"subContents": @[@"test1", @"test2", @"test3"]
};
[[QuickTrackingSDK sharedInstance] trackAppStart:appStartProperties];

2.2 手動觸發應用退出事件

介面函數：

// 手動觸發應用退出事件
-(void)trackAppEnd:(NSDictionary *_Nullable)properties;

參數：

樣本：

NSDictionary *appEndProperties = @{
    @"appEndTest": @"appEndTest"
};
[[QuickTrackingSDK sharedInstance] trackAppEnd:appEndProperties];

3 裝置ID

SDK支援自訂裝置ID，如果要使用自訂裝置ID，需要設定setCustomDeviceId 介面為有效值（非空），預設值為裝置唯一標識加密後的內容。

3.1 設定自訂裝置ID

介面函數：

// 設定自訂裝置ID
-(void)setCustomDeviceId:(NSString *_Nonnull)customDeviceID;

參數：

樣本：

[[QuickTrackingSDK sharedInstance] setCustomDeviceId:@"your_deviceId"];

3.2 讀取裝置ID

介面函數：

// 讀取裝置ID
-(NSString *_Nullable)getDeviceID;

樣本：

NSString *deviceID = [[QuickTrackingSDK sharedInstance] getDeviceID];

使用注意：

該方法依賴於SDK初始化完成，可能返回空值

4 帳號ID

4.1 使用者登入

Quick Tracking SDK在統計使用者時以裝置為標準，如果需要統計自身的帳號，請使用以下方法。

介面函數：

// 登入
- (void)onProfileSignIn:(NSString *_Nonnull)userId;

參數：

樣本：

[[QuickTrackingSDK sharedInstance] onProfileSignIn:@"your_userId"];

4.2 使用者登出

如果不再需要綁定使用者帳號，可以調用SDK提供的使用者登出方法，調用後SDK不再發送使用者帳號相關內容。

介面函數：

// 登出
- (void)onProfieSignOff;

樣本：

[[QuickTrackingSDK sharedInstance] onProfieSignOff];

5 使用者屬性上傳

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

介面函數：

// 使用者屬性上傳
- (void)uploadUserProfile:(NSDictionary *_Nullable)properties;

參數：

樣本：

NSDictionary *userProfile = @{
  @"name": @"your_name",
  @"email": @"example@example.com"
};
[[QuickTrackingSDK sharedInstance] uploadUserProfile:userProfile];

使用注意：

SDK不會緩衝使用者屬性，上報使用者屬性需先調用使用者帳號設定APIonProfileSignIn才能保證資料準確性。

6. 全域屬性

6.1 註冊全域屬性

介面函數：

// 設定全域屬性
-(void)registerGlobalProperties:(NSDictionary * _Nonnull)properties;

參數：

樣本：

[[QuickTrackingSDK sharedInstance] registerGlobalProperties:@{
    @"content": @"測試",
    @"times": @1024,
    @"subContents": @[@"abc", @"def", @"ghi"]
}];

使用注意：

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

6.2 刪除一個全域屬性

介面函數：

// 根據Key刪除全域屬性
-(void)unregisterGlobalProperty:(NSString *_Nonnull)propertyName;

參數：

樣本：

[[QuickTrackingSDK sharedInstance] unregisterGlobalProperty:@"your_key"];

6.3 根據key擷取單個全域屬性

介面函數：

// 根據Key擷取全域屬性
-(id _Nullable)getGlobalProperty:(NSString *_Nonnull)propertyName;

參數：

傳回值：

樣本：

id value = [[QuickTrackingSDK sharedInstance] getGlobalProperty:@"your_key"];

6.4 擷取全部全域屬性

介面函數：

// 擷取全部全域屬性
-(NSDictionary *_Nullable)getGlobalProperties;

傳回值：

樣本：

NSDictionary *globalProperties = [[QuickTrackingSDK sharedInstance] getGlobalProperties];

6.5 清空全部全域屬性

介面函數：

// 清空全部全域屬性
-(void)clearGlobalProperties;

樣本：

[[QuickTrackingSDK sharedInstance] clearGlobalProperties];

7. 頁面瀏覽事件

使用前，請先到QuickTracking管理背景資料擷取-->埋點管理-->事件管理模組，建立相應的頁面事件，然後在工程中傳入相應的頁面編碼（page_name）。

7.1 頁面啟動

介面函數：

// 統計頁面進入行為
+(void)onPageStart:(id _Nonnull)pageContext page_name:(NSString * _Nonnull)page_name options:(NSDictionary *_Nullable)options;

參數：

樣本：

NSDictionary *pageOptions = @{
    @"url": @"your_url",
    @"page_title": @"your_page_title"
};
[QuickTrackingSDK onPageStart:self page_name:@"your_page_name" options:pageOptions];

7.2 頁面離開

介面函數：

// 統計頁面離開行為
+(void)onPageEnd:(id _Nonnull)pageContext page_name:(NSString * _Nonnull)page_name;

參數：

樣本：

[QuickTrackingSDK onPageEnd:self page_name:@"your_page_name"];

7.3 設定頁面事件屬性

介面函數：

// 設定頁面事件屬性
+(void)updatePageProperties:(id _Nonnull)pageContext page_name:(NSString *_Nonnull)page_name properties:(NSDictionary *_Nonnull)properties;

參數：

樣本：

NSDictionary *pageProperties = @{
    @"page_type": @"main",
    @"user_role": @"admin"
};
[QuickTrackingSDK updatePageProperties:self page_name:@"your_name" properties:pageProperties];

8. 事件埋點

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

使用前，請先到QuickTracking管理背景資料擷取-->埋點管理-->事件管理模組，建立相應的自訂事件，然後在工程中傳入相應的事件編碼。

介面函數：

// 埋時間點事件
- (void)event:(NSString *_Nonnull)eventCode;
// 埋時間點事件帶事件屬性
- (void)event:(NSString *_Nonnull)eventCode properties:(NSDictionary *_Nullable)properties;
// 埋時間點事件帶頁面編碼
- (void)event:(NSString *_Nonnull)eventCode page_name:(NSString *_Nonnull)page_name;
// 埋時間點事件帶頁面編碼和事件屬性
- (void)event:(NSString *_Nonnull)eventCode page_name:(NSString *_Nonnull)page_name properties:(NSDictionary *_Nullable)properties;

參數：

樣本：

// 埋時間點事件
NSString *eventCodeSimple = @"your_event_code";
[[QuickTrackingSDK sharedInstance] event:eventCodeSimple];

// 埋時間點事件帶頁面屬性
NSString *eventCodeWithProperties = @"your_event_code";
NSDictionary *yourProperties = @{
    @"item_name": @"your_item_name",
    @"item_price": @20
};
[[QuickTrackingSDK sharedInstance] event:eventCodeWithProperties properties:yourProperties];

// 埋時間點事件帶頁面編碼
NSString *eventCodeWithPage = @"your_event_code";
NSString *page_name = @"homepage";
[[QuickTrackingSDK sharedInstance] event:eventCodeWithPage page_name:page_name];

// 埋時間點事件帶頁面編碼和事件屬性
NSString *eventCodeWithPageWithProperties = @"your_event_code";
NSString *page_name = @"settings_page";
NSDictionary *properties = @{
    @"button_name": @"save_settings",
    @"user_id": @"test"
};
[[QuickTrackingSDK sharedInstance] event:eventCodeWithPageWithProperties page_name:page_name properties:properties];

9. 其他

9.1 禁用SDK

調用後，SDK將不採集事件，不發送網路請求。

介面函數：

// 禁用SDK
+(void)disableSDK;

樣本：

[QuickTrackingSDK disableSDK];

9.2 開啟SDK

如果之前SDK是禁止狀態，調用後將恢複資料擷取功能。

介面函數：

// 開啟SDK
+(void)enableSDK;

樣本：

[QuickTrackingSDK enableSDK];