iOS SDK 使用说明

最后更新于:2018-12-18 17:48:11

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

更新日志

1. 集成神策分析 SDK

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

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

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

其他集成方式:

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

1.10.18 之后版本,如果 App 引入了 adsupport 库,SDK 默认使用 IDFA 做为匿名 ID,之前版本通过 pod 'SensorsAnalyticsSDK', :subspecs => ['IDFA'] 开启匿名 ID 使用 IDFA 功能。

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

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

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

如果不想通过 CocosPod 进行集成,也可以从 Github 获取 SDK 的源代码,并添加进项目使用。需要注意的是,如果通过这种方式使用神策分析 SDK,需要在项目设置 "Build Phase" - "Link Binary With Libraries" 中添加依赖库:libicucore、libsqlite3 和 libz。

注: 如果执行

pod update

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

pod cache clean SensorsAnalyticsSDK

2. 初始化神策分析 SDK

2.1 获取配置信息

首先从神策分析系统中,获取数据接收和配置分发的 URL。

如果使用神策分析 Cloud 服务,需获取的配置信息为:

如果用户使用单机版私有部署的神策分析,默认的配置信息为:

如果用户使用集群版私有部署的神策分析,默认的配置信息为:

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

2.2 在 Objective-C 中使用

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

    // 引入神策分析 SDK
    #import "SensorsAnalyticsSDK.h"

    // 数据接收的 URL
    #define SA_SERVER_URL @"YOUR_SERVER_URL"
    // Debug 模式选项
    //   SensorsAnalyticsDebugOff - 关闭 Debug 模式
    //   SensorsAnalyticsDebugOnly - 打开 Debug 模式,校验数据,但不进行数据导入
    //   SensorsAnalyticsDebugAndTrack - 打开 Debug 模式,校验数据,并将数据导入到神策分析中
    // 注意!请不要在正式发布的 App 中使用 Debug 模式!
    #define SA_DEBUG_MODE SensorsAnalyticsDebugOff

    // 初始化 SDK
    [SensorsAnalyticsSDK sharedInstanceWithServerURL:SA_SERVER_URL
                                        andLaunchOptions:launchOptions
                                        andDebugMode:SA_DEBUG_MODE];

    // 设置公共属性示例代码
    [[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"appName": @"appName"}];
    [[SensorsAnalyticsSDK sharedInstance] enableTrackScreenOrientation:YES]; // CoreMotion 采集屏幕方向
    [[SensorsAnalyticsSDK sharedInstance] enableTrackGPSLocation:YES];// CoreLocation 采集 GPS 信息

swift 代码示例:

SensorsAnalyticsSDK.sharedInstance(withServerURL: SA_SERVER_URL, andLaunchOptions:launchOptions, andDebugMode: SensorsAnalyticsDebugMode.andTrack)

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

注意:不要在正式发布的 App 中使用 Debug 模式!

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

