1. 開啟螢幕方向的自動採集

1.10.1+ 版本 SDK 支援自動採集螢幕方向，可以在初始化 SDK 後呼叫 - enableTrackScreenOrientation: 進行開啟，開啟後的螢幕方向資訊記錄在事件的 $screen_orientation 屬性中：

[[SensorsAnalyticsSDK sharedInstance] enableTrackScreenOrientation:YES];

CODE

2. 開啟位置資訊自動採集

1.10.1+ 版本 SDK 支援自動採集 GPS 資訊，可以在初始化 SDK 後呼叫 - enableTrackGPSLocation: 方法進行開啟，開啟後的經緯度資訊會乘 10⁶ 後記錄在事件的 $longitude、$latitude 屬性中：

// CoreLocation 採集 GPS 資訊
[[SensorsAnalyticsSDK sharedInstance] enableTrackGPSLocation:YES];

CODE

2.1.13+ 版本 SDK 預設不整合 GPS 模組。

如果使用 CocoaPods 整合 SDK，請修改 Podfile 檔案，增加 Location 模組的 subspec，例如：pod 'SensorsAnalyticsSDK', :subspecs => ['Location']。
如果使用原始碼整合神策分析 iOS SDK，請檢查是否包含名為 SALocationManager 的檔案

3. 統計事件時長

1.10.6+ 版本 SDK 支援程式碼埋點來統計事件的時長，只需要在行為開啟時呼叫 - trackTimerStart:，在行為結束時呼叫 - trackTimerEnd:withProperties: 介面，SDK 會自動計算時長，並以秒(浮點數)為單位存在事件的 $event_duration 屬性中：

// 開始播放影片時
[[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"WatchVideo"];

// 暫停播放時
[[SensorsAnalyticsSDK sharedInstance] trackTimerPause:@"WatchVideo"];

// 恢復播放時
[[SensorsAnalyticsSDK sharedInstance] trackTimerResume:@"WatchVideo"];

// 停止或者結束播放時
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:@"WatchVideo" withProperties:@{@"VideoType": @"film"}];

CODE

3.1. 同名事件交叉的時長統計

預設情況下，時長的統計以事件名作為標識，相同的事件名會自動匹配 start-end，如果兩個同名事件在時間上有交叉部分，會造成錯誤匹配。為了解決此問題，1.11.17+ 版本 SDK 支援同名事件交叉的時長統計，開發者需要保存- trackTimerStart: 的回傳值，以便後續針對性地進行暫停、恢復或停止：

// 開始第一個事件計時
NSString *timer1 = [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"testTimer"];
 
// 開始第二個事件計時
NSString *timer2 = [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"testTimer"];
 
//如果需要暫停第一個事件計時
[[SensorsAnalyticsSDK sharedInstance] trackTimerPause:timer1];
 
//如果需要恢復第一個事件計時
[[SensorsAnalyticsSDK sharedInstance] trackTimerResume:timer1];
 
// 結束第一個事件計時
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:timer1];
 
// 結束第二個事件計時
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:timer2];

CODE

只有呼叫 - trackTimerEnd: 時，SDK 才會真正記錄事件
多次呼叫 - trackTimerStart:，以最後一次呼叫作為計時起點
預設情况下，統計的時長不包括用戶 App 在後台的時長

4. 取得預設屬性

前端 SDK 在記錄事件時會增加裝置相關的預設屬性，為了確保前後端事件屬性的一致性，某些情況下可能需要在前端取得 SDK 預設屬性，1.8.19+ 版本 SDK 可以使用 - getPresetProperties 方法取得事件預設屬性，然後透過業務介面傳到伺服器端，由伺服器端增加到事件屬性中：

// 取得事件預設屬性
[[SensorsAnalyticsSDK sharedInstance] getPresetProperties];

CODE

5. 事件動態公共屬性

動態公共屬性和公共屬性的區別是：前者適合標記年齡，後者適合標記性別。

對於一些值會變化的公共屬性，如當前遊戲等級、最新金幣餘額等，1.10.8+ 版本 SDK 提供了- registerDynamicSuperProperties: 介面來設定動態公共屬性:

