菜单

集成文档（iOS）

iOS SDK 合规

  • 您需要确保 App 有《隐私政策》，并且在用户首次启动 App 时就弹出《隐私政策》取得用户同意。
  • 您需要告知用户您 App 集成了神策分析 SDK：
    • 如果您没有使用 IDFA，请在隐私政策中增加如下参考条款：
      “我们使用了神策 SDK，采集您的 IDFV 信息，用于统计分析您在 App 内的使用效果。”
    • 如果您使用了 IDFA，请在隐私政策中增加如下参考条款：
      “我们使用了神策 SDK，采集您的 IDFA 信息，用于统计分析您在 App 内的使用效果。”
  • 您务必确保用户同意《隐私政策》后，再初始化神策 SDK。

 

集成神策分析 SDK

CocoaPods 方式

  1. 在 Podfile 文件中添加 pod 'SensorsAnalyticsSDK'
  2. 打开终端，切换到项目目录
  3. 执行 pod install 或 pod update

注：如果执行 pod update 无法检测到最新版本，可以先执行 pod cache clean SensorsAnalyticsSDK 清除本地缓存。

源码方式

  1. 从 GitHub 获取 SDK 的二进制包
  2. 将 SensorsAnalyticsSDK > Source > Core 目录下的 SensorsAnalyticsSDK.xcframework 包拖到 App 项目，并选中 Copy items if needed
  3. 项目设置 "Build Phase" > "Link Binary With Libraries" 中添加依赖库：libicucore、libsqlite3 和 libz

升级到 v5.0.0 版本须知

SDK 自从 v5.0.0 版本开始，更改为二进制包（xcframework）的形式，同时在目录结构上做了一定的调整，带来了一些集成方式的变更，具体如下：

  • 不再维护一些过时的 subspec，包含 WebView、WKWebView、DeprecatedCellClick、ApplicationExtension 等，如 pod 集成出现 SensorsAnalyticsSDK 相关报错，请联系售后技术同学处理
  • Location 和 DeviceOrientation 两个 subspec 不再提供，相关功能使用参考 开启位置信息采集 和 开启屏幕方向采集
  • Core 以及依赖 Core 的 Exposure 和 EnglishResources subspec 与 Base 是互斥的，请不要一起使用。如需开启曝光或英文功能，建议使用初始化配置 SAConfigOptions 中接口
  • 在项目中多个 Target 集成 SDK 不同的 subspec 的情况下，pod 安装后可能会出现 “Multiple commands produce ... [CP] Copy XCFrameworks” 的错误，请联系技术售后同学处理

注意

  • 集成 SDK 会使 App 安装包体积增加约 350 KB
  • SDK 兼容 iOS 9.0 及以上版本
  • 请使用 CocoaPods v1.12.0 及以上版本，否则会出现 bundle 签名报错

初始化神策分析 SDK

获取项目数据接收地址

  • 每个项目都有单独的数据接收地址
  • 请使用 管理员 账户获取相应项目的数据接收地址

初始化 SDK

在 AppDelegate 的 - application: didFinishLaunchingWithOptions: 中添加初始化代码：

Objective-C

// 引入神策分析 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;
}

Swift

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
     
}

配置 Scheme

获取项目 Scheme

  • 项目的 Scheme 需要管理员账户进行获取
  • App 工程中可以同时配置多个项目的 Scheme

App 中添加 Scheme

App 工程中选择 target > Info > Types，点击加号 (+)，将上一步获取到的 Scheme 配置到 URL Types 中：

处理传入的 URL

在 AppDelegate 的 - application: openURL: options: 方法中调用 - handleSchemeUrl: 对神策分析 Scheme 进行处理：

Objective-C

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

Swift

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

注意

  1. 如果 - application: openURL: options: 中还有其他逻辑处理，需要将 - handleSchemeUrl: 尽量前置，以保证 - handleSchemeUrl: 能被执行。
  2. 如果项目中使用 SceneDelegate, 需要在 - scene: openURLContexts: 方法中调用 - handleSchemeUrl: 对神策分析 Scheme 进行处理

SDK 基本配置

开启全埋点

初始化 SDK 时，autoTrackEventType 属性可以配置需要开启的全埋点类型。全埋点使用文档参见 基础 API 功能介绍。

用户关联

用户关联是为了对用户进行唯一标识，提高用户行为分析的准确性。目前神策提供了简易用户关联和全域用户关联，分别用于支撑不同的业务场景。

设置事件公共属性

对于所有事件都需要添加的属性，初始化 SDK 后，可使用 registerSuperProperties: 将属性注册为公共属性。详细使用文档参见 基础 API 功能介绍。

记录激活事件

可以调用 trackAppInstallWithProperties: 方法记录激活事件，多次调用此方法只会在第一次调用时触发激活事件。详细使用文档参见 渠道追踪与广告。

代码埋点追踪事件

SDK 初始化后，可以通过 track: 和 track:withProperties: 方法追踪用户行为事件，并为事件添加自定义属性。详细使用文档参见 基础 API 功能介绍。

调试查看事件信息

初始化 SDK 时，进行以下配置，即可打开 SDK 的日志输出功能：

