1. 开启 Crash 信息的自动采集

1.8.12+ 版本 SDK 支持自动采集 Crash 信息,可以在初始化 SDK 时通过配置 SAConfigOptions 进行开启。开启后的 Crash 堆栈信息会记录在 AppCrashed 事件的 app_crashed_reason 属性中。

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:launchOptions];
options.enableTrackAppCrash = YES;
[SensorsAnalyticsSDK startWithConfigOptions:options];
CODE

2. 开启屏幕方向的自动采集

1.10.1+ 版本 SDK 支持自动采集屏幕方向,可以在初始化 SDK 后调用 enableTrackScreenOrientation: 进行开启,开启后的屏幕方向信息记录在事件的 $screen_orientation 属性中。

[[SensorsAnalyticsSDK sharedInstance] enableTrackScreenOrientation:YES]; 
CODE

3. 开启位置信息自动采集

1.10.1+ 版本 SDK 支持自动采集 GPS 信息,可以在初始化 SDK 后调用 - enableTrackGPSLocation: 方法进行开启,开启后的经纬度信息会乘 10⁶ 后记录在事件的 $longitude$latitude 属性中。

// CoreLocation 采集 GPS 信息
[[SensorsAnalyticsSDK sharedInstance] enableTrackGPSLocation:YES];
CODE

4. 开启点击分析功能

使用点击分析功能前,确保您的 App 中配置了当前项目的 Scheme,详细操作可参考配置 Scheme

1.9.3+ 版本 SDK 支持 App 点击分析功能,可以在初始化 SDK 后调用 - enableHeatMap 进行开启,SDK 会在所有的 $AppClick 事件添加控件路径信息,用于和点击分析中热力图进行匹配。

[[SensorsAnalyticsSDK sharedInstance] enableHeatMap];
CODE

开启 App 点击分析后,该功能默认对所有页面上的点击生效, 如果您只是想部分页面进行热力图,可以通过 addHeatMapViewControllers: 进行配置添加。

[[SensorsAnalyticsSDK sharedInstance] addHeatMapViewControllers:@"HomeViewController", "DiscoverViewController"];
CODE
  • 此功能需要神策分析 1.13 及以上版本。
  • 此功能前提是的全埋点中开启了点击事件的采集功能。

5. 统计事件时长

1.10.6+ 版本 SDK 支持代码埋点来统计事件的时长,只需要在行为开始时调用  - trackTimerStart:,在行为结束时调用 trackTimerEnd:withProperties: 接口,SDK 会自动计算时长,并以秒(浮点数)为单位存在事件的 $event_duration 属性中。

此外,SDK 还支持暂停和恢复操作,可通过 trackTimerPause:、trackTimerResume: 接口进行统计。
以直播 App 中用户视频播放行为为例:

// 开始播放视频时
[[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"WatchVideo"];

// 暂停播放时
[[SensorsAnalyticsSDK sharedInstance] trackTimerPause:@"WatchVideo"];

// 恢复播放时
[[SensorsAnalyticsSDK sharedInstance] trackTimerResume:@"WatchVideo"];

// 停止或者结束播放时
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:@"WatchVideo" withProperties:@{@"VideoType": @"film"}];
CODE

5.1. 同名事件交叉的时长统计

默认情况下,时长的统计以事件名作为标识,相同的事件名会自动匹配 start-end,如果两个同名事件在时间上有交叉部分,会造成错误匹配。为了解决此问题,1.11.17+ 版本 SDK 支持同名事件交叉的时长统计,开发者需要保存 - trackTimerStart: 的返回值,以便后续针对性地进行暂停、恢复或停止。

// 开始第一个事件计时
NSString *timer1 = [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"testTimer"];
 
// 开始第二个事件计时
NSString *timer2 = [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"testTimer"];
 
//如果需要暂停第一个事件计时
[[SensorsAnalyticsSDK sharedInstance] trackTimerPause:timer1];
 
//如果需要恢复第一个事件计时
[[SensorsAnalyticsSDK sharedInstance] trackTimerResume:timer1];
 
// 结束第一个事件计时
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:timer1];
 
// 结束第二个事件计时
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:timer2];
CODE


  • 只有调用 trackTimerEnd: 时,SDK 才会真正记录事件。
  • 多次调用 trackTimerStart:,以最后一次调用作为计时起点。
  • 默认情况下,统计的时长不包括用户 App 在后台的时长。