3. 追踪事件

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

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

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

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

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

    // 记录浏览商品事件,并将商品ID、商品类别和是否被添加进收藏夹作为事件属性上传
    [[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"]];   // 产品列表

    // 记录浏览商品事件,并将商品ID、商品类别和是否被添加进收藏夹作为事件属性上传
    [[SensorsAnalyticsSDK sharedInstance] track:@"PaidOrder"
                                 withProperties:@{
                                                  @"OrderPaid" : [NSNumber numberWithFloat:orderPaid],
                                                  @"OrderList" : orderList
                                                  }];

swift 代码示例:

    // 记录浏览商品事件,并将商品ID、商品类别和是否被添加进收藏夹作为事件属性上传
    SensorsAnalyticsSDK.sharedInstance().track("ViewProduct", withProperties:
                                            ["ProductID":123456,                // 获取商品ID
                                             "ProductCatalog":"Laptop Computer",// 获取商品类别
                                             "IsAddedToFav":false])             // 是否被添加到收藏夹

通过 Debug模式,可以校验追踪的事件及属性是否正确。普通模式下,数据导入后,在神策分析中稍等片刻,便能看到追踪结果。请注意,不要在正式发布的 App 中使用 Debug 模式

3.1 Auto Track

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

    // 打开自动采集, 并指定追踪哪些 AutoTrack 事件
    [[SensorsAnalyticsSDK sharedInstance] enableAutoTrack:SensorsAnalyticsEventTypeAppStart |
     SensorsAnalyticsEventTypeAppEnd |
     SensorsAnalyticsEventTypeAppViewScreen |
     SensorsAnalyticsEventTypeAppClick];

swift 代码示例:

SensorsAnalyticsSDK.sharedInstance().enableAutoTrack([.eventTypeAppStart,.eventTypeAppEnd,.eventTypeAppViewScreen,.eventTypeAppClick])

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

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

    • 继承于 UIControl 的控件(如 UIButtonUISlider 等)、UITabBarUIActionSheet 以及 UIAlertView 等控件
      • $element_type - String 类型,表示控件的类型
      • $element_content - String 类型,表示控件的内容
      • $title - String 类型,表示 ViewController 的标题,先读取controller.navigationItem.title,如果有自定义view,并且能够获取到文本,就覆盖 controller.navigationItem.title 获取到的值
      • $screen_name - String 类型,表示 ViewController 的类名
    • 继承于 UIScrollView 的控件(UITableViewUICollectionView
      • $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 浏览页面时(切换 ViewController),会自动记录记录 $AppViewScreen 事件,事件属性:

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

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

3.2 事件属性

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

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

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

3.2.1 SDK 默认属性

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

3.2.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 冲突时,事件属性优先级最高,它会覆盖事件公共属性。

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

3.3 事件时长

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

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

    // 进入商品页面,标记 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,用于标记产生事件的未登录用户,并以此进行用户相关分析,如留存率、事件漏斗等。1.10.18 之后的 SDK,如果项目中导入了 AdSupport 库,则 SDK 尝试获取 IDFA 作为匿名 ID;如果获取 IDFA 失败,则 SDK 尝试获取 IDFV 作为匿名 ID;如果获取 IDFV 失败,则会生成 UUID 作为匿名 ID。

使用 IDFV 或 UUID 作为匿名 ID,当用户重新安装 App 时,如使用 1.9.10 之前的 SDK,匿名 ID 可能会发生变化。1.9.10 之后的 iOS SDK,将匿名 ID 和 trackInstallation 标记位存储到 Keychain 上,解决卸载重装后,匿名 ID 可能变化及重复发送 trackInstallation 的问题。

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

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

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

swift 代码示例:

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

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

4.1 用户注册

(1.6.24及以后的版本才支持login和logout方法)

当一个用户 注册成功登录成功 之后,可以通过 login: 方法设置用户的 登录 ID ,并将 匿名 ID登录 ID 进行关联,以保证用户分析的准确性。例如:

    // 记录用户打开首页,此时的 DistinctId 为神策分析 SDK 随机分配的 ID,例如 IDFV: "9771C579-71F0-4650-8EE8-8999FA717761"
    // 这只是一个示例,用户可根据实际需求添加事件
    [[SensorsAnalyticsSDK sharedInstance] track:@"ViewHomepage"];

    // 关联 DistinctId(匿名 ID),神策分析将 "9771C579-71F0-4650-8EE8-8999FA717761" 与 "developer@sensorsdata.cn" 关联,并认为两个 DistinctId 为同一个用户
    [[SensorsAnalyticsSDK sharedInstance] login:@"developer@sensorsdata.cn"];

    // 记录用户打开商品详情页,此时被追踪的事件的 DistinctId 为 "developer@sensorsdata.cn"
    // 这只是一个示例,用户可根据实际需求添加事件
    [[SensorsAnalyticsSDK sharedInstance] track:@"ProductDetailView"];

swift 代码示例:

    // 关联 DistinctId(匿名 ID),神策分析将 "9771C579-71F0-4650-8EE8-8999FA717761" 与 "developer@sensorsdata.cn" 关联,并认为两个 DistinctId 为同一个用户
    SensorsAnalyticsSDK.sharedInstance().login("developer@sensorsdata.cn")

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

5. 设置用户属性

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

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

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

    // 设定用户年龄属性 "Age" 为 18
    // `set:` 方法设定一个或多个用户属性
    [[[SensorsAnalyticsSDK sharedInstance] people] 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: 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如:

    // 设定用户渠道为,"developer@sensorsdata.cn" 的 "AdSource" 属性值为 "App Store"
    [[[SensorsAnalyticsSDK sharedInstance] people] setOnce:@"AdSource" to:@"App Store"];

    // 再次设定用户渠道,设定无效,"developer@sensorsdata.cn" 的 "AdSource" 属性值仍然是 "App Store"
    [[[SensorsAnalyticsSDK sharedInstance] people] 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] people] increment:@"GamePlayed" by:[NSNumber numberWithInt:1]];

    // 增加用户付费次数和积分
    // `increment:` 对一个或多个属性进行累加
    [[[SensorsAnalyticsSDK sharedInstance] people] 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] people] append:@"Movies" by:[NSSet setWithArray:@[@"Sicario", @"Love Letter"]]];

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

swift 代码示例:

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

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

6. 高级功能

6.1 新增用户及渠道追踪

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

6.2 打通 iOS App 与 H5

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

6.3 替换默认匿名id

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

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

6.4 添加应用程序名称

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

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

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

6.5 开启 crash 信息的自动采集

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

   //开启 crash 信息自动采集
   [[SensorsAnalyticsSDK sharedInstance] trackAppCrash];

6.6 获取预制属性

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

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

6.7 设置动态公共属性

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

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

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

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

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

7. 设置神策分析 SDK

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

7.1 数据采集

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

  • 当前是否是 WIFI / 3G / 4G 网络
  • 是否满足发送事件之一:
    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/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 方法来设定缓存数据的上限值。参数单位 条。

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

7.1.6 Debug 模式下,关闭提示框

1.6.36 及以后版本 Debug 模式下,数据出错时默认会以提示框的方式提示开发者。

1.6.38 及以后版本 Debug 模式下,默认最多弹出 3 个提示框,用户可调用 showDebugInfoView: 方法关闭提示框。

     //关闭弹出框
    [[SensorsAnalyticsSDK sharedInstance] showDebugInfoView:NO];

7.1.7 关于 ARC

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

7.2 调试日志

默认情况下,神策分析 SDK 只会输出错误日志 和 Debug 模式的提示信息。若开发者需要调试神策分析 SDK,可以开启调试日志功能,具体操作如下:

1、对于直接使用神策分析 SDK 源代码的开发者,可以在编译选项 Preprocessor Macros 中定义选项 SENSORS_ANALYTICS_ENABLE_LOG=1 打开调试日志。

2、使用 Cocoapods 的开发者,推荐使用pod 'SensorsAnalyticsSDK', :subspecs => ['LOG'] 集成方式开启,或者在 Pod 的 SensorsAnalyticsSDK 中添加上述选项,如下图:

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 。