1. 开启全埋点

全埋点，也叫无埋点、无码埋点、无痕埋点、自动埋点等。 全埋点，是指无需应用程序开发工程师写代码或者只写少量的代码，即可预先自动收集用户的所有或者绝大部分的行为数据，然后再根据实际的业务分析需求从中筛选出所 需行为数据并进行分析。

全埋点目前可以采集的事件有： AppStart（App 启动）、AppEnd（App 退出）、AppViewScreen（浏览页面） 和 AppClick（控件点击） 四种事件。

SDK初始化前，可通过配置HNBuildOptions实例的autoTrackEventType属性按需开启全埋点类型：

   /**
     * 可选项: 开启全埋点, 选择开启的全埋点类型，可根据需求进行组合
     * 支持四种全埋点类型: App启动、退出、元素点击、页面浏览
     */

    // 可依据需求组合开启
    options.autoTrackEventType =  HNAutoTrackAppStart |
                                    HNAutoTrackAppEnd |
                                  HNAutoTrackAppClick |
                                  HNAutoTrackAppScreen;

2. 用户关联

用户关联是为了对用户进行唯一标识，提高用户行为分析的准确性。

2.1 关联用户ID

当用户注册成功或者进行登录时，需要调用SDK 的用户登录接口：

     // 比如：登录手机号、登录邮箱 、用户唯一主键值
    [[HinaCloudSDK sharedInstance] setUserUId:@"<您平台用户唯一标识>"];

    // 为了准确记录登录用户的行为信息，建议在以下时机各调用一次用户登录接口：
    // · 用户在注册成功时
    // · 用户登录成功时
    // · 已登录用户每次启动 App 时

2.2 获取设备唯一ID

     // 如需获取设备唯一id，请在初始化SDK后调用
    [[HinaCloudSDK sharedInstance] deviceUId];

注意：如果 App 引入了 AdSupport 库，SDK 默认使用 IDFA 作为设备唯一 ID，使用 IDFA 能避免用户在重装 App 后设备 ID 发生变化的情况。若没有IDFA，SDK 会使用 IDFV，如果 IDFV 获取失败，则使用随机的 UUID，一般情况下都能够获取到 IDFV。如果使用 IDFV 或 UUID ，当用户卸载重装 App 时设备 ID 会变。

2.3 自定义设备唯一ID

    /**
     @abstract
     在初始化 SDK 之后立即调用，替换sdk分析默认分配的 *匿名 ID*

     @discussion
     一般情况下，如果是一个注册用户，则应该使用注册系统内的 user_id，调用 SDK 的 setUserUId: 接口。
     对于未注册用户，则可以选择一个不会重复的匿名 ID，如设备 ID 等
     如果没有调用此方法，则使用 SDK 自动生成的匿名 ID : deviceUId
     SDK 会自动将设置的 deviceUId 保存到文件中，下次启动时会从中读取
     重要:该方法在 SDK 初始化之后立即调用，可以自定义匿名 ID,不要重复调用。
     @param  当前用户的 deviceUId
     */

    [[HinaCloudSDK sharedInstance] deviceUId:@"123456"];

3. 用户属性

3.1 设置用户属性

用于直接设置用户的一个或者几个 userDict，建立用户模型。同一个 key 多次设置时，value 值会进行覆盖替换。

    [[HinaCloudSDK sharedInstance] set:@{

    }];

3.2 固定初始值的属性

对于需要保证只有首次设置时有效的属性，如用户首次注册地点、首次设置的用户昵称等，可以使用setOnce接口进行记录。后续设置已经存在的属性不会覆盖已有数据，如果设置不存在的属性则会自动创建：

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

3.3 数值类型的属性

同一个 key 多次设置时，value 值（数值类型）进行累加；常用于记录用户付费次数、付费额度、积分等属性。

    // 对单条属性累加
    [[HinaCloudSDK sharedInstance] add:@"my_level" by:[NSNumber numberWithInt:1]];
    // 对多条属性累加
    [[HinaCloudSDK sharedInstance] add:@{
        @"my_level":[NSNumber numberWithInt:1],
        @"my_golds":[NSNumber numberWithInt:23]
    }];

3.4 属性取消

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

    // 取消用户的Level属性
    [[HinaCloudSDK sharedInstance] unset:@"Level"];

3.5 清空用户属性

如果想要删除当前这个用户的所有记录，可以调用-deleteUser：

    [[HinaCloudSDK sharedInstance] deleteUser];

4. 自定义埋点

