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

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

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

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

2. 用户关联

2.1 用户登录

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

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

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

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

2.2 用户登出

说明：调用此接口后，SDK 会将设备上持久化存储中 account_id 信息删除，此时不会触发任何预置事件。后续该设备上，用户产生的事件，在上报时将不再带有 account_id 信息。

HinaCloudSDK.getInstance().cleanUserUId();

2.3 获取匿名 ID

说明：如需获取匿名 ID，请在初始化SDK后调用getDeviceUId()方法进行获取。

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

2.4 更改匿名 ID

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

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

注意：SDK 默认获取ODID（开发者匿名设备标识符）作为匿名 ID；若 ODID 获取不到，SDK 内部会生成一个 UUID。

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}`)
})

7.1.1.2 NavPathStack

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

let params: Record<string, Record<string, Object>> = {
  "hinadt_data_tag": {
    "title":"页面标题"
  }
}
this.pageStack.pushPath({ name: "NavDestinationTitle" + item, param: params })
})

7.1.2 忽略页面浏览

说明：默认采集所有页面，如果需要指定某些页面不采集，可以通过如下方式设置：

HinaCloudSDK.getInstance().ignoreAutoTrackPages(new Set<string>([
  'pages/SecondPage',
  'pages/ThirdPage',
  ...
]))

7.2 元素点击

说明：元素点击事件（全埋点 H_AppClick 事件），默认采集了元素id、元素类型和元素上的文本，默认对所有常规元素点击进行采集。

7.2.1 设置自定义属性

说明：当元素被点击时，如果需要对某个组件，增加一些属性或者修改默认采集的属性值，可以通过以下方式设置：在组件上调用 customProperty API 传入 hinadt_data_tag ，并将相应的属性传入。

Button('加入购物车')
  .fontSize(15)
  .customProperty('hinadt_data_tag', {
    'productId': 'xxx'
  })

7.2.2 忽略元素点击

说明：默认采集所有常规元素的点击，SDK支持忽略某类或者单个元素点击行为。

1、忽略某类元素点击

说明：在SDK初始化后，通过 ignoreFrameNodeType 配置忽略采集的组件类型。

// 注意参数使用字符串格式
HinaCloudSDK.getInstance().ignoreFrameNodeType('Button')

2、忽略单个元素点击

说明：在组件上调用 customProperty API 传入 hinadt_data_tag，并将 ‘ignore’: true 参数传入。

Button('测试按钮Button')
  .fontSize(15)
  .customProperty('hinadt_data_tag', {
    'ignore': true
  })

8. 其他功能

8.1 日志开关

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

config.enableLog(enableLog: boolean)

8.2 禁用SDK

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

config.disableSDK();

8.3 属性值长度

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

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