在使用前，請先閱讀數據模型
SDK的更新日誌，可參閱 Release Notes

iOS SDK 合规

您需要確保 App 有《隱私政策》，並且在用戶首次啓動 App 時就彈出《隱私政策》取得用戶同意。
您需要告知用戶您 App 集成了神策分析 SDK：
- 如果您沒有使用 IDFA, 請在隱私政策中增加如下參考條款：
  「我們使用了神策 SDK，採集您的 IDFV 信息，用於統計分析您在 App 內的使用效果。」
- 如果您使用了 IDFA，請在隱私政策中增加如下參考條款：
  「我們使用了神策 SDK，採集您的 IDFA 信息，用於統計分析您在 App 內的使用效果。」
您務必確保用戶同意《隱私政策》後，再初始化神策 SDK。

1. 整合神策分析 SDK

在 Podfile 文件中增加 pod 'SensorsAnalyticsSDK'

打開終端機，切換到項目目錄
執行 pod install 或 pod update

注：如果執行 pod update 無法檢測到最新版本，可以先執行 pod cache clean SensorsAnalyticsSDK 清除本地暫存。

從 GitHub 取得SDK的原始碼
將源代碼中 SensorsAnalyticsSDK 目錄導入 App 項目，並選中 Copy items if needed
項目設置 "Build Phase" -> "Link Binary With Libraries" 中添加依賴庫：libicucore、libsqlite3 和 libz

在 Cartfile 文件中增加以下配置：

github "sensorsdata/sa-sdk-ios"

CODE

執行 carthage update --platform iOS 並將 SensorsAnalyticsSDK.framework 增加到您的項目中

整合 SDK 會讓 App 安裝包體積增加約 350 KB
SDK 兼容 iOS 8.0 及以上版本

2. 初始化神策分析 SDK

2.1. 取得項目數據接收地址

每個項目都有單獨的數據接收地址
請使用管理員賬戶取得相應項目的數據接收地址

2.2. 初始化 SDK

在 AppDelegate 的 - application: didFinishLaunchingWithOptions: 中增加初始化程式碼：

// 引入神策分析 SDK
#import <SensorsAnalyticsSDK/SensorsAnalyticsSDK.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 初始化配置
    SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#數據接收地址#> launchOptions:launchOptions];
    // 開啟全埋點
    options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |
                                 SensorsAnalyticsEventTypeAppEnd |
                                 SensorsAnalyticsEventTypeAppClick |
                                 SensorsAnalyticsEventTypeAppViewScreen;
#ifdef DEBUG
    // 开启 Log
    options.enableLog = YES;
#endif

	/**
	 * 其他配置，如開啟可視化全埋點
	 */
    // 初始化 SDK
    [SensorsAnalyticsSDK startWithConfigOptions:options];
	
	
    return YES;
}

CODE

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
         
    let options = SAConfigOptions.init(serverURL: <#數據接收地址#>, launchOptions: launchOptions)  
      
    //開啟全埋點
    options.autoTrackEventType = [.eventTypeAppStart, .eventTypeAppEnd, .eventTypeAppClick, .eventTypeAppViewScreen]
#ifdef DEBUG
    //開啟开启log
    options.enableLog = true
#endif
 	/**
	 * 其他配置，如開啟可視化全埋點
    */
    //初始化SDK
    SensorsAnalyticsSDK.start(configOptions: options)
         
    return true
     
}

CODE

3. 配置 Scheme

3.1. 取得項目 Scheme

項目的 Scheme 需要管理員帳號取得
App 工程中可以同時配置多個項目的 Scheme

3.2. App 中增加 Scheme

App 工程中選擇 target -> Info -> Types，點擊加號(+)，將上一步獲得的 Scheme 配置到 URL Types 中：

3.3. 處理傳入的 URL

在 AppDelegate 的 - application:openURL:options: 方法中調用 - handleSchemeUrl: 對神策分析 Scheme 進行處理：

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
	if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url]) {
		return YES;
	}
	return NO;
}

CODE

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
     if SensorsAnalyticsSDK.sharedInstance()?.handleSchemeUrl(url) ?? false{
			return true
	}
	return true
}

CODE