4.1 自定义埋点

    [[HinaCloudSDK sharedInstance] track:@"WatchVideo"
                          withProperties:@{@"VideoID":[NSNumber numberWithInt:756487],
                                           @"VideoName":@"Lord of the Rings",
                                           @"IsFree":@(YES)}];

4.2 统计埋点事件时长

需要成对调用计时器的开始、结束等方法，以此来实现对统计时长的事件采集：

    // 开始播放电影
    [[HinaCloudSDK sharedInstance] trackTimerStart:@"WatchMovie"];
    // 暂停播放
    [[HinaCloudSDK sharedInstance] trackTimerPause:@"WatchMovie"];
    // 恢复播放
    [[HinaCloudSDK sharedInstance] trackTimerResume:@"WatchMovie"];
    // 结束播放
    [[HinaCloudSDK sharedInstance] trackTimerEnd:@"WatchMovie" withProperties:@{@"MovieType":@"classical"}];

注意：
- 只有调用 - trackTimerEnd: 时，SDK 才会真正记录事件
- 多次调用 - trackTimerStart:，以最后一次调用作为计时起点
- 默认情况下，统计的时长不包括用户 App 在后台的时长

5. 事件属性

在进行埋点事件追踪时，您可以根据需求对埋点事件进行属性的定义。目前 SDK 中提供了公共属性用于给每个埋点事件添加属性。

5.1 设置事件公共属性

公共属性是指对于所有事件都需要添加的属性，设置之后 SDK 会在每次触发埋点时，自动获取并添加到触发的事件中。

    // 设置事件公共属性
    [[HinaCloudSDK sharedInstance] registerCommonProperties:^NSDictionary<NSString *,id> * _Nonnull{
        return @{@"level": @"3",
                 @"balance": @"5642"};
    }];

5.2 获取预置属性

如需了解和使用预置属性，可以通过此方法获取预置属性。

    // 获取sdk预置的属性
    [[HinaCloudSDK sharedInstance] getPresetProperties];

6. 数据存储与发送

6.1 上报条件

iOS SDK 每次触发事件时会检查如下条件，以判断是否向服务器上传数据:

1. 当前网络是否符合 flushNetworkPolicy (默认 3G、4G、5G、WiFi)
2. 与上次发送的时间间隔是否大于 flushInterval (默认 15 秒)
3. 本地缓存的事件条目数是否大于 flushPendSize (默认 100 条)

只有1、2 或1、3 满足时，SDK 才会进行发送数据。以上参数支持自定义，可以通过修改相应参数值来达到控制事件上报的频率：

    HNBuildOptions *ops = [[HNBuildOptions alloc] initWithServerURL:@"<数据接收地址>" launchOptions:launchOptions];

    // 设置触发间隔，默认 15 * 1000 毫秒
    ops.flushInterval = 10 * 1000;

    // 设置触发条数，默认 100 条
    ops.flushPendSize = 50;

    // 设置上报网络策略，默认 3G、4G、5G、WiFi
    ops.flushNetworkPolicy = HNNetworkTypeALL;

    [HinaCloudSDK startWithConfigOptions:ops];

6.2 立即上报（强制上报）

特殊场景需要立即上报的，可以在事件触发后调用 - flush：

    [[HinaCloudSDK sharedInstance] flush];

6.3 本地数据缓存上限值

如果一直不满足上报条件，本地缓存的事件量达到 maxCacheSize 时，每次再触发新的事件，SDK 会依次丢弃老数据，保留最新的数据。maxCacheSize支持自定义，默认10000条：

    ops.maxCacheSize = 15000;

6.4 清空本地缓存事件

为适应 GDPR 要求，SDK 可调用 - clear 方法用于清空本地缓存的全部事件：

    // 删除本地缓存的全部事件，请慎用！
    [[HinaCloudSDK sharedInstance] clear];

7. 全埋点高级控制

全埋点也称自动埋点、无痕埋点，目前SDK支持的全埋点有 App 启动、App 退出、浏览页面和控件点击 四种事件。

7.1 开启子页面浏览事件自动采集

在 SDK初始化 前，通过 HNBuildOptions 实例的 enableAutoTrackChildViewScreen 属性开启自动采集子页面的浏览事件：

    options.enableAutoTrackChildViewScreen = YES;

7.2 自动采集事件的忽略补充

SDK开启全埋点后，SDK 支持通过配置忽略部分页面或控件的采集。

7.2.1 忽略某个控件的点击事件

    button.hinaDataIgnoreView = YES;

