iOS SDK 使用说明

最后更新于:2019-10-09 11:47:06

在使用前,请先阅读数据模型的介绍。

更新日志

1. 集成神策分析 SDK

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

1.1 通过 CocoaPods 集成

我们推荐使用 CocoaPods 快速集成:

  • 安装 CocoaPods
  • 在项目中新建 Podfile 文件,并添加:
    pod 'SensorsAnalyticsSDK'

其他集成方式:

集成方式 说明 支持版本
pod 'SensorsAnalyticsSDK', :subspecs => ['LOG'] 集成 SDK 同时开启调试日志 1.6.39及以后版本支持
pod 'SensorsAnalyticsSDK', :subspecs => ['ENABLE_REACT_NATIVE_APPCLICK'] 集成 SDK 同时开启对 React Native 页面控件的自动采集 1.8.0及以后版本支持
pod 'SensorsAnalyticsSDK', :subspecs => ['ENABLE_REACT_NATIVE_APPCLICK', 'LOG'] 集成 SDK 同时开启多个功能 1.8.0及以后版本支持

1.10.18 及之后版本,如果 App 引入了 AdSupport 库,SDK 默认使用 IDFA 作为匿名 ID,之前版本通过指定 subspecs pod 'SensorsAnalyticsSDK', :subspecs => ['IDFA'] 同时引入了 AdSupport 库来开启使用 IDFA 作为匿名 ID。

推荐使用以上方式集成。如果在项目的编译选项中定义相关宏,当执行 pod update 命令时,会清除设置,使用以上方式集成设置不会被清除。

  • 关闭 Xcode
  • 在 Xcode 项目目录下执行 pod install,CocosPods 会自动下载神策分析 SDK 并进行配置,再重启 Xcode 即可

iOS SDK 要求最低 iOS 版本为 7.0。目前,Release 模式并支持 arm7 与 arm64 双架构时,神策分析 SDK 大小约 600 KB。

注: 如果执行

pod update

无法检测到最新版本,可以先执行如下命令清除本地缓存再 update。

pod cache clean SensorsAnalyticsSDK

1.2 通过 Carthage 集成

  • 通过 Homebrew 安装 Carthage :

    $ brew update
    $ brew install carthage
    
  • 在项目中新建 Cartfile 文件,并添加:

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

  • 调用文件,导入 SDK:

    #import <SensorsAnalyticsSDK/SensorsAnalyticsSDK.h>
    

1.3 通过源码集成

如果不想通过 CocosPod 进行集成,也可以从 GitHub 获取 SDK 的源代码,并添加进项目使用。

需要注意的是,如果通过这种方式使用神策分析 SDK,需要在项目设置 "Build Phase" - "Link Binary With Libraries" 中添加依赖库:libicucore、libsqlite3 和 libz。

2. 初始化神策分析 SDK

2.1 获取数据接收地址

首先从神策分析系统中,获取数据接收 URL。

如果私有部署的过程中修改了 Nginx 的默认配置,或通过 CDN 等访问神策分析,则请咨询相关人员获得配置信息。

2.2 在 Objective-C 中使用

在程序的入口(如 AppDelegate.m )中引入 SensorsAnalyticsSDK.h,并在 - (BOOL) application:(UIApplication *)didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 中调用 startWithConfigOptions: 初始化 SDK。

注意:神策 iOS SDK 必须在主线程里进行初始化,否则会引发无法预料的问题(比如丢失 $AppStart 事件)。
    // 引入神策分析 SDK
    #import "SensorsAnalyticsSDK.h"

    // 数据接收的 URL
    #define SA_SERVER_URL @"YOUR_SERVER_URL"

    // 初始化 SDK
    SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:launchOptions];
    [SensorsAnalyticsSDK startWithConfigOptions:options];

swift 代码示例:

    let options = SAConfigOptions.init(serverURL: SA_SERVER_URL, launchOptions: launchOptions)
    SensorsAnalyticsSDK.start(configOptions: options)
  • 1.10.26及之前的版本,SDK 初始化方式:

其中 SA_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。一旦成功初始化后,则可以通过 sharedInstance 获取 SDK 实例,进行用户行为事件或属性的追踪。

至此,我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的配置方法,可以跳到本文末尾的 设置神策分析 SDK 一节。

3. 追踪事件

第一次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:

  • 图片社交产品,可以追踪用户浏览图片和评论事件
  • 电商产品,可以追踪用户浏览商品和下订单等事件

