iOS SDK
新书推荐《iOS 全埋点解决方案》
- 在使用前,请先阅读数据模型
- SDK 的更新日志,可参阅 Release Notes
iOS SDK 合规
- 您需要确保 App 有《隐私政策》,并且在用户首次启动 App 时就弹出《隐私政策》取得用户同意。
- 您需要告知用户您 App 集成了神策分析 SDK:
- 如果您没有使用 IDFA, 请在隐私政策中增加如下参考条款:
“我们使用了神策 SDK,采集您的 IDFV 信息,用于统计分析您在 App 内的使用效果。” - 如果您使用了 IDFA,请在隐私政策中增加如下参考条款:
“我们使用了神策 SDK,采集您的 IDFA 信息,用于统计分析您在 App 内的使用效果。”
- 如果您没有使用 IDFA, 请在隐私政策中增加如下参考条款:
- 您务必确保用户同意《隐私政策》后,再初始化神策 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"
- 执行 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;
}
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
}
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;
}
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
if SensorsAnalyticsSDK.sharedInstance()?.handleSchemeUrl(url) ?? false{
return true
}
return true
}
- 如果 - 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#>"}];
// 将 AppName 注册为公共属性
SensorsAnalyticsSDK.sharedInstance()?.registerSuperProperties(["AppName" : "<#YOUR APP NAME#>"])
公共属性会保存在 App 本地缓存中,可以通过 - unregisterSuperProperty: 删除一个公共属性,或使用 - clearSuperProperties: 删除所有已设置的事件公共属性。
4.3. 用户登录
当用户注册成功或者进行登录时,需要调用SDK 的用户登录接口:
- Objective-C & version<4.3.0
- Swift & version<4.3.0
- Objective-C & version >=4.3.0
- Swift & version >=4.3.0
[[SensorsAnalyticsSDK sharedInstance] login:@"<#登录 ID#>"];
SensorsAnalyticsSDK.sharedInstance()?.login("<#登录 ID#>")
用户登录时调用,第一个参数从详细的预置 ID key 列表中获取,第二个参数为对应的具体用户 ID
iOS SDK
[[SensorsAnalyticsSDK sharedInstance] loginWithKey:@"key" loginId:@"value"];
多用户 ID 关联时调用,第一个参数从详细的预置 ID key 列表中获取,第二个参数为对应的关联用户 ID
iOS SDK
[[SensorsAnalyticsSDK sharedInstance] bind:@"$identity_mobile" value:@"187****8991"];
多用户 ID 取消关联时调用,第一个参数为取消关联的 key,第二个参数为对应的取消关联用户 ID
iOS SDK
[[SensorsAnalyticsSDK sharedInstance] unbind:@"$identity_mobile" value:@"187****8991"];
用户登录时调用,第一个参数从详细的预置 ID key 列表中获取,第二个参数为对应的具体用户 ID
iOS SDK
SensorsAnalyticsSDK.sharedInstance()?.login(withKey:"key",loginId:"value");
多用户 ID 关联时调用,第一个参数从详细的预置 ID key 列表中获取,第二个参数为对应的关联用户 ID
iOS SDK
SensorsAnalyticsSDK.sharedInstance()?.bind("$identity_mobile",value:"187****8991");
多用户 ID 取消关联时调用,第一个参数为取消关联的 key,第二个参数为对应的取消关联用户 ID
iOS SDK
SensorsAnalyticsSDK.sharedInstance()?.unbind("$identity_mobile",value:"187****8991");
为了准确记录登录用户的行为信息,建议在以下时机各调用一次用户登录接口:
· 用户在注册成功时 · 用户登录成功时 · 已登录用户每次启动 App 时
4.4. 记录激活事件
可以调用 - trackAppInstallWithProperties: 方法记录激活事件,多次调用此方法只会在第一次调用时触发激活事件:
#error 如果您之前使用 - trackInstallation: 触发的激活事件,需要继续保持原来的调用,无需改为 - trackAppInstall: , 否则会导致激活事件数据分离。
[[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];
#error 如果您之前使用 - trackInstallation: 触发的激活事件,需要继续保持原来的调用,无需改为 - trackAppInstall: , 否则会导致激活事件数据分离。
SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"])
若用原记录的激活事件名不是 $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"}];
}
}
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"])
}
}
更多关于渠道追踪功能的说明,请参考渠道追踪。
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)}];
SensorsAnalyticsSDK.sharedInstance()?.track("<#事件名#>", withProperties: ["<#属性名#>" : "<#属性值#>"])
事件名和事件属性的格式规范,请参考数据格式。
5. 调试查看事件信息
初始化 SDK 时,进行以下配置,即可打开 SDK 的日志输出功能:
// 打开 SDK log 功能
options.enableLog = YES;
//开启log
options.enableLog = true
然后在 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]}];
// 设定用户年龄属性 "Age" 为 18
// set: 方法设定一个或多个用户属性
SensorsAnalyticsSDK.sharedInstance()?.set(["Age" : 18])
6.2. 打通 App 与 H5
版本要求
iOS SDK v2.0.8 及以上版本。
初始化 SDK 时,进行如下配置,即可开启 App 打通 H5 功能:
// 开启 App 打通 H5
options.enableJavaScriptBridge = YES;
// 开启 App 打通 H5
options.enableJavaScriptBridge = true
打通功能需要 App 和 H5 同时开启才可以生效,H5 开启方法请参考 App 打通 H5。
6.3. 可视化全埋点
版本要求
- 神策分析 v1.17.2517+
- iOS SDK v2.0.0+
SDK 初始化时,进行如下配置,即可开启可视化全埋点:
// 开启可视化全埋点
options.enableVisualizedAutoTrack = YES;
// 开启可视化全埋点
options.enableVisualizedAutoTrack = true
6.3.1. 可视化全埋点自定义属性
注意事项:
如果您需要使用可视化全埋点自定义属性,需要配置 enableVisualizedProperties:
// 开启可视化全埋点自定义属性配置下发
options.enableVisualizedProperties = YES;
此属性为 false 的情况下,创建的可视化自定义属性无法采集。