如果 - application:openURL:options: 中还有其他逻辑处理，需要将 - handleSchemeUrl: 尽量前置，以保证 - handleSchemeUrl: 能被执行。

4. SDK 基本配置

4.1. 開啟全埋點

初始化 SDK 時，autoTrackEventType 屬性可以配置需要開啓的全埋點類型。全埋點其他配置，可参考全埋点 (iOS)。

5. 設置事件公共屬性

對於所有事件都需要添加的屬性，初始化 SDK 後，可使用 - registerSuperProperties: 將屬性註冊為公共屬性：

// 将 AppName 註冊為公共属性
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];

CODE

// 將 AppName 註冊為公共属性 
SensorsAnalyticsSDK.sharedInstance()?.registerSuperProperties(["AppName" : "<#YOUR APP NAME#>"])

CODE

公共属性会保存在 App 本地缓存中，可以通过 - unregisterSuperProperty: 删除一个公共属性，或使用 - clearSuperProperties: 删除所有已设置的事件公共属性。

5.1. 使用者登入

當使用者註冊成功或者進行登入時，需要調用SDK的 - login: 接口：

[[SensorsAnalyticsSDK sharedInstance] login:@"<#登入 ID#>"];

CODE

SensorsAnalyticsSDK.sharedInstance()?.login("<#登入 ID#>")

CODE

為了準確記錄使用者的行為信息，建議在以下時機各調用一次 - login: 接口：

· 用戶在註冊成功時
· 用戶登錄成功時 
· 已登錄用戶每次啓動 App 時

5.2. 紀錄啟動事件

可以調用 - trackAppInstallWithProperties:

方法記錄激活事件，多次調用此方法只會在第一次調用時觸發激活事件：

#error 如果您之前使用 - trackInstallation:  觸發的啟動事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離。
[[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];

CODE

#error 如果您之前使用 - trackInstallation:  觸發的啟動事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離。
SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"])

CODE

5.2.1. 使用 IDFA 用於精准渠道追蹤

該功能需要在 info.plist 文件中添加 NSUserTrackingUsageDescription：提示用戶授權的一句話（具體根據業務需求而定）。

	// 需要 #import <AppTrackingTransparency/AppTrackingTransparency.h>
	if (@available(iOS 14, *)) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
			// iOS 14 及以上紀錄啟動事件
		    #error 如果您之前使用 - trackInstallation:  觸發的激活事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離。             
		[[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];
        }];
    } else {
		// iOS 13 及以下紀錄啟動事件
		#error 啟動接口請雨上面接口保持一致
        [[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];
    }

CODE

// 需要 #import <AppTrackingTransparency/AppTrackingTransparency.h>
if #available(iOS 14, *) {
      ATTrackingManager.requestTrackingAuthorization { (status) in
			// iOS 14 及以上紀錄啟動事件 		    
			#error 如果您之前使用 - trackInstallation:  觸發的激活事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離。             
           SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"])
          }
     } else {
		  // iOS 13 及以下錄啟動事件
 	      #error 動接口請雨上面接口保持一致
          SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"])     
}

CODE

5.2.2. 使用 CAID 進行渠道匹配

if (獲取 CAID 後觸發激活事件){ 
	#error 如果您之前使用 - trackInstallation:  觸發的激活事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離。  
	[[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];
}

CODE

if (獲取 CAID 後觸發激活事件){ 
	#error 如果您之前使用 - trackInstallation:  觸發的激活事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離
	SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"])
}

CODE

5.2.3. 既使用 IDFA 又使用 CAID 進行渠道比對

// 需要 #import <AppTrackingTransparency/AppTrackingTransparency.h>
if (@available(iOS 14, *)) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
            if (獲取 CAID 後觸發激活事件){
				#error 如果您之前使用 - trackInstallation:  觸發的激活事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離
   			  [[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];
			}
        }];
    } else {
        if (獲取 CAID 後觸發激活事件){     
			#error 如果您之前使用 - trackInstallation:  觸發的激活事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離
		     [[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];
			}
    }

CODE

// 需要 #import <AppTrackingTransparency/AppTrackingTransparency.h> 
if #available(iOS 14, *) { 
		ATTrackingManager.requestTrackingAuthorization { (status) in 
		  if (獲取 CAID 後觸發激活事件){ 
			  #error 如果您之前使用 - trackInstallation:  觸發的激活事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離。 
			  SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"]) 
			  } 
		  } 
} else { 
		if (獲取 CAID 後觸發激活事件){ 
			#error 如果您之前使用 - trackInstallation:  觸發的激活事件，需要繼續保持原來的調用，無需改為 - trackAppInstall: , 否則會導致激活事件數據分離。 
			SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"]) 
		} 
}