神策分析 SDK 成功初始化后,可以通过 track:track:withProperties: 方法追踪用户行为事件,并为事件添加自定义属性。以电商产品为例,可以这样追踪一次购物行为:

    // 在用户浏览商品页面时...

    UInt64 productId = 123456;                      // 获取商品ID
    NSString *productCatalog = @"Laptop Computer";  // 获取商品类别
    BOOL isAddedToFavorites = NO;                // 是否被添加到收藏夹

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

    // 在用户结账付款时...

    float orderPaid = 50.10;                        // 订单支付金额
    NSSet *orderList = [NSSet setWithArray:@[@"Apple iPhone6s", @"Nexus 6"]];   // 产品列表

    [[SensorsAnalyticsSDK sharedInstance] track:@"PaidOrder"
                                 withProperties:@{
                                                  @"OrderPaid" : [NSNumber numberWithFloat:orderPaid],
                                                  @"OrderList" : orderList
                                                  }];

swift 代码示例:

    // 在用户浏览商品页面时...
    SensorsAnalyticsSDK.sharedInstance()?.track("ViewProduct", withProperties:
                                            ["ProductID":123456,                // 获取商品ID
                                             "ProductCatalog":"Laptop Computer",// 获取商品类别
                                             "IsAddedToFav":false])             // 是否被添加到收藏夹

触发事件后,在神策分析中稍等片刻,便能看到追踪结果。

3.1 AutoTrack

开发者集成神策分析 SDK 后,SDK 可以自动采集一些用户行为,如 App 启动、退出等,开发者可以通过 enableAutoTrack: 接口打开自动采集功能:

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:launchOptions];
options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart | SensorsAnalyticsEventTypeAppEnd | SensorsAnalyticsEventTypeAppClick | SensorsAnalyticsEventTypeAppViewScreen;
[SensorsAnalyticsSDK startWithConfigOptions:options];

swift 代码示例:

let options = SAConfigOptions.init(serverURL: SA_SERVER_URL, launchOptions: launchOptions)
options.autoTrackEventType = [.eventTypeAppClick,.eventTypeAppStart,.eventTypeAppEnd,.eventTypeAppViewScreen]
SensorsAnalyticsSDK.start(configOptions: options)
  • 1.10.26及之前的版本,SDK 开启自动采集功能:

打开 AutoTrack 后,会采集的事件包括:

  • 点击控件时,会发送 $AppClick 事件,会包含点击的相应控件的基本信息。

    • 继承于 UIControl 的控件(如 UIButtonUISlider 等)的点击、UIImageViewUILabel 上添加的手势:
      • $element_type - String 类型,表示控件的类型
      • $element_content - String 类型,表示控件的内容
      • $title - String 类型,表示 ViewController 的标题,先读取controller.navigationItem.title,如果有自定义view,并且能够获取到文本,就覆盖 controller.navigationItem.title 获取到的值
      • $screen_name - String 类型,表示 ViewController 的类名
    • UITableViewUICollectionView 的 Cell 点击事件:
      • $element_type - String 类型,表示控件的类型
      • $element_content - String 类型,表示控件的内容
      • $title - String 类型,表示 ViewController 的标题,先读取controller.navigationItem.title,如果有自定义view,并且能够获取到文本,就覆盖 controller.navigationItem.title 获取到的值
      • $screen_name - String 类型,表示 ViewController 的类名
      • $element_position - String 类型,表示控件被点击的具体位置(例如:'0:2'表示 Section=0,Row =2)
  • App 启动或从后台恢复时,会自动记录 $AppStart 事件,事件属性:

    • $is_first_time - Bool 类型,Yes 表示 App 安装后首次启动,No 则相反
    • $is_first_day - Bool 类型,Yes 表示 App 安装后首日访问,No 则表示不是首日访问(1.6.29 及以后版本支持该属性)
    • $resume_from_background - Bool 类型,Yes 表示 App 从后台恢复,No 表示 App 启动
  • App 进入后台时,会自动记录 $AppEnd 事件,事件属性:

    • $event_duration - Int 类型,表示本次 App 启动的使用时长,单位为秒
  • App 由系统唤醒时,会自动记录 $AppStartPassively 事件,事件属性和 $AppStart 事件相同。
    关于$AppStartPassively事件说明,请参考

  • App 浏览页面时(切换 ViewController),会自动记录记录 $AppViewScreen 事件,事件属性:

    • $title - String 类型,表示 ViewController 的标题,先读取controller.navigationItem.title,如果有自定义view,并且能够获取到文本,就覆盖 controller.navigationItem.title 获取到的值
    • $screen_name - String 类型,表示 ViewController 的类名