[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary<NSString *,id> * _Nonnull{
	return @{@"level": <#當前遊戲等級#>,
			 @"balance": <#最新金幣餘額#>};
}];

CODE

事件屬性的優先級為：track 事件時傳入的屬性 > 動態公共屬性 > 公共屬性> 預設屬性
動態公共屬性的限制和事件屬性相同，詳情參考數據格式

6. 取得用戶 ID

神策中每個事件都會關聯到一個 ID 上，用於標識該事件所對應的用戶或裝置資訊，我們稱之為 distinct_id，您也可以透過 - distinctId 介面取得該 ID：

// 取得事件的 ID 標識
[[SensorsAnalyticsSDK sharedInstance] distinctId];

CODE

預設情况下，用戶登入前，distinct_id 是 SDK 根據裝置產生的一個匿名 ID，一般為IDFA、IDFV 或 UUID。

您也可以透過 - anonymousId 介面取得當前的匿名 ID：

// 取得匿名 ID
[[SensorsAnalyticsSDK sharedInstance] anonymousId];

CODE

7. 用戶屬性設定

7.1. 保留初次屬性

對於需要確保只有首次設定時有效的屬性，如用戶首次加值金額、首次設定的暱稱等，可以使用 - setOnce: 或 - setOnce:to: 介面進行記錄。與 - set: 方法不同的是，如果被設定的用戶屬性已存在，則這條記錄會被忽略而不會覆蓋已有數據，如果屬性不存在則會自動建立：

// 設定用戶 AdSource 管道為 "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"App Store"];

// 再次設定用戶 AdSource 管道，設定無效，AdSource 屬性值仍然是 "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"Email"];

CODE

7.2. 數值屬性累加

針對一些數值型屬性，如消費總額、用戶積分等屬性，我們可以使用 - increment: 或 - increment:by: 對原值進行累加，神策會自動計算並保存累加之後的值：

// 將用戶遊戲次數屬性增加一次
// increment:by: 對一個屬性進行累加
[[SensorsAnalyticsSDK sharedInstance] increment:@"GamePlayed" by:[NSNumber numberWithInt:1]];

// 增加用戶付費次數和積分
// increment: 對一個或多個屬性進行累加
[[SensorsAnalyticsSDK sharedInstance] increment:@{@"UserPaid" : [NSNumber numberWithInt:1],
												  @"PointEarned" : [NSNumber numberWithFloat:12.5]}];

CODE

7.3. 列表屬性追加

對於列表類型用戶屬性，如用戶喜愛的電影、用戶評價過的餐廳等屬性，可以呼叫 - append:by: 介面進行追加一些新值：

// 設定用戶觀影列表屬性，設定後屬性 "Movies" 為: ["Sicario", @"Love Letter"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Sicario", @"Love Letter"]]];

// 再次設定該屬性，屬性 "Movies" 為: ["Sicario", @"Love Letter", @"Dead Poets Society"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Love Letter", @"Dead Poets Society"]]];

CODE

列表型屬性中的元素必須為 NSString 型別，且元素的值會自動去重。關於列表型限制請見數據格式。

7.4. 屬性取消

如果需要取消已設定的某個用戶屬性，可以呼叫- unset: 進行取消：

// 取消設定 gender 屬性
[[SensorsAnalyticsSDK sharedInstance] unset:@"Gender"];

CODE

8. 開啟點擊點擊分析功能

版本要求

神策分析 1.13+

此功能依賴於全埋點中點擊事件採集的開啟
使用此功能前，確保您的 App 中設定了當前專案的 Scheme，詳細操作可參考設定 Scheme

1.9.3+ 版本 SDK 支援 App 點擊分析功能，SDK 初始化前將 SAConfigOptions 實體 enableHeatMap 屬性設定為 YES 即可開啟 SDK 的點擊分析功能：

// 開啟點擊分析
options.enableHeatMap = YES;

CODE

開啟 App 點擊分析後，該功能預設對所有頁面上的點擊生效，如果您只是想部分頁面進行熱力圖，可以透過 - addHeatMapViewControllers: 進行設定增加：

[[SensorsAnalyticsSDK sharedInstance] addHeatMapViewControllers:@"HomeViewController", "DiscoverViewController"];

CODE

9. 埋點數據的加密功能

為了加強埋點數據的安全性，神策分析支援對埋點數據進行加密，並以密文的形式對數據進行儲存和傳送。

本功能需要伺服器端的配合，可以聯繫神策客戶成功/專案經理協助開通伺服器端解密功能。

9.1. SDK 端開啟加密

對於 2.1.0+ 版本 SDK，初始化前將 SAConfigOptions 實例 enableEncrypt 屬性設定為 YES 即可開啟 SDK 的加密功能：

// 開啟 SDK 加密功能
options.enableEncrypt = YES;

CODE

9.2. 加密私鑰的驗證

使用此功能前，確保您的 App 中設定了當前專案的 Scheme，詳細操作可參考設定 Scheme

在神策分析平台中，進入私鑰管理功能，進入路徑：「更多」 → 「基本設定」 → 「數據接入」 → 「私鑰管理」

點擊「私鑰管理」按鈕進入私鑰管理頁面

點擊對應私鑰的 QR Code 圖示，用瀏覽器掃描 QR Code 打開 App 進行私鑰驗證。

驗證一致，則 App 端提示 "私鑰驗證通過，所選私鑰與 App 端私鑰相同"
驗證不一致：則 App 端提示 “私鑰驗證不通過，所選私鑰與 App 端私鑰不相同。所選私鑰版本:v1，App 端私鑰版本:v2”
如果本地私鑰為空：則 App 端提示 “私鑰驗證不通過，App 端私鑰為空”
如果掃描私鑰為空：則 App 端提示 “私鑰驗證不通過，所選私鑰無效”

10. 即時查看當前裝置事件數據

使用此功能前，確保您的 App 中設定了當前專案的 Scheme，詳細操作可參考設定 Scheme
除錯模式只對本次啟動有效，退出 App 自動失效

電腦端打開神策分析頁面，埋點 -> 匯入即時查看 -> Debug 數據 -> 設定裝置除錯模式，使用相機或其他 QR Code 工具掃描螢幕 QR Code。

掃描打開 App 後，會跳出提示，選擇想要切換的除錯模式：
開啟除錯模式(匯入數據)：打開除錯模式，校驗數據，並將數據匯入到神策分析中。
開啟除錯模式(不匯入數據)：打開除錯模式，僅校驗數據，但不進行數據匯入，數據最終不會進入到資料庫。

11. 部分頁面開啟可視化全埋點

可視化全埋點開啟後，預設對 App 內全部頁面生效，如果只需要部分頁面開啟可視化全埋點，可以在 SDK 初始化後使用- addVisualizedAutoTrackViewControllers: 進行增加：

// 只開啟 MainController 的可視化全埋點
[[SensorsAnalyticsSDK sharedInstance] addVisualizedAutoTrackViewControllers:[NSArray arrayWithObject:@"MainController"]];

CODE

12. 自定義上報策略

為了減少效能和電量損耗，Android SDK 和 iOS SDK 中事件觸發後不會立即上報，而是先將事件快取在本地，然後定時、批量進行上報。

12.1. 上報條件

iOS SDK 每次觸發事件時會檢查如下條件，以判斷是否向伺服器上傳數據:
1. 當前網路是否符合 flushNetworkPolicy (預設 3G、4G、5G、WiFi)
2. 與上次傳送的時間間隔是否大於 flushInterval (預設 15 秒)
3. 本地快取的事件條目數是否大於 flushBulkSize (預設 100 條)

只有1、2 或1、3 滿足時，SDK 才會進行傳送數據。以上參數支援自定義，可以透過修改相應參數值來達到控制事件上報的頻率：

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:@"<#數據接收網址#>" launchOptions:launchOptions];

