1. 源码集成 macOS SDK

  1. GitHub 下载 SDK 源码
  2. 将 SDK 源码拖入 App 项目中,并选中 Copy items if needed

  3. 项目设置 "Build Phase" -> "Link Binary With Libraries" 中添加依赖库:libicucorelibsqlite3libz

2. 初始化神策分析 macOS SDK

2.1. 获取数据接收地址

数据接收地址是 SDK 上报数据的目标地址,需要使用管理员账户进行获取。

re

2.2. 初始化 SDK 及基本配置

注意:需要在程序入口主线程初始化 SDK,否则可能会丢失部分事件数据。

初始化 SDK

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
     // 初始化配置,必选
    [SensorsAnalyticsSDK sharedInstanceWithServerURL:<#数据接收地址#> andDebugMode:SensorsAnalyticsDebugOff];
     
    /* 注意:只有初始化 SDK 后,才可以调用 [SensorsAnalyticsSDK sharedInstance] 进行其他操作,如:注册公共属性、track 激活事件等 */
 
    // 开启 log 输出,建议只在开发阶段调试开启,非必选
    [[SensorsAnalyticsSDK sharedInstance] enableLog:YES];
}
CODE

3. 使用神策分析 macOS SDK

3.1. 代码埋点追踪事件

神策分析 SDK 成功初始化后,可以通过 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

注意:

  1. 事件名和属性名需要时合法变量名,且不能以 $ 开头;
  2. 属性名大小写敏感,并且不同事件会共用同名属性。即若 foo 事件含有 aaa 属性,则后续所有事件不能使用与 aaa 仅大小写不同的属性(如 aAa、aaA);
  3. 事件名和属性其他约束,具体请参考 数据格式
  4. macOS SDK 暂时只支持代码埋点,不支持全埋点。

3.2. 设置事件公共属性

如果所有事件中都具有某个属性值,则可以将该属性作为公共属性,一个属性注册成公共属性后,SDK 自动会将该属性拼接到所有的埋点事件中,省去了每次都手动添加困扰。 

3.2.1. 静态公共属性

 可以通过 registerSuperProperties: 注册事件公共属性,例如将应用名称作为事件的公共属性:

注册公共属性

[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];
CODE

成功设置事件公共属性后,再通过 track: 追踪事件时,事件公共属性会被添加进每个事件中,例如:

// 记录收藏商品事件
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
                             withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:123456]}];
CODE

在设置事件公共属性后,实际发送的事件中会被加入 AppName 属性,等价于:

// 记录收藏商品事件
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
                             withProperties:@{
                                                 @"ProductID" : [NSNumber numberWithUnsignedLong:123456],
                                                 @"AppName" : @"<#YOUR APP NAME#>"
                                                 }];
CODE

3.2.2. 动态公共属性

通过 registerDynamicSuperProperties 方法设置动态公共属性,设置之后,事件触发时候 SDK 会自动实时获取 registerDynamicSuperProperties 中的属性添加到触发的事件中

动态公共属性

	// 注册动态公共属性
    [[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary * _Nonnull{
        __block NSApplicationOcclusionState appState;
        if (NSThread.isMainThread) {
            appState = NSApplication.sharedApplication.occlusionState;
        }else {
            dispatch_sync(dispatch_get_main_queue(), ^{
                appState = NSApplication.sharedApplication.occlusionState;
            });
        }
        return @{@"__APPState__":@(appState)};
    }];
 
CODE

注意:动态公共属性和静态公共属性的作用相同,注册之后的所有事件都会包含这个属性。

3.3. 用户标识

3.3.1. ID 与用户标识

无论是自定义代码埋点事件还是全埋点自动采集的事件,神策中每个事件都会关联到一个 ID 上,用于标识该事件所对应的用户或设备信息,我们称之为 distinct_id。默认情况下,用户登录前,distinct_id 是 SDK 根据设备生成的一个匿名 ID,默认使用 mac 序列号,如果获取失败,则使用 UUID;用户登录后,开发人员调用 login: 将用户登录 ID 传给 SDK,后续该设备上所有事件的 distinct_id 就会变成用户所对应的 登录 ID。

3.3.2. ID 绑定和用户关联

用户登录前,distinct_id匿名 ID;用户登录后,distinct_id登录 ID。为了将用户登录前后的事件序列串联起来,神策分析采用了用户关联机制:调用 login: 接口时,后台会尝试将匿名 ID登录 ID 关联起来,并生成一个新的 user_id,并在神策分析中使用 user_id 作为标识用户和计算指标的依据。 SDK 内部做了逻辑处理,多次调用 login: 传入相同的登录 ID 时,SDK 会进行忽略。为了保证用户关联的覆盖率,在如下时机时均需要调用 login: 进行用户关联:

  1. 用户注册或登录成功时,需调用 login: 进行用户关联
  2. App 启动时,若当前为已登录用户,需调用 login: 传入登录 ID 进行用户关联
[[SensorsAnalyticsSDK sharedInstance] login:<#业务系统的登录 ID#>];
CODE

4. macOS SDK 中预置属性

字段名称类型显示名说明
$app_version字符串应用版本应用的版本
$lib字符串SDK类型例如 macOS
$lib_version字符串SDK版本
$manufacturer字符串设备制造商例如Apple
$model字符串设备型号例如 MacBookPro14,1
$os字符串操作系统例如 macOS
$os_version字符串操作系统版本例如 10.15.2
$screen_height数值屏幕高度例如 1440
$screen_width数值屏幕宽度例如 2560
$wifiBOOL是否wifi
$network_type字符串网络类型例如 WiFi
$is_first_day布尔值是否首日访问
$device_id字符串设备ID默认获取 序列号,获取不到则使用 UUID