关于 AutoTrack 的更详细文档,请参考

3.2 记录激活事件

可以调用 trackInstallation: 方法记录激活事件,多次调用此方法只会触发一次激活事件(触发激活事件时会自动保存 $first_visit_time 首次访问时间属性到用户表)。

    // 记录 AppInstall 激活事件
    [[SensorsAnalyticsSDK sharedInstance] trackInstallation:@"AppInstall"];

调用上述代码,SDK 内部会触发一次 AppInstall 事件并设置 $first_visit_time 用户属性。

3.3 事件属性

每个事件可以设置多个事件属性,例如浏览商品事件中,将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中,事件属性可以作为统计过滤条件使用,也可以作为维度进行多维分析。对于事件属性,神策分析有一些约束:

  • 事件属性是一个 NSDictionary 对象
  • NSDictionary 中每个元素描述一个属性,Key 为属性名称,必需是 NSString 类型
  • NSDictionary 中,每个元素的 Value 是属性的值,支持 NSStringNSNumberNSSetNSDate,对于 NSSet,其中所有元素必须是 NSString 类型

对于神策分析中事件属性的更多约束,请参考 数据格式

3.3.1 SDK 默认属性

神策分析 SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为事件属性,详细的默认属性列表请参考文档 数据格式

3.3.2 事件公共属性