// 設定觸發間隔，預設 15 * 1000 毫秒
options.flushInterval = 10 * 1000;

// 設定觸發條數，預設 100 條
options.flushBulkSize = 50;

[SensorsAnalyticsSDK startWithConfigOptions:options];

// 設定上報網路策略，預設 3G、4G、WiFi，注意需要初始化 SDK 之後設定
[[SensorsAnalyticsSDK sharedInstance] setFlushNetworkPolicy:SensorsAnalyticsNetworkTypeALL];

CODE

12.2. 強制上報

如果特定事件需要立即上報，可以在事件觸發後呼叫 - flush 介面強制進行上報：

// 立即上報
[[SensorsAnalyticsSDK sharedInstance] flush];

CODE

12.3. 快取上限

如果事件觸發後一直不滿足上報條件，本地快取的數據條數會越來越多，當快取事件量達到 maxCacheSize 時，每次再觸新的事件，SDK 會依次丟掉舊數據，保留最新的數據。 maxCacheSize 預設為 10000 條，支援客戶自定義：

// 設定最大快取量，預設 10000 條
options.maxCacheSize = 20000;

CODE

13. 清空本地快取事件

為了因應 GDPR 要求，1.10.8+ 版本 SDK 增加了 - deleteAll 方法用於清空本地快取的所有事件：

