1. 开启全埋点（自动采集）

SDK 可以自动采集一些用户行为，如 App 启动、退出、浏览页面、控件点击，共计四种。

说明：在初始化时，通过setAutoTrackEventType进行配置开启，不配置则视为关闭全埋点。

  /**
    * 开启全埋点，默认关闭
    */
    //比如：开启全部类型
builder.setAutoTrackEventType(IAutoTrackEventType.APP_CLICK |
                        IAutoTrackEventType.APP_START |
                        IAutoTrackEventType.APP_END |
                        IAutoTrackEventType.APP_VIEW_SCREEN);

2. 用户关联

2.1 关联用户ID

当用户注册成功或登录成功时，需要调用 SDK 的 setUserUId() 方法。

HinaCloudSDK.getInstance().setUserUId("您平台用户唯一标识");// 比如：登录手机号、登录邮箱 、用户唯一主键值

注意：为了准确记录登录用户的行为信息，建议在以下时机各调用一次用户登录方法：

· 用户在注册成功时
· 用户登录成功时
· 已登录用户每次启动 App 时

2.2 获取设备唯一ID

说明：如需获取设备唯一id，请在初始化SDK后调用getDeviceUId()方法进行获取。

HinaCloudSDK.getInstance().getDeviceUId();

2.3 自定义设备唯一ID

说明：默认情况下，SDK 会生成设备唯一ID 并可以保证该ID的唯一性，如需替换SDK默认分配的，配置如下；

//初始化时配置
builder.setDeviceUId(String deviceUId)

//或者在初始化后，通过API配置
HinaCloudSDK.getInstance().setDeviceUId(xxx);

注意： SDK 默认使用 AndroidId 作为设备 ID，如果 AndroidId 获取不到则获取随机的 UUID。

3. 用户属性

3.1 设置用户属性

说明：同一个 key 多次设置时，会进行覆盖，value 值只会记录最后设定的值。

HinaCloudSDK.getInstance().userSet(String key, Object value);
// 或
HinaCloudSDK.getInstance().userSet(JSONObject properties);

3.2 固定初始值的属性

说明：同一个 key 多次设置时，不会进行覆盖，value 值只会记录初次设定的值。

HinaCloudSDK.getInstance().userSetOnce(String key, Object value);
// 或
HinaCloudSDK.getInstance().userSetOnce(JSONObject properties);

3.3 数值类型的属性

说明：同一个 key 多次设置时，value 值（数值类型）进行求和计算。

HinaCloudSDK.getInstance().userAdd(String key, Number value)
// 或者使用JSONObject，注意此情况下 JSONObject 里面的 value 值需要是数值类型；
HinaCloudSDK.getInstance().userAdd(JSONObject properties)

3.4 属性取消

说明：取消已设置的某个用户属性。

HinaCloudSDK.getInstance().userUnset(String key);

3.5 清空用户属性

说明：清空当前用户的用户属性。

HinaCloudSDK.getInstance().userDelete();

4. 自定义埋点

用于记录埋点事件。

4.1 自定义埋点

说明：使用track()方法进行直接埋点，埋点事件支持添加自定义属性。

//直接埋点，不含自定义属性，比如：点击“开始阅读”按钮；
HinaCloudSDK.getInstance().track("novel_read_btn_click");

//直接埋点，添加自定义属性，比如：点击“开始阅读”按钮，添加属性：小说id、小说的章节；
try {
    JSONObject properties = new JSONObject();
    properties.put("novel_id", "1234567890");
    properties.put("novel_chapter", "3");
    HinaCloudSDK.getInstance().track("novel_read_btn_click", properties);
} catch (JSONException e) {
    e.printStackTrace();
}

4.2 自定义时长埋点

说明：需要成对调用计时器的开始和结束方法，以此来实现对统计时长的事件采集；
*在事件开始时，调用trackTimerStart("event1")，该方法并不会真正发送事件；
*在事件结束时，调用trackTimerEnd("event1", properties)，SDK 会触发事件，并自动将事件持续时间记录在事件属性 “event_duration” 中。

// 比如：开始观看视频;
HinaCloudSDK.getInstance().trackTimerStart("watch_video");

// 比如：结束观看视频；
try {
  JSONObject properties = new JSONObject();
  properties.put("video_id", "1234567890");//添加自定义属性
  properties.put("video_type", "娱乐");//添加自定义属性
  // 调用 trackTimerEnd 方法，会触发事件，并在属性 event_duration 中记录时长；
  HinaCloudSDK.getInstance().trackTimerEnd("watch_video", properties);
} catch (JSONException e) {
  e.printStackTrace();
}

5 事件属性

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

5.1 设置公共属性

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

HinaCloudSDK.getInstance().registerCommonProperties(new ICommonProperties() {
            @Override
            public JSONObject getCommonProperties() {
                try {
                    JSONObject jsonObject = new JSONObject();
                    jsonObject.put("appName", PackageUtils.getAppName());
                    jsonObject.put("isLogin", UserUtils.isLogin());
                    return jsonObject;
                } catch (Exception e) {
                    e.printStackTrace();
                }
                return null;
            }
        });

