1. 开启全埋点（自动采集）(开发内测中)

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

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

//比如：开启自动采集应用启动和退出事件；
config.setAutoTrackEventType(IAutoTrackEventType.APP_START | IAutoTrackEventType.APP_END);

2. 用户关联

2.1 关联用户ID

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

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

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

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

2.2 获取设备唯一ID

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

let deviceUId = HinaCloudSDK.getInstance().getDeviceUId();

2.3 自定义设备唯一ID

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

// 通过 setDeviceUId 配置
HinaCloudSDK.getInstance().setDeviceUId("xxx");

注意：SDK 生成设备唯一ID规则：应用包名hex + 时间戳（毫秒） + 随机数（3位）。

3. 用户属性

3.1 设置用户属性

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

HinaCloudSDK.getInstance().userSet(key: string, value: string | number | boolean | JSONObject);
// 或
HinaCloudSDK.getInstance().userSetUseJson(properties: JSONObject);

3.2 固定初始值的属性

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

HinaCloudSDK.getInstance().userSetOnce(key: string, value: string | number | boolean | JSONObject);
// 或
HinaCloudSDK.getInstance().userSetOnceUseJson(properties: JSONObject);

3.3 数值类型的属性

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

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

3.4 集合类型的属性

说明：同一个 key 多次设置时，value 值（字符串类型）集合进行追加。

HinaCloudSDK.getInstance()userAppend(key: string, value: string)
// 或
let books = new Set<string>();
books.add("三字经");
books.add("论语");

HinaCloudSDK.getInstance().userAppendUseSet(key: string, values: Set<string>);

3.5 属性取消

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

HinaCloudSDK.getInstance().userUnset(key: string);

3.6 清空用户属性

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

HinaCloudSDK.getInstance().userDelete();

4. 自定义埋点

用于记录埋点事件。

4.1 自定义埋点

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

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

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

4.2 自定义时长埋点

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

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

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

5 事件属性

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

5.1 设置公共属性

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

首先，自定义一个实现ICommonProperties接口的类；

@Sendable
export class MyProperties implements ICommonProperties {
  getCommonProperties(): JSONObject {
    let jsonObject: JSONObject = new JSONObject();
    jsonObject.put("alias", "鸿蒙alias");
    jsonObject.put("appTimeZone", systemDateTime.getTimezoneSync());
    jsonObject.put("appTime", Date.now());
    return jsonObject;
  }
}

然后，把类的实例设置到 SDK 即可；

HinaCloudSDK.getInstance().registerCommonProperties(new MyProperties());

5.2 获取预置属性

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

let 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 条。

//初始化时配置
config.setFlushPendSize(size: number);//最少50条。

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

6.1.2 发送间隔

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

//初始化时配置(注意：使用毫秒配置)
config.setFlushInterval(intervalTime: number);//最小 5 秒，单位毫秒。

//或者在初始化后，通过API配置(注意：使用毫秒配置)
HinaCloudSDK.getInstance().setFlushInterval(intervalTime: number);

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

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

//初始化时配置
config.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 本地数据库默认缓存数据的上限值为 10000 条。

//初始化时配置
config.setMaxCacheSize(maxCacheSize: number)//最小 10000 条；

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

6.4 清空本地缓存事件

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

HinaCloudSDK.getInstance().clear();

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

7. 全埋点控制（开发内测中）

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

7.1 页面浏览

针对鸿蒙页面浏览事件，可以通过以下两种方式，将自定义属性传入到页面浏览事件中。

7.1.1 设置自定义属性

7.1.1.1 Router

通过 Router 的 Push API 传递 hinadt_data_tag ，并将自定义属性作为值传入。示例代码如下：

router.pushUrl({
  url: 'pages/SecondPage',
  params: {
    'hinadt_data_tag': {
      "title":"页面标题"
    }
  }
}).then(() => {
  console.info('Succeeded in jumping to the second page.')
}).catch((err: BusinessError) => {
  console.error(`Failed to jump to the second page. Code is ${err.code}, message is ${err.message}`)
})

上述示例中 pages/SecondPage 页面触发页面浏览事件时，则会额外添加自定义属性。

7.1.1.2 NavPathStack

如 App 中通过 NavPathStack 实现路由，则可以通过 NavPathStack 的 Push 相关 API 将 params 传入。示例代码如下：

7.1.2 忽略页面浏览

8. 其他功能

8.1 设置和清除位置信息

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

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

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

8.2 日志开关

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

config.enableLog(enableLog: boolean)

8.3 禁用SDK

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

config.disableSDK();

8.4 属性值长度

说明：自定义属性值（string.length）长度，SDK默认限制1024，自定义最大不要超过5120；

// 在初始化
config.setLimitLength(limitLength: number);
// 或者在初始化后，通过API配置；
HinaCloudSDK.getInstance().setLimitLength(limitLength: number);