[[SensorsAnalyticsSDK sharedInstance] deleteAll];

CODE

14. 本地憑證校驗

1.11.5+ 版本 SDK 傳送數據時支援本地憑證校驗，可按照如下步骤進行設定：

伺服器產生 SSL 憑證，如果不是 .cer 格式，需要使用 OpenSSL 進行格式轉換:

openssl x509 -in 你的憑證.crt -out 你的憑證.cer -outform der

CODE

將憑證施入專案中，選取相應 Target 並選擇 Copy items if needed。
設定神策 SDK 憑證校驗方式：

/*
設定憑證校驗方式，預設為 SASSLPinningModeNone
*/
SASecurityPolicy *securityPolicy = [SASecurityPolicy policyWithPinningMode:SASSLPinningModePublicKey];

/*
是否允許無效憑證（自建憑證），預設為 NO ，
如果是需要驗證自建憑證，需要設定為 YES 。
*/
securityPolicy.allowInvalidCertificates = YES;

/*
是否需要驗證網域名，預設為 YES ，
如憑證的網域名與請求的網域名不一致，需把該項設定為 NO 。
*/
securityPolicy.validatesDomainName = NO;

/*
設定本地憑證路徑
*/
securityPolicy.pinnedCertificates = [SASecurityPolicy certificatesInBundle:[NSBundle mainBundle]];

/*
設定憑證策略
*/
[[SensorsAnalyticsSDK sharedInstance] setSecurityPolicy:securityPolicy];

CODE

其中，SSLPinningMode 有以下三種模式：

· SASSLPinningModeNone：預設模式，客戶端無條件信任伺服器端回傳憑證，不做 App 本地憑證校驗
· SASSLPinningModePublicKey：只驗證憑證中公鑰，不驗證憑證的有效期等資訊
· SASSLPinningModeCertificate：校驗本地憑證的所有資訊

SASSLPinningModeCertificate 模式會校驗憑證有效期等資訊，如果不能確保用戶 App 憑證始終處於未過期狀態，建議使用SASSLPinningModePublicKey 模式。

15. 追蹤並進行管道匹配和回傳

從 iOS v2.0.9 開始 SDK 支援 track 方法觸發的自定義事件增加管道屬性的邏輯，初始化前將 SAConfigOptins 實體 enableAutoAddChannelCallbackEvent 屬性設置為 YES 即可支援自定義事件增加管道屬性。

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:launchOptions];
// 自定義埋點事件中自動增加管道匹配資訊
options.enableAutoAddChannelCallbackEvent = YES;
[SensorsAnalyticsSDK startWithConfigOptions:options];

CODE

當次安裝、首次觸發回傳事件，記錄事件並進行管道匹配和回傳。
當次安裝、再次觸發回傳事件，記錄事件，但不進行管道匹配和回傳。
移除重裝、首次觸發回傳事件，記錄事件並進行管道匹配和回傳。

p.s. 上述規則適用於同名事件，不同事件之間不相互影響。

16. App 被動啟動($AppStartPassively) 事件說明

