新书推荐《iOS 全埋点解决方案》

在使用前，请先阅读数据模型
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: 能被执行。
如果项目中使用 SceneDelegate, 需要在 - scene:openURLContexts: 方法中调用 - handleSchemeUrl: 对神策分析 Scheme 进行处理

4. SDK 基本配置

4.1. 开启全埋点

初始化 SDK 时，autoTrackEventType 属性可以配置需要开启的全埋点类型。全埋点其他配置，可参考全埋点 (iOS)。

4.2. 设置事件公共属性

对于所有事件都需要添加的属性，初始化 SDK 后，可使用 - registerSuperProperties: 将属性注册为公共属性：

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

CODE

// 将 AppName 注册为公共属性
SensorsAnalyticsSDK.sharedInstance()?.registerSuperProperties(["AppName" : "<#YOUR APP NAME#>"])

CODE

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

4.3. 用户登录

当用户注册成功或者进行登录时，需要调用SDK 的用户登录接口：

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

CODE

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

CODE

SDK 版本 >= 4.3.0，用户登录时调用，第一个参数从详细的预置 ID key 列表中获取，第二个参数为对应的具体用户 ID。

调用接口后，对应的 key 和 value 会缓存在本地，后续采集的事件，均包含缓存的 ID 信息。

iOS SDK

 [[SensorsAnalyticsSDK sharedInstance] loginWithKey:@"key" loginId:@"value"];

CPP

多用户 ID 关联时调用，第一个参数从详细的预置 ID key 列表中获取，第二个参数为对应的关联用户 ID。

调用接口后，对应的 key 和 value 会缓存在本地，后续采集的事件，均包含缓存的 ID 信息。

iOS SDK

[[SensorsAnalyticsSDK sharedInstance] bind:@"$identity_mobile" value:@"187****8991"];

CPP

多用户 ID 取消关联时调用，第一个参数为取消关联的 key，第二个参数为对应的取消关联用户 ID。

调用接口后，会发送相关的解绑事件，同时会将本地缓存的 ID 信息中，对应的 key-value 清除（若存在）。

iOS SDK

[[SensorsAnalyticsSDK sharedInstance] unbind:@"$identity_mobile" value:@"187****8991"];

CPP

SDK 版本 >= 4.3.0，用户登录时调用，第一个参数从详细的预置 ID key 列表中获取，第二个参数为对应的具体用户 ID。

调用接口后，对应的 key 和 value 会缓存在本地，后续采集的事件，均包含缓存的 ID 信息。

iOS SDK

SensorsAnalyticsSDK.sharedInstance()?.login(withKey:"key",loginId:"value");

CPP

多用户 ID 关联时调用，第一个参数从详细的预置 ID key 列表中获取，第二个参数为对应的关联用户 ID。

调用接口后，对应的 key 和 value 会缓存在本地，后续采集的事件，均包含缓存的 ID 信息。

iOS SDK

SensorsAnalyticsSDK.sharedInstance()?.bind("$identity_mobile",value:"187****8991");

CPP

多用户 ID 取消关联时调用，第一个参数为取消关联的 key，第二个参数为对应的取消关联用户 ID。

调用接口后，会发送相关的解绑事件，同时会将本地缓存的 ID 信息中，对应的 key-value 清除（若存在）。

iOS SDK

SensorsAnalyticsSDK.sharedInstance()?.unbind("$identity_mobile",value:"187****8991");

CPP

为了准确记录登录用户的行为信息，建议在以下时机各调用一次用户登录接口：

· 用户在注册成功时
· 用户登录成功时
· 已登录用户每次启动 App 时

4.4. 记录激活事件

可以调用 - trackAppInstallWithProperties: 方法记录激活事件，多次调用此方法只会在第一次调用时触发激活事件：

#error 如果您之前使用 - trackInstallation:  触发的激活事件，需要继续保持原来的调用，无需改为 - trackAppInstall: , 否则会导致激活事件数据分离。
[[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];

CODE

#error 如果您之前使用 - trackInstallation:  触发的激活事件，需要继续保持原来的调用，无需改为 - trackAppInstall: , 否则会导致激活事件数据分离。
SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"])

CODE

若用原记录的激活事件名不是 $AppInstall，需要使用虚拟事件将原激活事件和 $AppInstall 合并分析数据，具体咨询神策技术支持

4.4.1. 使用 IDFA 用于精准渠道追踪

该功能需要在 info.plist 文件中添加 NSUserTrackingUsageDescription 配置

- (void)applicationDidBecomeActive:(UIApplication *)application{
    // 需要 #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

func applicationDidBecomeActive(_ application: UIApplication) {
        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

IDFA 授权代码需要在 UIApplicationStateActive 状态时才能弹出授权窗，详细信息可参考苹果开发者中心。

更多关于渠道追踪功能的说明，请参考渠道追踪。

4.5. 代码埋点追踪事件

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

事件名和事件属性的格式规范，请参考数据格式。

5. 调试查看事件信息

初始化 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】 字段开头的事件数据并输出错误原因

6. SDK 可选配置

6.1. 设置用户属性

- set: 方法可以设置用户属性，同一个 key 多次设置时，value 值会进行覆盖替换：

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

CODE

// 设定用户年龄属性 "Age" 为 18
// set: 方法设定一个或多个用户属性
SensorsAnalyticsSDK.sharedInstance()?.set(["Age" : 18])

CODE

关于事件属性和用户属性的区别，请参考数据模型
用户属性的命名约束，请参考参考数据格式
用户属性其他设置方法，可参考用户属性设置

6.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。

6.3. 可视化全埋点

版本要求

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

SDK 初始化时，进行如下配置，即可开启可视化全埋点：

// 开启可视化全埋点
options.enableVisualizedAutoTrack = YES;

CODE

// 开启可视化全埋点
options.enableVisualizedAutoTrack = true

CODE

6.3.1. 可视化全埋点自定义属性

版本要求

iOS SDK v4.0.0 及以上版本

SA 开启 SDG 且 SDG 的版本 v0.10.0.134 以上

Edge 版本号：0.2.9882

注意事项：

如果您需要使用可视化全埋点自定义属性，需要配置 enableVisualizedProperties:

// 开启可视化全埋点自定义属性配置下发
options.enableVisualizedProperties = YES;

CODE

此属性为 false 的情况下，创建的可视化自定义属性无法采集。

本功能使用前，请确保您 iOS 项目中已完成配置 Scheme
可视化全埋点在神策分析中的使用，请参考可视化全埋点