特别地,如果某个事件的属性,在所有事件中都会出现,可以通过 registerSuperProperties: 将该属性设置为事件公共属性。例如将应用名称作为事件的公共属性,设置方法如下:

    // 将'AppName'作为事件公共属性,后续所有 track: 追踪的事件都将设置 "AppName" 属性
    [[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#>"])

重复调用 registerSuperProperties: 会覆盖之前已设置的公共属性。
公共属性会保存在 App 本地缓存中。可以通过 unregisterSuperProperty: 删除一个公共属性,或使用 clearSuperProperties: 删除所有已设置的事件公共属性。
当公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖公共属性。
神策事件属性大小写敏感(详见数据格式),设置公共属性前需确保事件表中不存在仅大小写不同的同名属性,否则会导致所有事件因存在同名属性而不能入库。

注意:请在初始化 SDK 之后,立即调用 `registerSuperProperties:` 接口,确保每个事件都会添加已设置的公共属性。

3.4 事件时长

可以通过计时器统计事件的持续时间。首先,在事件开始时调用(1.10.6 及以后版本支持) trackTimerStart:@"Event" 记录事件开始时间,该方法并不会真正发送事件;在事件结束时,调用 trackTimerEnd:@"Event" withProperties:properties,SDK 会追踪 "Event" 事件,并自动将事件持续时间记录在事件属性 "$event_duration" 中。

1.11.6 版本开始,统计事件时长支持暂停和恢复,通过调用 trackTimerPause:@"Event"trackTimerResume:@"Event" 来分别实现暂停和恢复。

例如记录用户浏览商品页面的时间:

    // 进入商品页面,标记 ViewProduct 事件的启动时间
    [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"ViewProduct"];

    // ... 用户浏览商品

    // 离开商品页,记录 ViewProduct 事件,并在属性 $event_duration 中记录用户浏览商品的时间
    [[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:@"ViewProduct"
                                 withProperties:@{
                                                  @"ProductId" : PRODUCT_ID
                                                 }];

swift 代码示例:

    // 进入商品页面,标记 ViewProduct 事件的启动时间
    SensorsAnalyticsSDK.sharedInstance().trackTimerStart("ViewProduct")

    // ... 用户浏览商品

    // 离开商品页,记录 ViewProduct 事件,并在属性 $event_duration 中记录用户浏览商品的时间
    SensorsAnalyticsSDK.sharedInstance().trackTimerEnd("ViewProduct", withProperties: [ProductId:PRODUCT_ID])

多次调用 trackTimerStart:@"Event" 时,事件 "Event" 的开始时间以最后一次调用时为准。

4. 识别用户

在集成了神策分析 SDK 的 App 中,SDK 会为每个设备分配一个匿名 ID,用于标记产生事件的未登录用户,并以此进行用户相关分析,如留存率、事件漏斗等。

默认使用 IDFV 或 UUID 作为匿名 ID,如使用 1.9.10 之前的 SDK,当用户重新安装 App 时,匿名 ID 可能会发生变化。

1.9.10 之后的 iOS SDK,将匿名 ID 和 trackInstallation 标记位存储到 Keychain 上,解决卸载重装后,匿名 ID 可能变化及重复发送 trackInstallation 的问题。

1.10.18 之后的 SDK,如果项目中导入了 AdSupport 库,则 SDK 尝试获取 IDFA 作为匿名 ID;如果获取 IDFA 失败,则 SDK 尝试获取 IDFV 作为匿名 ID;如果获取 IDFV 失败,则会生成 UUID 作为匿名 ID。

注意:使用 IDFA 作为匿名 ID,需要添加 AdSupport.framework 库

通过 anonymousId 方法可获取神策分析 iOS SDK 分配的 匿名 ID

  //获取当前用户的匿名 ID
  NSString *anonymousId = [[SensorsAnalyticsSDK sharedInstance] anonymousId];

swift 代码示例:

  let  anonymousId:String = SensorsAnalyticsSDK.sharedInstance().anonymousId()

注意: 如果服务端做了埋点,需在用户注册/登录的时候将匿名 ID 传给服务端做用户 ID 关联。

4.1 匿名 ID 和登录 ID 关联

用户在登录前 ,SDK 会分配一个匿名 ID 来标识游客。当用户注册成功或登录成功时调用 login: 方法,传入对应的登录 ID ;匿名 ID 会与对应的登录 ID 进行关联,关联成功之后视为同一个用户。

调用时机:注册成功、登录成功 、初始化 SDK(如果能获取到登录 ID)都需要调用 login: 方法传入登录 ID。

注意:登录 ID 是指可以唯一标识一个用户的 ID,通常是业务数据库里的主键或其它唯一标识。
    //注册成功、登录成功、初始化SDK后  调用 login: 传入登录 ID
    [[SensorsAnalyticsSDK sharedInstance] login:@"你们服务端分配给用户具体的登录 ID"];

swift 代码示例:

    //注册成功、登录成功、初始化SDK后  调用 login: 传入登录 ID
    SensorsAnalyticsSDK.sharedInstance().login("你们服务端分配给用户具体的登录 ID")

注意,对同一个用户,login: 可调用多次,多次调用 login: 时,如果新设置的 登录 ID 与之前缓存的 登录 ID 相同,神策分析会忽略该次调用。

5. 设置用户属性

为了更准确地提供针对人群的分析服务,可以使用神策分析 SDK 的 set 对象设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件,精确分析特定人群的指标。

使用 set:set:to:,可以设定用户属性,例如:

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

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

swift 代码示例:

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

   //设置多个用户属性
   SensorsAnalyticsSDK.sharedInstance().set(["Age":18])

使用 unset: 可以删除特定的用户属性。

用户属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

5.1 记录初次设定的属性

对于只在首次设置时有效的属性,我们可以使用 setOnce:setOnce:to: 记录这些属性。与 set: 方法不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据,如果属性不存在则会自动创建。因此,setOnce: 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如:

    // 设定用户 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"])

5.2 数值类型的属性

对于数值型的用户属性,可以使用 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]
                                                               }];

swift 代码示例:

    SensorsAnalyticsSDK.sharedInstance().increment("GamePlayed", by: 1)

    SensorsAnalyticsSDK.sharedInstance().increment(["UserPaid":1,"PointEarned":5])

5.3 列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性,可以记录列表型属性,例如:

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

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

6. 高级功能

替换匿名 ID

如果需要替换神策默认分配的匿名 ID ,可以通过在初始化 SDK 之后立即调用 identify: 方法进行替换。例如:

// 例如,替换默认的匿名 ID 为: '9771C579-71F0-4650-8EE8-8999FA717761'
    [[SensorsAnalyticsSDK sharedInstance] identify:@"9771C579-71F0-4650-8EE8-8999FA717761"];

6.1 新增用户及渠道追踪

神策分析 SDK 提供渠道追踪功能,详情介绍请参考 《新增用户与渠道追踪》

6.2 打通 iOS App 与 H5

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

6.3 添加应用程序名称