5.2 获取预置属性

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

JSONObject jsonObject = HinaCloudSDK.getInstance().getPresetProperties()

6. 数据存储与发送

SDK上报数据的方式分为：实时上报和批量上报；

• 实时上报：如果追求数据采集的时效性，可以在部分关键埋点后，调用 flush() 方法，强制将数据上报到服务器；

• 批量上报：为了减少性能和电量损耗，在事件触发后不会立即上报，而是先将事件缓存在本地，然后定时、批量进行上报。

在每次调用 track()、setUserUId()、userSet() 等方法时，SDK 会将埋点事件保存在数据库中，并会检查如下条件，判断是否向服务器上传数据。满足条件后，SDK 会将数据 gzip 压缩后，批量发送到服务器。

1.是否是 WIFI/2G/3G/4G/5G 网络条件
2.是否满足发送条件之一:
    a.与上次发送的时间间隔是否大于 flushInterval
    b.本地缓存日志数目是否大于 flushPendSize
    c.事件类型为 setUserUId() 方法触发的 H_SignUp 事件

注意：在 App 进入后台状态或监听到网络切换有网络时，SDK 会调用 flush() 方法，将缓存的数据发送到服务器。

6.1 上报条件

6.1.1 缓存条数

说明：设置本地缓存的最大条数，默认为 100 条。

//初始化时配置
builder.setFlushPendSize(int size);//最少50条。

//或者在初始化后，通过API配置
HinaCloudSDK.getInstance().setFlushPendSize(xxx);

6.1.2 发送间隔

说明：设置埋点数据发送的间隔时间，默认为 15s。

//初始化时配置
builder.setFlushInterval(int interval);//最小 5 秒，单位毫秒。

//或者在初始化后，通过API配置
HinaCloudSDK.getInstance().setFlushInterval(xxx);

6.1.3 设置数据的网络上传策略

说明：默认情况下，在 WIFI/3G/4G/5G 网络条件下，SDK 都会尝试去同步数据。可以自由组合来指定发送数据的网络策略。

//初始化时配置
builder.setNetworkTypePolicy(ISendNetworkType.TYPE_2G
                        | ISendNetworkType.TYPE_3G
                        | ISendNetworkType.TYPE_4G
                        | ISendNetworkType.TYPE_WIFI
                        | ISendNetworkType.TYPE_5G);

//或者在初始化后，通过API配置；
HinaCloudSDK.getInstance().setFlushNetworkPolicy(xxx);

6.2 立即上报（强制上报）

说明：如果追求数据采集的时效性，调用flush()，即可立即执行上报。

HinaCloudSDK.getInstance().flush();

注意：在 App 进入后台状态或监听到网络切换有网络时，SDK 会调用 flush() 方法，将缓存的数据发送。

6.3 本地数据缓存上限值

说明：SDK 本地数据库默认缓存数据的上限值为 32MB。

//初始化时配置
builder.setMaxCacheSize(long maxCacheSize)//最小 16MB（16 * 1024 * 1024），单位 byte；

//或者在初始化后，通过API配置；
HinaCloudSDK.getInstance().setMaxCacheSize(xxx);

注意：当存储数量达到上限值，会依次丢弃老数据，保留最新的数据。

6.4 清空本地缓存事件

说明：删除 App 本地存储的所有事件。

HinaCloudSDK.getInstance().clear();

注意：如果不是特殊要求，请不要调用此方法。

6.5 使用自签证书

说明：初始化 SDK 时，通过 setSSLSocketFactory() 方法设置自签证书，设置自签证书后，SDK 内所有的 HTTPS 请求会进行此接口设置的证书校验。

builder.setSSLSocketFactory(SSLSocketFactory sslSocketFactory)

7. 全埋点高级控制

SDK 可以自动采集一些用户行为，如 App 启动、退出、浏览页面、控件点击，共计四种。

7.1 关闭和重启全埋点

说明：在初始化时，通过setAutoTrackEventType进行配置开启，不配置则视为关闭全埋点。

//忽略指定类型的全埋点事件（Integer对应四种自动采集的事件常量）
HinaCloudSDK.getInstance().disableAutoTrackEventType(List<Integer> list)

//重启被忽略的全埋点事件（Integer对应四种自动采集的事件常量）
HinaCloudSDK.getInstance().enableAutoTrackEventType(List<Integer> list)

注意：fragment页面采集需要单独开启和配置，具体详见【7.3 fragment全埋点控制】；

7.2 activity全埋点控制

说明：通过 ignoreAutoTrackActivity() 方法可以忽略某个或某些 Activity 的 App 点击事件与 App 页面浏览事件(包含所属 Fragment)。同时也可以通过 resumeAutoTrackActivities() 方法恢复被忽略的页面。