CODE

開啟此功能，您需要使用 CAID SDK 并集成神策 iOS SDK CAID 模块：

如果是 pod 集成： pod 'SensorsAnalyticsSDK', :subspecs => ['CAID']
如果是原始碼整合，需要將 CAID 文件夾引用到工程裡即可

在獲取 CAID 时，不管是否獲取到都需要調用啟動事件

更多关于渠道追踪功能的更多關於渠道追蹤功能的說明，請參考渠道追蹤追蹤。

5.3. 代碼埋點追蹤事件

SDK 初始化後，可以通過 - track: 和 - track:withProperties: 方法追蹤使用者行為事件，並為事件增加自訂義屬性：

UInt64 productId = 123456;
NSString *productCatalog = @"Laptop Computer";
BOOL isAddedToFavorites = NO;

[[SensorsAnalyticsSDK sharedInstance] track:@"BuyProduct"
							 withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:productId],
											  @"ProductCatalog" : productCatalog,
											  @"IsAddedToFav" : @(isAddedToFavorites)}];

CODE

SensorsAnalyticsSDK.sharedInstance()?.track("<#事件名#>", withProperties: ["<#屬性名#>" : "<#屬性值#>"])

CODE

事件名和事件屬性的格式規範，請參考數據格式。

6. 調試查看事件訊息

初始化 SDK 時，進行以下配置，即可打開 SDK 的日誌輸出功能：

// 打開 SDK log 功能
options.enableLog = YES;

CODE

//開啟log
options.enableLog = true

CODE

然後在 IDE (如 Xcode )日誌控制台中篩選 SALog 關鍵詞：

埋點事件觸發成功時，SDK 會輸出【track event】開頭的事件數據
埋點事件觸發失敗時，SDK 會輸出相應的錯誤原因
事件數據上報成功時，SDK 會輸出【valid message】字段開頭的事件數據
事件數據上報失敗時，SDK 會輸出【invalid message】字段開頭的事件數據並輸出錯誤原因

7. SDK 可選配置

7.1. 設置用戶屬性

- set: 方法可以設置使用者屬性，同一個 key 多次設置時，value 值會進行覆蓋替換：

// 設定使用者年齡屬性 "Age" 为 18
// set: 方法设定一个或多个使用者属性
[[SensorsAnalyticsSDK sharedInstance] set:@{@"Age" : [NSNumber numberWithInt:18]}];

CODE

// 设定使用者年龄属性 "Age" 为 18
// set: 方法設定一個或多個使用者屬性
SensorsAnalyticsSDK.sharedInstance()?.set(["Age" : [NSNumber numberWithInt:18])

CODE

關於事件屬性和使用者屬性的區別，請參考數據模型
使用者属性的命名约束，请参考参考數據格式
使用者属性其他设置方法，可参考使用者属性设置

7.2. 打通 App 与 H5

版本要求

iOS SDK v2.0.8 及以上版本。

初始化 SDK 時，進行如下配置，即可開啓 App 打通 H5 功能：

// 開啟 App 打通 H5
options.enableJavaScriptBridge = YES;

CODE

// 開啟 App 打通 H5
options.enableJavaScriptBridge = true

CODE

打通功能需要 App 和 H5 同時開啓才可以生效，H5 開啓方法請參考 App 打通 H5。

7.3. 可視化全埋點

版本要求

神策分析 v1.17.2517+
iOS SDK v2.0.0+

SDK 初始化時，進行如下配置，即可開啓可視化全埋點：

// 開啟視化全埋點 
options.enableVisualizedAutoTrack = YES;

CODE

// 開啟視化全埋點
options.enableVisualizedAutoTrack = true

CODE

本功能使用前，請確保您 iOS 項目中已完成配置 Scheme
可視化全埋點在神策分析中的使用，請參考可視化全埋點