Objective-C

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

Swift

// 开启 log
options.enableLog = true

然后在 IDE（如 Xcode）日志控制台中筛选 SALog 关键词：

  • 埋点事件触发成功时，SDK 会输出 【track event】 开头的事件数据
  • 埋点事件触发失败时，SDK 会输出相应的错误原因
  • 事件数据上报成功时，SDK 会输出 【valid message】 字段开头的事件数据
  • 事件数据上报失败时，SDK 会输出 【invalid message】 字段开头的事件数据并输出错误原因

SDK 可选配置

打通 App 与 H5

版本要求

iOS SDK v2.0.8 及以上版本。

初始化 SDK 时，进行如下配置，即可开启 App 打通 H5 功能：

Objective-C

// 开启 App 打通 H5
options.enableJavaScriptBridge = YES;

Swift

// 开启 App 打通 H5
options.enableJavaScriptBridge = true

注意

打通功能需要 App 和 H5 同时开启才可以生效，H5 开启方法请参考 App 打通 H5。

可视化全埋点

在 SDK 初始化时调用 enableVisualizedAutoTrack 开启可视化全埋点，详细使用文档参照 基础 API 功能可视化全埋点介绍。

iOS App Extension 集成

App Extension 中集成神策分析 SDK

注意

  • App Extension 集成神策 SDK，同时宿主 App 支持全埋点，依赖 SensrsAnalyticsSDK v4.5.16 及以上版本
  • 请确保主 target 和 Extension 对应的 target，集成 SensrsAnalyticsSDK 相同的 subspec，否则 Archive 可能会报错导致失败

针对 App Extension 集成神策 iOS SDK，推荐需要使用 CocoaPods 方式集成。并且针对主 target 和 Extension 对应的 target，需要集成 相同的 subspec，推荐使用默认 subspec 即可。参考如下

Extension 和主 target 分别集成

  1. 在 Podfile 文件的主 target 和 Extension 都需要添加 pod 'SensorsAnalyticsSDK'，参考如下 
    platform :ios, '9.0'

target 'SensorsData' do
  use_frameworks!
  pod 'SensorsAnalyticsSDK'
end

target 'SensorsDataExtension' do
  use_frameworks!
  pod 'SensorsAnalyticsSDK'
end
  2. 打开终端，切换到项目目录
  3. 执行 pod install 或 pod update

注：如果执行 pod update 无法检测到最新版本，可以先执行 pod cache clean SensorsAnalyticsSDK 清除本地缓存。

Extension 继承主 target 集成

  1. 在 Podfile 文件的主 target 中添加 pod 'SensorsAnalyticsSDK'，Extension 继承主 target 依赖的三方库，参考如下 
    platform :ios, '9.0'

target 'SensorsData' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  pod 'SensorsAnalyticsSDK'

  target 'SensorsDataExtension' do
    use_frameworks!
  end

end
  2. 打开终端，切换到项目目录
  3. 执行 pod install 或 pod update

注：如果执行 pod update 无法检测到最新版本，可以先执行 pod cache clean SensorsAnalyticsSDK 清除本地缓存。

App Extension 中使用神策分析 SDK

初始化神策分析 SDK

注意

App Extension 中，导入 SensorsAnalyticsExtension.h 头文件使用神策分析 SDK。SensorsAnalyticsSDK.h 中部分接口，在 Extension 中不可用，不要导入

在 App Extension 中，如 Today Extension, Share Extension 等，请在对应的 ViewController.m 的 - (instancetype)initWithCoder 或 - (void)viewDidLoad 等方法中初始化神策分析 SDK

Objective-C
// 引入神策分析 SDK Extension 依赖头文件
#import <SensorsAnalyticsSDK/SensorsAnalyticsExtension.h>  

- (void)viewDidLoad {
    [super viewDidLoad];

    // 初始化配置
    SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];

#ifdef DEBUG
    // 开启 Log
    options.enableLog = YES;
#endif

    /**
     * 其他配置，Extension 只支持基础埋点，不支持全埋点、可视化全埋点等功能
     */

    // 初始化 SDK
    [SensorsAnalyticsSDK startWithConfigOptions:options];
}
Swift
override func viewDidLoad() {
    super.viewDidLoad()               
    
    let options = SAConfigOptions.init(serverURL: <#数据接收地址#>, launchOptions: launchOptions)  

#ifdef DEBUG
    // 开启 log
    options.enableLog = true
#endif
    /**
     * 其他配置，Extension 只支持基础埋点，不支持全埋点、可视化全埋点等功能
     */

    // 初始化 SDK
    SensorsAnalyticsSDK.start(configOptions: options)
}

追踪事件

在 App Extension 中埋点触发事件，和普通 App 相同，例如在 ShareViewController 的 didSelectPost 回调中埋点。其他使用，参考 基础 API 介绍（iOS）

[SensorsAnalyticsSDK.sharedInstance track:"<#事件名#>" withProperties:@{@"<#属性名#>": @"<#属性值#>"}];
上一个
iOS SDK
下一个
基础 API 介绍（iOS）
最近修改: 2025-04-27