基本使用(iOS)

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

集成 SDK 会使 App 安装包体积增加约 350KB。

初始化 SDK 并开启全埋点

初始化 SDK 需要配置上报数据的目标地址，该地址可以使用管理员账户进行获取。

需要在程序入口主线程同步初始化 SDK，否则可能会丢失部分事件数据。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

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

	// 开启全埋点，可根据需求进行组合
	options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |
								 SensorsAnalyticsEventTypeAppEnd |
								 SensorsAnalyticsEventTypeAppClick |
								 SensorsAnalyticsEventTypeAppViewScreen;
#ifdef DEBUG
	// SDK 开启 Log
	options.enableLog = YES;
#endif

	// 初始化 SDK
	[SensorsAnalyticsSDK startWithConfigOptions:options];

	return YES;
}

CODE

配置 Scheme

项目的 scheme 需要管理员账户进行获取
如果 App 在不同环境中使用到了多个数据接收地址，也应该配置多个与之对应的 scheme

获取当前项目 scheme 值

App 中配置 scheme

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

处理传入的 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

如果 - application:openURL:options: 中还有其他逻辑处理，需要将 - handleSchemeUrl: 尽量前置，以保证 - handleSchemeUrl: 能被执行。

代码埋点追踪事件

可以通过 - track: 和 - track:withProperties: 方法追踪用户行为事件，并为事件添加自定义属性：

UInt64 productId = 123456;
NSString *productCatalog = @"Laptop Computer";
BOOL isAddedToFavorites = NO;

[[SensorsAnalyticsSDK sharedInstance] track:@"ViewProduct"
							 withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:productId],
											  @"ProductCatalog" : productCatalog,
											  @"IsAddedToFav" : isAddedToFavorites ? @YES : @NO}];

CODE

事件名和属性名需要时合法变量名，且不能以 $ 开头；
属性名大小写敏感，并且不同事件会共用同名属性。即若 foo 事件含有 "aaa" 属性，则后续所有事件不能使用与 "aaa" 仅大小写不同的属性(如 aAa、aaA)；
事件名和属性其他约束，具体请参考数据格式。

设置事件公共属性

如果所有事件中都需要某些相同的属性，可使用 - registerSuperProperties: 把这些属性注册为公共属性：

// 将 AppName 注册为公共属性
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];

// 记录商品收藏事件中也会具有 AppName 属性
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
							 withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:123456]}];

CODE

在初始化 SDK 之后尽早设置公共属性
公共属性会保存在 App 本地缓存中。可以通过 - unregisterSuperProperty: 删除一个公共属性，或使用 - clearSuperProperties: 删除所有已设置的事件公共属性
公共属性约束和事件属性相同，详情参考数据格式

事件动态公共属性

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

对于一些值会变化的公共属性，如当前游戏等级、最新金币余额等，1.10.8+ 版本 SDK 提供了- registerDynamicSuperProperties: 接口来设置动态公共属性:

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

CODE

事件属性的优先级为：track 事件时传入的属性 > 动态公共属性 > 公共属性> 预置属性；
动态公共属性的约束和事件属性相同，详情参考数据格式。

记录激活事件

如果使用了神策渠道追踪功能，则需要在 App 启动时调用 - trackInstallation: 记录安装激活事件：

// 记录激活事件
[[SensorsAnalyticsSDK sharedInstance] trackInstallation:@"AppInstall"
                                         withProperties:@{@"DownloadChannel": @"AppStore"}];

CODE

第一次调用 - trackInstallation: 时， SDK 会在 KeyChain 中记录一个标志位。只有 App 在当前设备上的首次安装才会记录激活事件，卸载重装不重复触发。
第一次调用 - trackInstallation: 时， SDK 会触发您命名的激活事件，并设置用户 $first_visit_time 属性。
更多关于渠道追踪功能介绍请参考渠道追踪。

用户登录

当用户在客户端进行登录时，需要调用SDK 的 - login: 接口：

[[SensorsAnalyticsSDK sharedInstance] login:@"<#登录ID#>"];

CODE

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

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

调用- login: 传入的值应当是可以唯一标识单个用户的 ID，通常是业务数据库里的主键或其它唯一标识。

设置用户属性

