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


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)。

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 的 - login: 接口：

[[SensorsAnalyticsSDK sharedInstance] login:@"<#登录 ID#>"];
CODE 
SensorsAnalyticsSDK.sharedInstance()?.login("<#登录 ID#>")
CODE

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

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

4.4. 记录激活事件

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

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

4.4.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

4.4.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

4.4.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 模块：

  1. 如果是 pod 集成： pod 'SensorsAnalyticsSDK', :subspecs => ['CAID'] 
  2. 如果是源码集成，需要将 CAID 文件夹引入到工程里即可

在获取 CAID 时，不管是否获取到都需要调用激活事件

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

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" : [NSNumber numberWithInt: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