基本使用(iOS)

介绍 SDK 的常用功能点及使用方式。

全埋点(iOS)

介绍 SDK 全埋点采集的原理、全埋点事件的忽略与补充、属性的手动补充等知识。

高级功能(iOS)

介绍 SDK 中特殊场景下的一些功能及使用方式。

常见问题(iOS)

介绍 SDK 集成和使用过程中的一些常见疑问。

App Extension 中的使用

介绍 App Extension 中怎么使用 SDK 采集事件。



集成神策分析 SDK

  • 项目 Podfile 中添加以下配置:
pod 'SensorsAnalyticsSDK'
CODE
  • Podfile 目录下执行 pod install 安装 SDK。


注意:如果执行 pod update 无法检测到最新版本,可以先执行 pod cache clean SensorsAnalyticsSDK 清除本地缓存后重新 update。
  • 项目 Cartfile 文件中添加以下配置:
github "sensorsdata/sa-sdk-ios"
CODE
  • 执行 carthage update --platform iOS 并将 SensorsAnalyticsSDK.framework 添加到您的项目中;
  • 从  GitHub 获取 SDK 的源代码。
  • 将 SDK 源代码导入 App 项目,并选中 Copy items if needed;
  • 项目设置 "Build Phase" -> "Link Binary With Libraries" 中添加依赖库:libicucorelibsqlite3libz

集成 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 预置事件和预置属性