除了给事件添加属性，SDK 也支持给用户设置属性，如年龄、性别、等级，神策事件分析、留存分析、分布分析等功能均支持使用用户属性作为过滤条件，精确分析特定人群的指标。

关于事件属性和用户属性的区别，请参考数据模型
用户属性的命名约束，请参考参考数据格式

属性更新

- set:、- set:to:，可以设定用户属性，同一个 key 多次设置时，value 值会进行覆盖替换。

// 设定用户性别属性 "Gender" 为 "Male"
// set:WithValue 方法用于设定单个用户属性
[[SensorsAnalyticsSDK sharedInstance] set:@"Gender" to:@"Male"];

// 设定用户年龄属性 "Age" 为 18
// set: 方法设定一个或多个用户属性
[[SensorsAnalyticsSDK sharedInstance] set:@{@"Age" : [NSNumber numberWithInt:18]}];

CODE

保留初次属性

对于需要保证只有首次设置时有效的属性，如用户首次充值金额、首次设置的昵称等，可以使用 - setOnce: 或 - setOnce:to: 接口进行记录。与 - set: 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。

// 设定用户 AdSource 渠道为为 "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"App Store"];

// 再次设定用户 AdSource 渠道，设定无效，AdSource 属性值仍然是 "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"Email"];

CODE

数值属性累加

针对一些数值型属性，如消费总额、用户积分等属性，我们可以使用 - increment: 或 - increment:by: 对原值进行累加，神策会自动计算并保存累加之后的值。

// 将用户游戏次数属性增加一次
// increment:by: 对一个属性进行累加
[[SensorsAnalyticsSDK sharedInstance] increment:@"GamePlayed" by:[NSNumber numberWithInt:1]];

// 增加用户付费次数和积分
// increment: 对一个或多个属性进行累加
[[SensorsAnalyticsSDK sharedInstance] increment:@{@"UserPaid" : [NSNumber numberWithInt:1],
												  @"PointEarned" : [NSNumber numberWithFloat:12.5]}];

CODE

列表属性追加

对于列表类型用户属性，如用户喜爱的电影、用户点评过的餐厅等属性，可以调用 - append:by: 接口进行追加一些新值。

// 设定用户观影列表属性，设定后属性 "Movies" 为: ["Sicario", @"Love Letter"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Sicario", @"Love Letter"]]];

// 再次设定该属性，属性 "Movies" 为: ["Sicario", @"Love Letter", @"Dead Poets Society"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Love Letter", @"Dead Poets Society"]]];

CODE

列表型属性中的元素必须为 NSString 类型，且元素的值会自动去重。关于列表型限制请见数据格式。

属性取消

如果需要取消已设置的某个用户属性，可以调用 - unset: 进行取消

// 取消设置 gender 属性
[[SensorsAnalyticsSDK sharedInstance] unset:@"Gender"];

CODE

打通 App 与 H5

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

可视化全埋点

版本要求

神策分析 v1.15.2420+、v1.16.2386+、v1.17.2517+

iOS SDK v2.0.0+

本功能使用前，请确保您 iOS 项目中已完成配置 Scheme

可视化全埋点在神策分析中的使用，请参考可视化全埋点

开启可视化全埋点

SDK 初始化前将 SAConfigOptions 实例 - enableVisualizedAutoTrack 属性设置为 YES 即可开启可视化全埋点：

// 开启可视化全埋点
options.enableVisualizedAutoTrack = YES;

OBJECTIVE-C

部分页面开启可视化全埋点

可视化全埋点开启后，默认对 App 内全部页面生效，如果只需要部分页面开启可视化全埋点，可以在 SDK 初始化后使用- addVisualizedAutoTrackViewControllers: 进行添加：

// 只开启 MainController 的可视化全埋点
[[SensorsAnalyticsSDK sharedInstance] addVisualizedAutoTrackViewControllers:[NSArray arrayWithObject:@"MainController"]];

OBJECTIVE-C

调试查看数据

SDK 初始化前将 SAConfigOptions 实例 enableLog 属性设置为 YES 即可打开 SDK 的日志输出功能，

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

OBJECTIVE-C

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

埋点事件触发成功时，SDK 会输出 【track event】 开头的事件数据；

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

所有事件公共预置属性

神策分析 SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为所有事件都有的公共属性，详细的默认属性列表可以参考 App SDK 预置事件和预置属性。