6. 追踪并进行渠道匹配和回传

1.10.15+ 版本 SDK 支持追踪自定义事件时进行渠道匹配,可以调用 trackChannelEvent:properties: 对待匹配的事件进行追踪,后台匹配到渠道信息后会将结果回传到渠道商。

 比如用户首次下单时,将下单线索同渠道商进行匹配:

// 用户下单时
[[SensorsAnalyticsSDK sharedInstance] trackChannelEvent:@"PayOrder" properties:@{@"Amount": @(35.0)}];
CODE
  • 当次安装首次触发回传事件,记录事件并进行渠道匹配和回传。
  • 当次安装再次触发回传事件,记录事件,但不进行渠道匹配和回传。
  • 卸载重装首次触发回传事件,记录事件并进行渠道匹配和回传。

p.s. 上述规则适用于同名事件,不同事件之间不相互影响。

7. 设置事件动态公共属性

对于一些值会变化的公共属性,如当前游戏等级、最新金币余额等,1.10.8+ 版本 SDK 提供了registerDynamicSuperProperties: 接口,该接口需要开发者传入一个返回公共属性的 block,每次事件触发时,SDK 都会执行这个 block 来获取最新的公共属性。

[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary<NSString *,id> * _Nonnull{
	return @{@"level": <#当前游戏等级#>,
			 @"balance": <#最新金币余额#>};
}];
CODE


动态公共属性和公共属性的区别是:前者适合标记年龄,后者适合标记性别。

8. 获取预置属性

前端 SDK 在记录事件时会添加设备相关的预置属性,为了保证前后端事件属性的一致性,某些情况下可能需要在前端获取 SDK 预置属性,1.8.19+ 版本 SDK 可以使用 - getPresetProperties 方法获取事件预置属性,然后通过业务接口传到服务端,由服务端添加到事件属性中。

// 获取事件预置属性
[[SensorsAnalyticsSDK sharedInstance] getPresetProperties];
CODE

9. 入库前修改事件信息

1.11.16+ 版本 SDK 支持在事件入库前进行修改属性、删除事件,可以使用 - trackEventCallback: 中 block 参数进行设置:

  1. block 中 eventName 参数为当前事件名。
  2. block 中 properties 参数为当前事件属性,该参数为 NSMutableDictionary 类型,可直接修改此参数达到修改事件属性的目的。
  3. block 返回值标志事件是否需要继续入库和上报: YES 事件会继续入库,NO 将删除此条事件。
  • 严禁在 block 中调用 - track:- trackInstallation: - login:  等触发事件的接口,否则会因循环调用而导致应用崩溃。
  • block 返回 NO 时 SDK 将删除此条事件,所以请确保判断逻辑,以免造成误删除事件。


[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName,
                                                               NSMutableDictionary<NSString *,id> *properties) {
    // BuyProduct 事件不进行入库
    if ([eventName isEqualToString:@"BuyProduct"]) {
        return NO;
    }
    
    // 删除 ViewProduct 事件 category 属性
    if ([eventName isEqualToString:@"ViewProduct"]) {
        [properties removeObjectForKey:@"category"];
    }
        
    return YES;
}];
CODE

10. 打通 App 与 H5

神策分析 SDK 提供打通 iOS App 与 H5 功能,详情介绍请参考打通 App 与 H5

11. 自定义上报策略

为了减少性能和电量损耗,Android SDK 和 iOS SDK 中事件触发后不会立即上报,而是先将事件缓存在本地,然后定时、批量进行上报。

11.1. 上报条件

iOS SDK 每次触发事件时会检查如下条件,以判断是否向服务器上传数据:
1. 当前网络是否符合 flushNetworkPolicy (默认 3G、4G、5G、WiFi)
2. 与上次发送的时间间隔是否大于 flushInterval (默认 15 秒)
3. 本地缓存的事件条目数是否大于 flushBulkSize (默认 100 条)

只有1、2 或1、3 满足时,SDK 才会进行发送数据。以上参数支持自定义,可以通过修改相应参数值来达到控制事件上报的频率。

flushNetworkPolicy 设置为 NONE 时,可以在不影响 SDK 事件采集前提下停止 SDK 事件上报能力。在一些合规需求中,可以通过此属性控制 SDK 是否上报事件信息。


11.2. 强制上报

如果特定事件需要立即上报,可以在事件触发后调用 - flush 接口强制进行上报。

11.3. 退出上报