對於 iOS 裝置，除了用戶主動啟動 App。裝置中某些條件觸發時(如收到通知、用戶位置資訊變化等)，系統可能會喚醒App，使程式在後台運作，當程式在後台啟動並運作時，SDK 觸發 $AppStartPassively(App 被動啟動)事件。
關於 iOS 裝置後台啟動和運做的更多資訊，可參考 Apple 文件 About the Background Execution Sequence。

17. 開啟 Crash 資訊的自動採集

1.8.12+ 版本 SDK 支援自動採集 Crash 資訊，可以在初始化 SDK 時透過設定 SAConfigOptions 進行開啟。開啟後的 Crash 堆疊資訊會記錄在 AppCrashed 事件的 app_crashed_reason 屬性中：

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:launchOptions];
options.enableTrackAppCrash = YES;
[SensorsAnalyticsSDK startWithConfigOptions:options];

CODE

18. 入庫前修改事件資訊

1.11.16+ 版本 SDK 支援在事件入庫前進行修改屬性、刪除事件，可以使用 - trackEventCallback: 中 block 參數進行設定：

block 中 eventName 參數為當前事件名。
block 中 properties 參數為當前事件屬性，該參數為 NSMutableDictionary 類型，可直接修改此參數達到修改事件屬性的目的。
block 回傳值標誌事件是否需要繼續入庫和上報： YES 事件會繼續入庫，NO 將刪除此條事件。

警告

嚴禁在 block 中呼叫- track: 、- trackInstallation:、 - login: 等觸發事件的介面，會因循環呼叫而導致應用崩潰
block 回傳 NO 時 SDK 將刪除此條事件，所以請確保判斷邏輯，以免造成誤刪除事件

[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName,
                                                               NSMutableDictionary<NSString *,id> *properties) {
    // BuyProduct 事件不進行入庫
    if ([eventName isEqualToString:@"BuyProduct"]) {
        return NO;
    }
    
    // 刪除 ViewProduct 事件 category 屬性
    if ([eventName isEqualToString:@"ViewProduct"]) {
        [properties removeObjectForKey:@"category"];
    }
        
    return YES;
}];

CODE

19. 自定義匿名 ID

預設情况下，SDK 會產生匿名 ID 並可以確保該 ID 的唯一性，如果需要替換神策預設分配的匿名 ID ，可以在初始化 SDK 之後立即呼叫 - identify: 方法進行替換。
程式碼示例：

[[SensorsAnalyticsSDK sharedInstance] identify:<#自定義匿名 ID#>];

CODE

20. 預編譯巨集設定 SDK 特性

為了滿足客戶特殊場景下的需求，SDK 支援透過預編譯巨集來選擇性編譯某些功能。透過 CocoaPods 整合時，可以透過增加 subspecs 進行設定；其他整合方式，可以在專案中設定 Preprocessor Macros。

功能	subspec (CocoaPods 方式)	Preprocessor Macros (其他整合方式)
禁用 UIWebView	DISABLE_UIWEBVIEW	SENSORS_ANALYTICS_DISABLE_UIWEBVIEW=1
移除重裝重新觸發啟動事件	DISABLE_INSTALLATION_MARK_IN_KEYCHAIN	SENSORS_ANALYTICS_DISABLE_INSTALLATION_MARK_IN_KEYCHAIN=1
封鎖 GPS 相關程式碼	DISABLE_TRACK_GPS	SENSORS_ANALYTICS_DISABLE_TRACK_GPS=1
不採集 UITableView 點擊事件	DISABLE_AUTOTRACK_UITABLEVIEW	SENSORS_ANALYTICS_DISABLE_AUTOTRACK_UITABLEVIEW=1

20.1. CocoaPods 整合方式設定

# 增加單個 subspec
pod 'SensorsAnalyticsSDK', :subspecs => ['DISABLE_UIWEBVIEW']

# 增加多個 subspec 
pod 'SensorsAnalyticsSDK', :subspecs => ['DISABLE_UIWEBVIEW', 'DISABLE_TRACK_GPS']

CODE

20.2. 其他整合方式設定

21. 查看應用的 App ID Prefix

登入Apple開發者網站，在 Certificates, Identifiers & Profiles 頁面，查看對應的 App ID Prefix