1. 开启全埋点

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

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

var param = {
...,
/**
 * 设置全埋点采集策略，默认关闭
 * TYPE_NONE = 0;//关闭
 * APP_START = 1;//启动 1
 * APP_END = 1 << 1;//退出 2
 * APP_CLICK = 1 << 2;//控件点击 4
 * APP_VIEW_SCREEN = 1 << 3;//浏览页面 8
 * 例：若需要开启 App 启动、退出，则需要设置 1 + 2 = 3
 */
//全埋点开启 App 启动、退出自动采集。
autoTrackTypePolicy:3,
...
};

moduleHC.init(param, function(ret, err){
    alert(JSON.stringify(ret));
});

2. 用户关联

2.1 用户登录

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

方法名： setUserUId()
请求参数：

请求示例：

var param = {userUId:"您平台用户唯一标识"};
uzmoduledemo.setUserUId(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

2.2 获取设备唯一ID

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

方法名： getDeviceUId()
请求参数：无

请求示例：

var param = {};
uzmoduledemo.getDeviceUId(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：

返回示例：

{
    "deviceUId":"默认的设备唯一ID，或者已设置的设备唯一ID",
}

2.3 自定义设备唯一ID

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

方法名： setDeviceUId()
请求参数：

请求示例：

var param = {deviceUId:"自定义设备唯一ID"};
uzmoduledemo.setDeviceUId(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

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

3. 用户属性

3.1 设置用户属性

说明：同一个 key 多次设置时，value 值会进行覆盖替换。

方法名： userSet()
请求参数：

请求示例：

var param = {properties:{gender:"男"}};
moduleHC.userSet(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

3.2 固定初始值的属性

说明：同一个 key 多次设置时，value 值只会记录初次设定的值；适用于为用户设置首次激活时间、首次注册时间等属性。

方法名： userSetOnce()
请求参数：

请求示例：

var param = {properties:{register_date:"2022-01-01"}};
uzmoduledemo.userSetOnce(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

3.3 数值类型的属性

说明：同一个 key 多次设置时，value 值（数值类型）进行求和计算；常用于记录用户付费次数、付费额度、积分等属性。

方法名： userAdd()
请求参数：

请求示例：

var param = {properties:{score:80}};
uzmoduledemo.userAdd(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

3.4 集合类型的属性

说明：同一个 key 多次设置时，value 值（字符串类型）都会被添加到集合里；适用于用户喜爱的电影、用户点评过的餐厅等属性。

方法名： userAppend()
请求参数：

请求示例：

var param = {propertyName:"books",appendList:["童话世界","三字经"]};
uzmoduledemo.userAppend(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

3.5 属性取消

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

方法名： userUnset()
请求参数：

请求示例：

var param = {propertyName:"gender"};
uzmoduledemo.userUnset(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

3.6 清空用户属性

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

方法名： userDelete()
请求参数：无

请求示例：

var param = {};
uzmoduledemo.userDelete(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

4. 自定义埋点

用于记录埋点事件。

4.1 自定义埋点

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

方法名： track()
请求参数：

请求示例：

//比如：点击“开始阅读”按钮，并添加属性：小说id、小说的章节；
var param = {eventName:"novel_read_btn_click",properties:{novel_id:"1234567890",novel_chapter:"3"}};
moduleHC.track(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

4.2 统计埋点事件时长

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

方法名： trackTimerStart()
请求参数：

请求示例：

// 比如：开始观看视频;
var param = {eventName:"watch_video"};
moduleHC.trackTimerStart(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

方法名： trackTimerEnd()
请求参数：

请求示例：

// 比如：结束观看视频；
// 调用 trackTimerEnd 方法，会触发事件，并在属性 event_duration 中记录时长；
var param = {eventName:"watch_video",properties:{video_id:"1234567890",video_type:"娱乐"}};
moduleHC.trackTimerEnd(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

注意：浏览页面、控件点击仅对原生工程支持，APICloud 工程仅支持采集APP启动和退出；

5. 事件属性

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

5.1 设置事件公共属性

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

方法名： registerCommonProperties()
请求参数：

请求示例：

var param = {properties:{app_name:"SDKDemo"}};
moduleHC.registerCommonProperties(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

5.2 获取预置属性

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

方法名： getPresetProperties()

请求参数：无

请求示例：

var param = {};
moduleHC.getPresetProperties(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：

返回示例：

{
    "app_name":"SDKDemo",
    "app_version":"1.0.0",
    ...
}

6. 数据存储与发送

在每次调用 track()、setUserUid()、userSet() 等方法时，SDK 会将埋点事件保存在数据库中，并会检查如下条件，以判断是否向服务器上传数据：

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

6.1 上报条件

6.1.1 缓存条数

说明：设置本地缓存日志的最大条目数，默认本地埋点数据缓存为 100 条。

方法名： setFlushPendSize 方法：
请求参数：

请求示例：

var param = {flushPendSize:50};//最少50条。
uzmoduledemo.setFlushPendSize(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

6.1.2 发送间隔

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

方法名： setFlushInterval 方法：
请求参数：

请求示例：

var param = {flushInterval:5000};//最小 5 秒，单位毫秒。
uzmoduledemo.setFlushInterval(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

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

说明：默认情况下，在 WIFI/3G/4G/5G 网络条件下，SDK 都会尝试去同步数据。

方法名： setFlushNetworkPolicy 方法：
请求参数：

请求示例：

/**
 * 设置 flush 时网络发送策略，默认 3G、4G、WI-FI 环境下都会尝试 flush
 * TYPE_NONE = 0;//NULL
 * TYPE_2G = 1;//2G
 * TYPE_3G = 1 << 1;//3G 2
 * TYPE_4G = 1 << 2;//4G 4
 * TYPE_WIFI = 1 << 3;//WIFI 8
 * TYPE_5G = 1 << 4;//5G 16
 * TYPE_ALL = 0xFF;//ALL 255
 * 例：若需要开启 4G 5G 发送数据，则需要设置 4 + 16 = 20
 */
//指定只在 3G/4G/WIFI 条件下发送数据。
var param = {networkTypePolicy:14};
uzmoduledemo.setFlushNetworkPolicy(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

6.2 立即上报

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

方法名： flush()
请求参数：无

请求示例：

var param = {};
uzmoduledemo.flush(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

6.3 本地数据缓存上限值

说明：
1、在初始化中设置，Android和iOS设置维度不一样，如有需要，请分开设置；
2、当存储数量达到上限值，会依次丢弃老数据，保留最新的数据。

var param = {
        ...,
        //android配置空间大小，SDK 本地数据库默认缓存数据的上限值为 32MB
        maxCacheSizeForAndroid: 32 * 1024 * 1024,//设置最小 16MB（16 * 1024 * 1024），单位 byte；
        //iOS配置条数，默认10000条
        maxCacheSizeForIOS: 10000,//设置最少10000条；
        ...
};

moduleHC.init(param, function(ret, err){
    alert(JSON.stringify(ret));
});

6.4 清空本地缓存事件

说明：删除 App 本地存储的所有事件，如果不是特殊要求，请不要调用此方法。

方法名： clear()
请求参数：无

var param = {};
uzmoduledemo.clear(param, function(ret, err){
    alert(JSON.stringify(ret));
});

返回参数：无

7. 其他功能

7.1 日志开关

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

var param = {
...,
//日志开关
enableLog:true,
...
};

moduleHC.init(param, function(ret, err){
    alert(JSON.stringify(ret));
});