iOS SDK 使用说明

最后更新于:2019-11-28 15:27:35

在使用前,请先阅读数据模型的介绍。
SDK 发版记录,可参考 Release Notes

集成神策分析 SDK

在 iOS App 中集成 神策分析 SDK,使用神策分析采集并分析用户行为。

集成方式选择

神策分析 SDK 支持 CocoaPods、Carthage 和源码方式集成。

通过 CocoaPods 集成

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

    注:如果执行 pod update 无法检测到最新版本,可以先执行 pod cache clean SensorsAnalyticsSDK 清除本地缓存后重新 update。

通过 Carthage 集成

  • 项目 Cartfile 文件中添加以下配置:

    github "sensorsdata/sa-sdk-ios"
    
  • 执行 carthage update --platform iOS 并将 SensorsAnalyticsSDK.framework 添加到您的项目中;

  • 调用文件,导入 SDK:

    #import <SensorsAnalyticsSDK/SensorsAnalyticsSDK.h>
    

通过源码集成

  • GitHub 获取 SDK 的源代码。
  • 将 SDK 源代码导入 App 项目,并选中 Copy items if needed;
  • 项目设置 "Build Phase" -> "Link Binary With Libraries" 中添加依赖库:libicucorelibsqlite3libz

注1:集成 SDK 会使 App 安装包体积增加约 350KB。
注2:神策 SDK 只兼容 iOS 7.0 及以上版本。

配置 Scheme

获取当前项目 scheme 值

项目的 scheme 需要管理员账户进行获取,并且每个项目的 scheme 值都是唯一的,如果 App 在不同环境中使用到了多个数据接收地址,那么也应该配置多个与之对应的 scheme。

App 中配置 scheme

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

初始化神策分析 SDK

获取数据接收地址

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

初始化 SDK 及基本配置

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

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

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

    // 开启全埋点,非必选
    options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |
                                 SensorsAnalyticsEventTypeAppEnd |
                                 SensorsAnalyticsEventTypeAppClick |
                                 SensorsAnalyticsEventTypeAppViewScreen;

    // 开启 crash 采集,非必选
    options.enableTrackAppCrash = YES;

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

    ** 注意:只有初始化 SDK 后,才可以调用 [SensorsAnalyticsSDK sharedInstance] 进行其他操作 **
    /**
     SDK 其他操作,如:注册公共属性、track 激活事件、App 与 H5 打通、开启热力图等
     */

    return YES;
}

Swift 代码示例:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    // 初始化配置,必选
    let options = SAConfigOptions(serverURL: <#数据接收地址#>, launchOptions: launchOptions)

    // 开启全埋点,非必选
    options.autoTrackEventType = [.eventTypeAppClick,.eventTypeAppStart,.eventTypeAppEnd,.eventTypeAppViewScreen]

    // 开启 crash 采集,非必选
    options.enableTrackAppCrash = true

    // 初始化 SDK,必选
    SensorsAnalyticsSDK.start(configOptions: options)

    ** 注意:只有初始化 SDK 后,才可以调用 SensorsAnalyticsSDK.sharedInstance() 进行其他操作 **
    /**
     SDK 其他操作,如:注册公共属性、track 激活事件、App 与 H5 打通、开启热力图等
     */
    return true
}
  • 1.10.26及之前的版本,SDK 初始化方式:

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

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

使用神策分析 SDK

代码埋点追踪事件

神策分析 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}];

Swift 代码示例:

SensorsAnalyticsSDK.sharedInstance()?.track("ViewProduct",withProperties:["ProductID":123456,
                                                                          "ProductCatalog":"Laptop Computer",
                                                                          "IsAddedToFav":false])

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

配置全埋点

SDK 可以自动采集一些通用的用户行为,包括 App 的启动、退出,页面浏览,元素点击四种事件。开发者可以通过 autoTrackEventType 来选择性开启 SDK 自动采集功能:

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];
// 需要开启的全面点类型
options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart | SensorsAnalyticsEventTypeAppEnd | SensorsAnalyticsEventTypeAppClick | SensorsAnalyticsEventTypeAppViewScreen;
[SensorsAnalyticsSDK startWithConfigOptions:options];

Swift 代码示例:

