1. 原始碼整合 macOS SDK

GitHub 下載 SDK 原始碼
將 SDK 原始碼拖入 App 專案中，並選中 Copy items if needed；
專案設定 "Build Phase" -> "Link Binary With Libraries" 中增加依賴函式庫：libicucore、libsqlite3 和 libz。

2. 初始化神策分析 macOS SDK

2.1. 取得數據接收網址

數據接收網址是 SDK 上報數據的目標網址，需要使用管理員帳號進行取得。

2.2. 初始化 SDK 及基本設定

注意：需要在程式入口 Main Thread 初始化 SDK，否則可能會遺失部分事件數據。

初始化 SDK

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
     // 初始化設定，必選
    [SensorsAnalyticsSDK sharedInstanceWithServerURL:<#數據接收網址#> andDebugMode:SensorsAnalyticsDebugOff];
     
    /* 注意：只有初始化 SDK 後，才可以呼叫 [SensorsAnalyticsSDK sharedInstance] 進行其他操作，如：註冊公共屬性、track 啟動事件等 */
 
    // 開啟 log 採集，建議只在開發階段除錯開啟，非必選
    [[SensorsAnalyticsSDK sharedInstance] enableLog:YES];
}

CODE

3. 使用神策分析 macOS SDK

3.1. 程式碼埋點追蹤事件

神策分析 SDK 成功初始化後，可以透過 track: 和 track:withProperties: 方法追蹤用戶行為事件，並為事件增加自定義屬性。以電商產品為例，可以這樣追蹤一次購物行為

代码埋点

UInt64 productId = 123456;
NSString *productCatalog = @"Laptop Computer";
BOOL isAddedToFavorites = NO;
 
[[SensorsAnalyticsSDK sharedInstance] track:@"ViewProduct"
                             withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:productId],
                                              @"ProductCatalog" : productCatalog,
                                              @"IsAddedToFav" : isAddedToFavorites ? @YES : @NO}];

CODE

注意：

事件名和屬性名需要時合法變數名，且不能以 $ 開頭；
屬性名大小寫敏感，並且不同事件會共用同名屬性。即若 foo 事件含有 aaa 屬性，則後續所有事件不能使用與 aaa 僅大小寫不同的屬性(如 aAa、aaA)；
事件名和屬性其他限制，具體請參考數據格式；
Mac SDK 暫時只支援程式碼埋點，不支援全埋點。

3.2. 設定事件公共屬性

如果所有事件中都具有某個屬性值，則可以將該屬性作為公共屬性，一個屬性註冊成公共屬性後，SDK 自動會將該屬性拼接到所有的埋點事件中，省去了每次都手動增加困擾。

3.2.1. 靜態公共屬性

可以透過 registerSuperProperties: 註冊事件公共屬性，例如將應用名稱作為事件的公共屬性：

註冊公共屬性

[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];

CODE

成功設定事件公共屬性後，再透過 track: 追蹤事件時，事件公共屬性會被增加進每個事件中，例如：

// 記錄收藏商品事件
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
                             withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:123456]}];

CODE

在設定事件公共屬性後，實際傳送的事件中會被加入 AppName 屬性，等同於：

// 記錄收藏商品事件
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
                             withProperties:@{
                                                 @"ProductID" : [NSNumber numberWithUnsignedLong:123456],
                                                 @"AppName" : @"<#YOUR APP NAME#>"
                                                 }];

CODE

3.2.2. 動態公共屬性

透過 registerDynamicSuperProperties 方法設定動態公共屬性，設定之後，事件觸發時候 SDK 會自動即時取得 registerDynamicSuperProperties 中的屬性增加到觸發的事件中

動態公共屬性

// 註冊動態公共屬性
[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary * _Nonnull{
	__block NSApplicationOcclusionState appState;
    if (NSThread.isMainThread) {
        appState = NSApplication.sharedApplication.occlusionState;
    }else {
        dispatch_sync(dispatch_get_main_queue(), ^{
            appState = NSApplication.sharedApplication.occlusionState;
        });
    }
    return @{@"__APPState__":@(appState)};
}];

CODE

注意：動態公共屬性和靜態公共屬性的作用相同，註冊之後的所有事件都會包含這個屬性。

3.3. 用戶標識

3.3.1. ID 與用戶標識

無論是自定義程式碼埋點事件還是全埋點自動採集的事件，神策中每個事件都會關聯到一個 ID 上，用於標識該事件所對應的用戶或裝置資訊，我們稱之為 distinct_id。預設情況下，用戶登入前，distinct_id 是 SDK 根據裝置產生的一個匿名 ID，預設使用 mac 序列號碼，如果取得失敗，則使用 UUID；用戶登入後，開發人員呼叫 login: 將用戶登入ID 傳給 SDK，後續該裝置上所有事件的 distinct_id 就會變成用戶所對應的登入 ID。

3.3.2. ID 綁定和用戶關聯

用戶登入前，distinct_id 為 匿名 ID；用戶登入後，distinct_id 為 登入ID。為了將用戶登入前後的事件序列串聯起來，神策分析採用了用戶關聯機制：呼叫 login: 介面時，後台會嘗試將匿名ID 和登入ID 關聯起來，並產生一個新的 user_id，並在神策分析中使用 user_id 作為標識用戶和計算指標的依據。 SDK 內部做了邏輯處理，多次呼叫 login: 傳入相同的 登入 ID 時，SDK 會進行忽略。為了保證用戶關聯的覆蓋率，在如下時機時均需要呼叫 login: 進行用戶關聯：

用戶註冊或登入成功時，需呼叫 login: 進行用戶關聯
App 啟動時，若當前為已登入用戶，需呼叫 login: 傳入登入 ID 進行用戶關聯

[[SensorsAnalyticsSDK sharedInstance] login:<#業務系統的登入 ID#>];

CODE

4. macOS SDK 中預設屬性

欄位名稱	型別	顯示名稱	說明
$app_version	字串	應用程式版本	應用程式的版本
$lib	字串	SDK類型	例如 macOS
$lib_version	字串	SDK版本
$manufacturer	字串	裝置製造商	例如 Apple
$model	字串	裝置型號	例如 MacBookPro14,1
$os	字串	作業系統	例如 macOS
$os_version	字串	作業系統版本	例如 10.15.2
$screen_height	數值	螢幕高度	例如 1440
$screen_width	數值	螢幕寬度	例如 2560
$wifi	BOOL	是否wifi
$network_type	字串	網路類型	例如 WIFI
$is_first_day	BOOL	是否首日連接
$device_id	字串	裝置ID	預設取得序列號碼，若取不到則使用 UUID