//忽略单个、多个 Activity
HinaCloudSDK.getInstance().ignoreAutoTrackActivities(List<Class<?>> activitiesList);

//恢复被忽略的 Activity
HinaCloudSDK.getInstance().resumeAutoTrackActivities(List<Class<?>> activitiesList);

7.3 fragment全埋点控制

说明：通过 trackFragmentAppViewScreen() 方法可以开启全部 Fragment 页面浏览事件的自动采集功能。

//初始化 SDK 之后，开启自动采集 Fragment 页面浏览事件
HinaCloudSDK.getInstance().trackFragmentAppViewScreen();

//开启后，指定 Fragment采集
HinaCloudSDK.getInstance().enableAutoTrackFragment(Class<?> fragment);

//开启后，忽略单个、多个Fragment采集
HinaCloudSDK.getInstance().ignoreAutoTrackFragments(List<Class<?>> fragmentList);

//开启后，对被忽略的 Fragment恢复采集
HinaCloudSDK.getInstance().resumeIgnoredAutoTrackFragments(List<Class<?>> fragmentList);

注意：enableAutoTrackFragment() 方法用于采集指定的 Fragment 页面，ignoreAutoTrackFragment() 方法用于忽略指定的 Fragment 页面。当二者设置同时存在时，以 enableAutoTrackFragment() 方法设置的为准，ignoreAutoTrackFragment() 方法设置的信息不再生效。

7.4 view全埋点控制

说明：view全埋点采集控制，支持某个view或某类view忽略；

//通过 ignoreView() 方法可以忽略某个 View 对象的 App 点击事件
HinaCloudSDK.getInstance().ignoreView(View view);

//通过 ignoreViewType() 方法可以忽略某种控件类型及其子类型的 App 点击事件
HinaCloudSDK.getInstance().ignoreViewType(Class<?> viewType);

7.5 页面设置自定义属性

说明：通过 IScreenAutoTracker 接口可以给页面设置自定义属性或修改预置属性的取值；实现该接口的类需要是页面对应的 Activity 类或者 Fragment 类；在 IScreenAutoTracker 接口 getPageCustomProperties() 方法返回的 JSONObject 中，可以通过设置 H_title、H_screen_name 属性来替换 SDK 默认采集 Activity 和 Fragment 类页面标题和页面名称。

public interface IScreenAutoTracker {

    String getPageUrl();

    JSONObject getPageCustomProperties() throws JSONException;
}

8. 其他功能

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

说明：初始化 SDK 时，进行如下配置，即可开启屏幕方向属性的收集，屏幕方向信息记录在事件的 H_screen_orientation 属性中。

builder.enableTrackScreenOrientation(boolean enable);

注意：该接口开启后会读取手机传感器信息，请根据合规需要进行说明。

8.2 开启采集页面浏览时长

说明：SDK 支持自动采集页面离开事件（H_AppPageLeave），来采集页面浏览时长。在初始化 SDK 时，使用enableTrackPageLeave()方法配置开启。

/**
* isTrackPageLeave: 是否采集 Activity 页面离开事件
* isTrackFragmentPageLeave: 是否采集 Fragment 页面离开事件
**/
builder.enableTrackPageLeave(boolean isTrackPageLeave, boolean isTrackFragmentPageLeave);

8.3 设置和清除位置信息

说明：通过 setGPSLocation() 方法，把第三方定位获取到的经纬度信息设置给 SDK，设置之后经纬度信息记录在事件的 H_longitude、H_latitude 属性中。清除位置信息调用 clearGPSLocation() 方法进行清除。

//设置经纬度
HinaCloudSDK.getInstance().setGPSLocation(double latitude, double longitude)

//清除位置信息
HinaCloudSDK.getInstance().clearGPSLocation()

8.4 开启Crash信息的自动采集

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

builder.enableTrackAppCrash();

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

说明：初始化 SDK 时，进行如下配置。

//传入 true 代表开启推送点击事件自动采集
builder.enablePushAutoTrack(boolean enable)

注意：如需设置推送唯一id，请在初始化SDK后调用HinaCloudSDK.getInstance().setPushUId(String pushTypeKey, String pushUId)

8.6 开启App与H5打通功能

说明：初始化 SDK 时，进行如下配置。

builder.enableJSBridge(boolean enable);

注意：需要设置JS开启webView.getSettings().setJavaScriptEnabled(true);

8.7 日志开关

说明：初始化 SDK 时，进行如下配置。

builder.enableLog(boolean enable)

8.8 禁用SDK

说明：初始化 SDK 时，进行如下配置。

builder.disableSDK(boolean disableSDK);

8.9 属性值长度

说明：初始化 SDK 完成后，进行如下配置，可以自定义属性值（string.length）长度，SDK默认限制1024，自定义最大不要超过5120；

HinaCloudSDK.getInstance().setLimitLength(int limitLength)