7.2.2 忽略某类控件的点击事件

    // 支持多次调用, 对合集进行忽略
    [[HinaCloudSDK sharedInstance] disableViewType:[HNButton class]];
    [[HinaCloudSDK sharedInstance] disableViewType:[HNView class]];

7.2.3 忽略页面的浏览事件

    // 可多次调用,对合集进行忽略
    [[HinaCloudSDK sharedInstance] disableAutoTrackViewControllers:@[@"DemoViewController",@"HNBaseViewController"]];

7.2.4 手动触发页面的点击事件

    // 可在 viewDidAppear 中触发此操作
    [[HinaCloudSDK sharedInstance] trackViewScreen:[UIViewController new]];

8. 其他功能

8.1 开启屏幕方向的自动采集

可以在初始化 SDK 后调用 - enableTrackScreenOrientation: 进行开启，开启后的屏幕方向信息记录在事件的 H_screen_orientation 属性中：

    [[HinaCloudSDK sharedInstance] enableTrackScreenOrientation:YES];

8.2 开启采集页面浏览时长

SDK 支持自动采集在离开页面时发送页面离开事件（H_AppPageLeave）来采集页面浏览时长，在初始化 SDK 前，通过 HNBuildOptions 实例的 enableTrackPageLeave 属性开启页面浏览时长事件采集：

// 开启页面离开事件采集
options.enableTrackPageLeave = YES;

8.3 开启位置信息的自动采集

SDK支持自动采集GPS信息，可以在SDK初始化后调用 enableTrackGPSLocation 方法进行开启，采集后的经纬度信息会乘以10⁶后记录在 H_longitude、H_latitude 属性中：

    [[HinaCloudSDK sharedInstance] enableTrackGPSLocation:YES];

注意：如果app业务中未开启定位权限，针对审核问题，开启此项功能后需在plist文件中添加相关用途说明。

8.4 开启Crash信息的自动采集

说明：初始化 SDK 时，通过如下配置，即可开启App Crash信息的采集。
SDK 默认关闭 Crash 信息采集，开启采集后，App Crash 时，会触发 AppCrashed 事件，堆栈信息记录在 app_crashed_reason 属性中。

    HNBuildOptions *options = [[HNBuildOptions alloc] initWithServerURL:kAppServerURL launchOptions:launchOptions];
    options.enableTrackAppCrash = YES;
    [HinaCloudSDK startWithConfigOptions:options];

8.5 开启推送点击事件的自动采集

在SDK初始化 前，通过 HNBuildOptions 实例的 enablePushAutoTrack 属性开启推送点击事件的自动采集：

    options.enablePushAutoTrack = YES;

      // 如需设置推送唯一id，请在初始化SDK后调用
    [[HinaCloudSDK sharedInstance] userPushKey:@"###" pushId:@"###"];

8.6 开启 App 与 H5打通功能

所谓打通，是指 H5 集成 JavaScript 数据采集 SDK 后，H5 触发的事件不是直接同步给服务端，而是先发给 App 端的数据。

采集 SDK，经 App 端数据采集 SDK 二次加工处理后入本地缓存再进行同步。

这样设计的目的主要是从以下几个角度考虑：
1、数据丢失率；
2、数据准确性；
3、用户标识。

初始化 SDK 时，进行如下配置，即可开启 App 打通 H5 功能：

    options.enableJSBridge = YES;

8.7 日志开关

#ifdef DEBUG
    // 开启 Log，可方便开发时进行调试
    options.enableLog = YES;
#endif

然后在 IDE (如 Xcode )日志控制台中筛选 SALog 关键词：

埋点事件触发成功时，SDK 会输出 【track event】 开头的事件数据；
埋点事件触发失败时，SDK 会输出相应的错误原因；
事件数据上报成功时，SDK 会输出 【valid message】字段开头的事件数据；
事件数据上报失败时，SDK 会输出 【invalid message】 字段开头的事件数据并输出错误原因。

8.8 禁用SDK

    // 禁用 SDK，默认为 NO
    // 禁用后，SDK 将不会触发事件，也不会发送网络请求
    // 在某些情形如应用审核期间，可以结合服务器开关配合使用此功能，提高审核通过率
    options.disableSDK = NO;

8.9 设置属性值长度

说明：属性值value的长度支持自定义，SDK默认限制属性value长度为1024，支持设置的有效长度为1024~5120，超出设置的阈值，SDK会做截断处理。

options.maxPropertyValueLength = 3000;