SDK 接入
- 1. 开启全埋点(自动采集)
- 2. 用户关联
- 2.1 关联用户ID
- 2.2 获取设备唯一ID
- 2.3 自定义设备唯一ID
- 3. 用户属性
- 3.1 设置用户属性
- 3.2 固定初始值的属性
- 3.3 数值类型的属性
- 3.4 集合类型的属性
- 3.5 属性取消
- 3.6 清空用户属性
- 4. 自定义埋点
- 4.1 自定义埋点
- 4.2 自定义时长埋点
- 5 事件属性
- 5.1 设置公共属性
- 5.2 获取预置属性
- 6. 数据存储与发送
- 6.1 上报条件
- 6.1.1 缓存条数
- 6.1.2 发送间隔
- 6.1.3 设置数据的网络上传策略
- 6.2 立即上报(强制上报)
- 6.3 本地数据缓存上限值
- 6.4 清空本地缓存事件
- 7. 其他功能
- 7.1 设置和清除位置信息
- 7.2 日志开关
- 7.3 禁用SDK
- 7.4 属性值长度
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 16:36