为了确保数据的及时上报,SDK 会在应用进入后台或退出时强制触发一次事件上报,如不需要,可以将 flushBeforeEnterBackground 设置为 NO 进行关闭.

11.4. 缓存上限

如果事件触发后一直不满足上报条件,本地缓存的数据条数会越来越多,当缓存事件量达到 maxCacheSize 时,每次再触新的事件,SDK 会依次丢弃老数据,保留最新的数据。maxCacheSize 默认为 10000 条,支持客户自定义。

12. 自定义匿名 ID

默认情况下,SDK 会生成匿名 ID 并可以保证该 ID 的唯一性,如果需要替换神策默认分配的匿名 ID ,可以在初始化 SDK 之后立即调用 identify: 方法进行替换。
代码示例:

[[SensorsAnalyticsSDK sharedInstance] identify:<#自定义匿名 ID#>];
CODE

13. 本地证书校验

1.11.1+ 版本 SDK 发送数据时支持本地证书校验,可按照如下步骤进行配置:

  • 服务器生成 SSL 证书,如果不是 .cer 格式,需要使用 OpenSSL 进行格式转换:

openssl x509 -in 你的证书.crt -out 你的证书.cer -outform der
CODE
  • 将证书拖入项目中,选取相应 Target 并选择 Copy items if needed。
  • 配置神策 SDK 证书校验方式:

SASecurityPolicy *securityPolicy = [SensorsAnalyticsSDK sharedInstance].securityPolicy;

/*
是否允许无效证书(自建证书),默认为 NO ,
如果是需要验证自建证书,需要设置为 YES 。
*/
securityPolicy.allowInvalidCertificates = YES;

/*
是否需要验证域名,默认为 YES ,
如证书的域名与请求的域名不一致,需把该项设置为 NO 。
*/
securityPolicy.validatesDomainName = NO;

/*
配置本地证书路径
*/
securityPolicy.pinnedCertificates = [SASecurityPolicy certificatesInBundle:[NSBundle mainBundle]];

/*
设置证书校验方式,默认为 SASSLPinningModeNone
*/
securityPolicy.SSLPinningMode = SASSLPinningModePublicKey;
CODE


其中,SSLPinningMode 有以下三种模式:

SASSLPinningModeNone:默认模式,客户端无条件信任服务端返回证书,不做 App 本地证书校验。
SASSLPinningModePublicKey:只验证证书中公钥,不验证证书的有效期等信息。
SASSLPinningModeCertificate:校验本地证书的所有信息。

SASSLPinningModeCertificate 模式会校验证书有效期等信息,如果不能保证用户 App 证书始终处于未过期状态,建议使用SASSLPinningModePublicKey 模式。

14. 清空本地缓存事件

为了适应 GDPR 要求,1.10.8+ 版本 SDK 增加了 - deleteAll 方法用于清空本地缓存的所有事件。

[[SensorsAnalyticsSDK sharedInstance] deleteAll];
CODE

15. 预编译宏配置 SDK 特性

为了满足客户特殊场景下的需求,SDK 支持通过预编译宏来选择性编译某些功能。通过 CocoaPods 集成时,可以通过添加 subspecs 进行配置;其他集成方式,可以在项目中配置 Preprocessor Macros

功能subspec (CocoaPods 方式)Preprocessor Macros (其他集成方式)备注
禁用 UIWebViewDISABLE_UIWEBVIEWSENSORS_ANALYTICS_DISABLE_UIWEBVIEW=1
卸载重装重新触发激活事件DISABLE_INSTALLATION_MARK_IN_KEYCHAINSENSORS_ANALYTICS_DISABLE_INSTALLATION_MARK_IN_KEYCHAIN=1
屏蔽 GPS 相关代码DISABLE_TRACK_GPSSENSORS_ANALYTICS_DISABLE_TRACK_GPS=1
不采集 UITableView 点击事件DISABLE_AUTOTRACK_UITABLEVIEWSENSORS_ANALYTICS_DISABLE_AUTOTRACK_UITABLEVIEW=1

15.1. CocoaPods 集成方式配置

# 添加单个 subspec 
pod 'SensorsAnalyticsSDK', :subspecs => ['DISABLE_UIWEBVIEW']

# 添加多个 subspec 
pod 'SensorsAnalyticsSDK', :subspecs => ['DISABLE_UIWEBVIEW', 'DISABLE_TRACK_GPS']
CODE

15.2. 其他集成方式配置