iOS SDK 使用说明

最后更新于：2018-12-28 17:54:30

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

更新日志

1. 集成神策分析 SDK

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

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

• 安装 CocoaPods
• 在项目中新建 Podfile 文件，并添加：

    pod 'SensorsAnalyticsSDK'

其他集成方式：

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 服务，需获取的配置信息为:

• 数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
• 数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}

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

• 数据接收地址: http://{$host_name}:8106/sa?project={$project_name} （注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）

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

• 数据接收地址: http://{$host_name}:8106/sa?project={$project_name}

如果私有部署的过程中修改了 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_MODE 为 Debug 模式 选项。一旦成功初始化后，则可以通过 sharedInstance 获取 SDK 实例，进行用户行为事件或属性的追踪。

至此，我们已经可以正常使用神策分析 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 的控件（如 UIButton、 UISlider 等）、UITabBar、UIActionSheet 以及 UIAlertView 等控件
    • $element_type - String 类型，表示控件的类型
    • $element_content - String 类型，表示控件的内容
    • $title - String 类型，表示 ViewController 的标题，先读取controller.navigationItem.title，如果有自定义view，并且能够获取到文本，就覆盖 controller.navigationItem.title 获取到的值
    • $screen_name - String 类型，表示 ViewController 的类名
  • 继承于 UIScrollView 的控件（UITableView 和 UICollectionView）
    • $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 是属性的值，支持 NSString、NSNumber、NSSet 和 NSDate，对于 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 冲突时，事件属性优先级最高，它会覆盖事件公共属性。

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 的问题。

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

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

swift 代码示例：

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

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

4.1 用户注册

当一个用户 注册成功 或 登录成功 之后，可以通过 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 所有事件都会有的预置属性：

注意：

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

8.2 $AppStart（App 启动） 事件的预置属性

8.3 $AppEnd（App 退出） 事件的预置属性

8.4 $AppViewScreen（App 浏览页面） 事件的预置属性

8.5 $AppClick（App 元素点击） 事件的预置属性

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