let options = SAConfigOptions.init(serverURL:<#数据接收地址#>, launchOptions: launchOptions)
// 需要开启的全面点类型
options.autoTrackEventType = [.eventTypeAppClick,.eventTypeAppStart,.eventTypeAppEnd,.eventTypeAppViewScreen]
SensorsAnalyticsSDK.start(configOptions: options)
  • 1.10.26及之前的版本,SDK 开启自动采集功能:

记录激活事件

如果使用了神策渠道追踪功能,则需要在 App 启动时调用 trackInstallation: 记录安装激活事件(SDK 内部做了处理,多次调用此方法,只有第一次生效)。

// 事件名可以根据需要自定义,一般为 AppInstall
[[SensorsAnalyticsSDK sharedInstance] trackInstallation:@"AppInstall"];

注1. 此接口第一次调用时,会触发 AppInstall 事件,并设置 $first_visit_time 用户属性。 注2. 更多关于渠道追踪功能介绍请参考 《新增用户与渠道追踪》

设置事件公共属性

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

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

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

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

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

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

Swift 代码示例:

SensorsAnalyticsSDK.sharedInstance().registerSuperProperties(["AppName":"<#YOUR APP NAME#>"])

注1. 公共属性只会对注册之后的事件生效,所以需要尽早注册公共属性,建议在初始化 SDK 之后立即设置。 注2. 公共属性会保存在 App 本地缓存中。可以通过 unregisterSuperProperty: 删除一个公共属性,或使用 clearSuperProperties: 删除所有已设置的事件公共属性。
注3. 当公共属性和事件属性的 Key 相同时,事件属性优先级最高,它会覆盖公共属性。
注4. 公共属性约束和事件属性相同,详情参考数据格式

ID 与用户标识

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

注1. 关于匿名 ID 的生成规则,可参考

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 进行用户关联

Objective-C 代码示例:

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

Swift 代码示例:

SensorsAnalyticsSDK.sharedInstance().login("<#登录ID#>")

注1. 登录 ID 是指可以唯一标识一个用户的 ID,通常是业务数据库里的主键或其它唯一标识。

设置用户属性

除了给事件添加属性,SDK 也支持给用户设置属性,如年龄、性别、等级,神策事件分析、留存分析、分布分析等功能均支持使用用户属性作为过滤条件,精确分析特定人群的指标。 注1. 关于事件属性和用户属性的区别,请参考 数据模型

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

Objective-C 代码示例:

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

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

Swift 代码示例:

//设置单个用户属性
SensorsAnalyticsSDK.sharedInstance().set("Gender", to:"Male")

//设置多个用户属性
SensorsAnalyticsSDK.sharedInstance().set(["Age":18])
  • 只保留初次设定的用户属性 对于需要保证只有首次设置时有效的属性,如用户首次充值金额、首次设置的昵称等,可以使用 setOnce:setOnce:to: 接口进行记录。与 set: 方法不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据,如果属性不存在则会自动创建。

Objective-C 代码示例:

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

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

Swift 代码示例:

    SensorsAnalyticsSDK.sharedInstance().setOnce("AdSource", to: "App Store")

    SensorsAnalyticsSDK.sharedInstance().setOnce(["AdSource":"Email"])
  • 数值类型属性累加新值 针对一些数值型属性,如消费总额、用户积分等属性,我们可以使用 increment:increment:by: 对原值进行累加,神策会自动计算并保存累加之后的值。

    Objective-C 代码示例:

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

    Swift 代码示例:

    SensorsAnalyticsSDK.sharedInstance().increment("GamePlayed", by: 1)
    SensorsAnalyticsSDK.sharedInstance().increment(["UserPaid":1,"PointEarned":5])
    
  • 列表类型属性追加新值 对于列表类型用户属性,如用户喜爱的电影、用户点评过的餐厅等属性,可以调用 append:by: 接口进行追加一些新值。

Objective-C 代码示例:

    // 设定用户观影列表属性,设定后属性 "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"]]];

Swift 代码示例:

    SensorsAnalyticsSDK.sharedInstance().append("Movies", by: ["Sicario","Love Letter"])

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

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

Objective-C 代码示例:

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

Swift 代码示例:

SensorsAnalyticsSDK.sharedInstance()?.unset("Gender")

注1 用户属性的命名约束,请参考参考 数据格式

事件数据的查看与调试

为了方便开发者调试事件数据,神策分析提供了多种数据的查看及调试方式。

实时查看当前设备事件数据

  1. 电脑端打开神策分析页面,埋点 -> 导入实时查看 -> Debug 数据 -> 设置设备调试模式,使用相机或其他二维码工具扫码屏幕二维码

  2. 扫码打开 App 后,会弹出提示,选择想要切换的调试模式。 开启调试模式(导入数据): 打开调试模式,校验数据,并将数据导入到神策分析中。 开启调试模式(不导入数据): 打开调试模式,仅校验数据,但不进行数据导入,数据最终不会进入到数据库。

注1:此功能要求神策分析版本大于 1.13,并且 App 配置了 scheme 及 添加了 -handleSchemeUrl:注2:调试模式只对本次启动有效,退出 App 自动失效,需要重新扫码进行开启。

IDE 控制台查看事件信息

扫码打开调试模式后,SDK 同时自动开启日志输出功能,也可在测试阶段通过 -enableLog: 接口打开 SDK 日志输出功能。 SDK 日志输出开启后,在 IDE (如 Xcode)日志控制台中筛选 SALog 关键词: 埋点事件触发成功时,SDK 会输出 【track event】 开头的事件数据; 埋点事件触发失败时,SDK 会输出相应的错误原因; 事件数据上报成功时,SDK 会输出 【valid message】字段开头的事件数据; 事件数据上报失败时,SDK 会输出 【invalid message】 字段开头的事件数据并输出错误原因。

通过自定义查询查看已入库的事件数据

神策分析中事件分析模块具有缓存机制,如果事件数据刚入库或者数据量变动比较小,事件分析模块的数据可能没有更新,此时可以通过自定义查询模块进行查询已入库的数据。

附录

附1:iOS SDK 中预置属性

所有事件公共预置属性:

字段名称 类型 显示名 说明 版本
$app_version 字符串 应用版本 应用的版本
$lib 字符串 SDK类型 例如iOS
$lib_version 字符串 SDK版本
$manufacturer 字符串 设备制造商 例如Apple
$model 字符串 设备型号 例如iPhone9,2
$os 字符串 操作系统 例如iOS
$os_version 字符串 操作系统版本 例如8.1.1
$screen_height 数值 屏幕高度 例如1920
$screen_width 数值 屏幕宽度 例如1080
$wifi BOOL 是否wifi
$carrier 字符串 运营商名称 例如ChinaNet
$network_type 字符串 网络类型 例如4G
$is_first_day 布尔值 是否首日访问 1.6.29支持
$device_id 字符串 设备ID 默认获取 IDFA,获取失败则获取IDFV,获取不到IDFV则获取UUID。 1.10.18支持
$screen_orientation 字符串 屏幕方向1 屏幕当前的方向 1.10.1支持
$latitude 数值 GPS信息2 纬度*106 1.10.1支持
$longitude 数值 GPS信息2 经度*106 1.10.1支持

注意:

  1. $screen_orientation 属性只有在开启 enableTrackScreenOrientation 时才会采集。
  2. $latitude、$longitude 属性只有在开启 enableTrackGPSLocation 时才会采集。

$AppStart(App 启动) 事件特有预置属性

字段名称 类型 显示名 说明 版本
$is_first_time BOOL 是否首次访问 App 安装后是否首次启动
$is_first_day BOOL 是否首日访问 App 安装后是否首日访问 1.6.29支持
$resume_from_background BOOL 是否从后台唤醒 App 是否是从后台恢复

$AppEnd(App 退出) 事件特有预置属性

字段名称 类型 显示名 说明 版本
$event_duration 数值 $event_duration 本次 App 启动的使用时长

$AppViewScreen(App 浏览页面) 事件特有预置属性

字段名称 类型 显示名 说明 版本
$title 字符串 页面标题 ViewController 的标题
$screen_name 字符串 页面名称 ViewController 的类名

$AppClick(App 元素点击) 事件特有预置属性

字段名称 类型 显示名 说明 版本
$element_type 字符串 元素类型 控件的类型,例如UIButton
$element_content 字符串 元素内容 控件的内容
$title 字符串 页面标题 ViewController 的标题
$screen_name 字符串 页面名称 ViewController 的类名
$element_position 字符串 元素位置 元素被点击时所处的位置

注意:$element_position 属性只有在列表点击的时候才会获取,例如 UITableVIew 和 UICollectionView 。