菜单

集成文档（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 目录导入 App 项目，并选中 Copy items if needed
  3. 项目设置 "Build Phase" -> "Link Binary With Libraries" 中添加依赖库：libicucore、libsqlite3 和 libz

Carthage 方式

  1. 在 Cartfile 文件中添加以下配置
    github "sensorsdata/sa-sdk-ios"
  2. 执行 carthage update --platform iOS 并将 SensorsAnalyticsSDK.framework 添加到您的项目中
  1. 在 Podfile 文件中添加 pod 'SensorsAnalyticsSDK'
  2. 打开终端，切换到项目目录
  3. 执行 pod install 或 pod update

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

  1. 从  GitHub 获取 SDK 的源代码
  2. 将源代码中 SensorsAnalyticsSDK 目录导入 App 项目，并选中 Copy items if needed
  3. 项目设置 "Build Phase" -> "Link Binary With Libraries" 中添加依赖库：libicucore、libsqlite3 和 libz

  1. 在 Cartfile 文件中添加以下配置
    github "sensorsdata/sa-sdk-ios"
  2. 执行 carthage update --platform iOS 并将 SensorsAnalyticsSDK.framework 添加到您的项目中

注意

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

初始化神策分析 SDK

获取项目数据接收地址

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

初始化 SDK

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

Objective-C

// 引入神策分析 SDK
#import 

- (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
     
}
// 引入神策分析 SDK
#import 

- (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;
}
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 *)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
}


- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options {
	if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url]) {
		return YES;
	}
	return NO;
}
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
// 打开 SDK log 功能
options.enableLog = YES;
//开启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
options.enableJavaScriptBridge = YES;
// 开启 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 清除本地缓存。

  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 清除本地缓存。

  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   

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

}


// 引入神策分析 SDK Extension 依赖头文件
#import   

- (void)viewDidLoad {
    [super viewDidLoad];

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

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

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

    // 初始化 SDK
    [SensorsAnalyticsSDK startWithConfigOptions:options];
}
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）
最近修改: 2024-12-27