HarmonyOS SDK 接入流程主要分为两个步骤(两个文档)

1、SDK配置:将对应的SDK集成到您的产品项目中,然后进行初始化代码处理;
2、SDK接入:将需要埋点的数据,按照SDK包装不同的方法进行数据上送,其中功能主要包含两大类:全埋点(自动采集数据上送)、自定义埋点(手动设置业务数据上送)。


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. 其他功能

7.1 设置和清除位置信息

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

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

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

7.2 日志开关

说明:初始化 SDK 时,进行如下配置。

config.enableLog(enableLog: boolean)

7.3 禁用SDK

说明:初始化 SDK 时,进行如下配置。

config.disableSDK();

7.4 属性值长度

说明:自定义属性值(string.length)长度,SDK默认限制1024,自定义最大不要超过5120;

// 在初始化
config.setLimitLength(limitLength: number);
// 或者在初始化后,通过API配置;
HinaCloudSDK.getInstance().setLimitLength(limitLength: number);
作者:王建华  创建时间:2024-11-12 09:49
最后编辑:王建华  更新时间:2024-11-12 16:36