神策分析 SDK 默认不采集应用程序的名称,如果想添加该属性,可直接获取应用程序名称,然后以公共属性的形式添加到事件中。具体操作如下:

    NSDictionary *infoDictionary = [[NSBundle mainBundle] infoDictionary];
    NSString *appCurName = [infoDictionary objectForKey:@"CFBundleDisplayName"];
    if (appCurName != nil) {
        [[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName": appCurName}];
    }

注意:请在开启自动采集( enableAutoTrack: )之前添加该属性,确保每个事件都会添加已设置的公共属性。

6.4 开启 crash 信息的自动采集

1.8.12 及以后的版本可通过调用 trackAppCrash 方法开启 crash 自动采集:

//开启 crash 信息自动采集
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:launchOptions];
options.enableTrackAppCrash = YES;
[SensorsAnalyticsSDK startWithConfigOptions:options];

6.5 获取预制属性

1.8.19 及以后的版本可以调用 getPresetProperties 方法获取预置属性:

   //获取预置属性
   NSDictionary * presetProperties = [[SensorsAnalyticsSDK sharedInstance] getPresetProperties];

6.6 开启屏幕方向属性的采集

1.10.1 及以后的版本可以通过 enableTrackScreenOrientation:方法开启屏幕方向属性的收集, 屏幕方向信息记录在事件的 $screen_orientation 属性中。

    // CoreMotion 采集屏幕方向
    [[SensorsAnalyticsSDK sharedInstance] enableTrackScreenOrientation:YES];

6.7 开启 GPS 信息采集

1.10.1 及以后的版本可以通过 enableTrackGPSLocation:方法,开启 GPS 信息采集, 经纬度信息记录在事件的 $longitude$latitude 属性中。

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

6.8 设置动态公共属性

1.10.8 及以后的版本可以通过 registerDynamicSuperProperties 方法设置动态公共属性,设置之后 SDK 会自动将设置的动态属性添加到触发的事件中。

    [[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary<NSString *,id> * _Nonnull{
        //比如 LoginManager 的 isLogin 方法是用于获取 App 当前的登录状态
        BOOL isLogin = [LoginManager isLogin];
        return @{@"isLogin":@(isLogin)};
    }];

6.9 删除本地存储的所有事件

1.10.8 及以后的版本可以通过 deleteAll 方法,删除 App 本地存储的所有事件。

    //删除 App 本地存储的所有事件
    [[SensorsAnalyticsSDK sharedInstance] deleteAll];

6.10 校验本地证书

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

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

     openssl x509 -in 你的证书.crt -out 你的证书.cer -outform der
    
  2. 将证书拖入项目中,选取相应 Target 并选择 Copy items if needed
  3. 配置神策 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;
    

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

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

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

7. 设置神策分析 SDK

当需要更精细地控制神策分析 SDK 的行为时,可以通过以下选项设置数据采集功能。

7.1 数据采集

在每次调用 track:login:set: 等方法的时,神策分析 SDK 会将事件与属性保存在 App 的存储空间中,并会检查如下条件,以判断是否向服务器上传数据:

  • 当前是否是 WIFI /3G/4G/5G 网络
  • 是否满足发送事件之一:
    1. 与上次发送的时间间隔是否大于 flushInterval
    2. 本地缓存的事件条目数是否大于 flushBulkSize

默认的 flushBulkSize 为 100 条,默认的 flushInterval 为 15 秒。满足条件后,神策分析 gzip 压缩后,批量发送到神策分析。

如果追求数据采集的时效性,可以调用 flush 方法,强制将数据发送到神策分析,例如:

    // 记录付费事件及订单金额属性
    [[SensorsAnalyticsSDK sharedInstance] track:@"OrderPaid" withProperties:@{@"Price" : [NSNumber numberWithFloat: 10.0]}];

    // 强制发送数据
    [[SensorsAnalyticsSDK sharedInstance] flush];

7.1.1 Flush Interval

神策分析 SDK 默认的 flushInterval 为 15 秒。可以设置 flushInterval 属性,修改事件发送时间间隔,注意时间单位为毫秒:

    // 设置发送时间间隔为 10 秒钟
    [SensorsAnalyticsSDK sharedInstance].flushInterval = 10 * 1000;

7.1.2 Flush Bulk Size

神策分析 SDK 默认的 flushBulkSize 为 100 条。可以设置 flushBulkSize 属性,修改事件发送的阈值。

    // 修改为每缓存 10 条数据,就发送一次
    [SensorsAnalyticsSDK sharedInstance].flushBulkSize = 10;

7.1.3 Flush Before Enter Background

在 App 进入后台状态前,神策分析 SDK 会将本地缓存的数据发送到神策分析。可以修改 flushBeforeEnterBackground 属性,关闭自动发送功能。

    // 关闭自动发送
    [SensorsAnalyticsSDK sharedInstance].flushBeforeEnterBackground = FALSE;

7.1.4 设置同步数据时的网络策略

神策分析 SDK 默认在 3G/4G/5G/WI-FI 环境下,SDK 都会尝试发送数据,可以通过调用 setFlushNetworkPolicy 接口修改网络策略(1.7.2及以后版本支持)。

    //网络模式选项
    // SensorsAnalyticsNetworkTypeNONE  所有状态都不发送数据
    // SensorsAnalyticsNetworkType2G    2G网络下发送数据
    // SensorsAnalyticsNetworkType3G    3G网络下发送数据
    // SensorsAnalyticsNetworkType4G    4G网络下发送数据
    // SensorsAnalyticsNetworkTypeWIFI  WIFI下发送数据
    // SensorsAnalyticsNetworkTypeALL   网络连通时发送数据

    [[SensorsAnalyticsSDK sharedInstance] setFlushNetworkPolicy:SensorsAnalyticsNetworkType3G |SensorsAnalyticsNetworkType4G | SensorsAnalyticsNetworkTypeWIFI];

7.1.5 设置本地缓存上限值

SDK 本地数据库默认缓存数据的上限值为 10000 条。 1.7.4 及以后的版本支持通过 setMaxCacheSize 方法来设定缓存数据的上限值。参数单位 条。

//设置本地数据缓存上限值为20000条
 [[SensorsAnalyticsSDK sharedInstance] setMaxCacheSize:20000];

当存储数量达到上限值,会依次丢弃老数据,保留最新的数据

7.1.6 关于 ARC

如果在非 ARC 的项目中使用神策分析 SDK ,需要在项目设置 "Build Phases" - "Compile Sources" 中将所有神策分析对应的资源文件添加 -fobjc-arc .

7.2 调试查看埋点数据

1.10.23及以后的版本, SDK 调试模式默认为关闭状态,需在代码中配置 scheme 后,通过扫描神策分析「设置调试模式」的二维码开启调试模式; 开启调试模式只针对当前扫码打开的 App 有效,如果 App 被强杀,下次打开 App, SDK 的调试模式恢复为关闭状态.

7.2.1 获取并配置 scheme

获取 scheme

使用 admin 账号,登录到神策分析相应的项目,点击右上角的账号,从「数据接入」页面获取 scheme 的值。

配置 scheme

点击项目 target 选择选项卡 Info,添加 URL Types,将第一步获取到的 scheme 配置到 URL Schemes 中。

7.2.2 处理 URL

在 AppDelegate.m 中的 - (BOOL)application:(UIApplication )app openURL:(NSURL )url options:(NSDictionary *)options 方法中 调用 handleSchemeUrl: 函数接收 URL

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url]) {
        return YES;
    }
    return NO;
}

7.2.3 用相机扫码,在 Safari 中打开 App,选择调试模式

在神策分析 v1.13 及之后版本中点击「设置设备调试模式」打开二维码。

二维码位置:「神策分析」——「埋点」——「导入实时查看」——「Debug 数据」——「设置设备调试模式」

扫码打开 App 时,会弹出提示,选择想要切换的调试模式。

开启调试模式(导入数据): 打开调试模式,校验数据,并将数据导入到神策分析中。

开启调试模式(不导入数据): 打开调试模式,仅校验数据,但不进行数据导入,数据最终不会进入到数据库。

7.2.4 导入实时查看

开启调试模式后,可以在神策分析 「埋点」→ 「导入实时查看」 点击「开始刷新」查看当前设备的调试数据上报情况

7.2.5 查看本地日志

开启调试模式后,也可以通过 Xcode 控制台查看输出的日志。过滤日志关键字为:SALog,一个事件有两条日志。 日志中如果出现 【track event】 字段, 说明此事件已触发,如果出现 【valid message】 字段,说明数据已同步到服务端。

8 预置属性

8.1 所有事件都会有的预置属性:

字段名称 类型 显示名 说明 版本
$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 时才会采集。

8.2 $AppStart(App 启动) 事件的预置属性

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

8.3 $AppEnd(App 退出) 事件的预置属性

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

8.4 $AppViewScreen(App 浏览页面) 事件的预置属性

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

8.5 $AppClick(App 元素点击) 事件的预置属性

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

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