- 平台介绍
- 接入指引
- 版本信息
- 使用流程
- 功能手册
- 操作视频
- 技术文档
- 基础知识
- 客户端SDK
- 服务端SDK
- 数据导入
- API功能
- SQL手册
- DML
- SQL函数
- 日期函数
- convert_tz
- curdate,current_date
- current_timestamp
- curtime,current_time
- date_add
- date_format
- date_sub
- datediff
- day
- dayname
- dayofmonth
- dayofweek
- dayofyear
- from_days
- from_unixtime
- hour
- makedate
- minute
- month
- monthname
- now
- second
- str_to_date
- time_round
- timediff
- timestampadd
- timestampdiff
- to_date
- to_days
- unix_timestamp
- utc_timestamp
- week
- weekday
- weekofyear
- year
- yearweek
- localtime,localtimestamp
- quarter
- last_day
- extract
- date_trunc
- minutes_add
- minutes_diff
- minutes_sub
- seconds_add
- seconds_diff
- seconds_sub
- hours_add
- hours_diff
- hours_sub
- days_add
- days_diff
- days_sub
- weeks_add
- weeks_diff
- weeks_sub
- months_add
- months_diff
- months_sub
- years_add
- years_diff
- years_sub
- 字符串函数
- append_trailing_char_if_absent
- to_base64
- from_base64
- ascii
- length
- bit_length
- char_length
- lpad
- rpad
- lower
- lcase
- upper
- ucase
- initcap
- repeat
- reverse
- char
- concat
- concat_ws
- substr
- substring
- sub_replace
- ends_with
- starts_with
- trim
- ltrim
- rtrim
- null_or_empty
- not_null_or_empty
- hex
- unhex
- elt
- instr
- locate
- find_in_set
- replace
- left
- right
- strleft
- strright
- split_part
- split_by_string
- substring_index
- money_format
- parse_url
- convert_to
- extract_url_parameter
- uuid
- space
- sleep
- 日期函数
- 数据类型
- 数据管理
- 常见问题
- 合规说明
- 资源下载
- AB测试
SDK接入
帮助中心 > 技术文档 > 客户端SDK > 跨平台框架 > APICloud > API详解
APICloud插件接入流程主要分为两个步骤(两个文档):
1、SDK配置:将对应的SDK集成到您的产品项目中,然后进行初始化代码处理;
2、SDK接入:将需要埋点的数据,按照SDK包装不同的方法进行数据上送,其中功能主要包含两大类:全埋点(自动采集数据上送)、自定义埋点(手动设置业务数据上送)。
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()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
userUId | String | 业务方-用户id |
请求示例:
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));
});
返回参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
deviceUId | String | 设备唯一id |
返回示例:
{
"deviceUId":"默认的设备唯一ID,或者已设置的设备唯一ID",
}
2.3 自定义设备唯一ID
说明:默认情况下,SDK 会生成设备唯一ID 并可以保证该ID的唯一性,如需替换SDK默认分配的,配置如下:
方法名: setDeviceUId()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
deviceUId | String | 业务方-自定义设备唯一id |
请求示例:
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()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
properties | json-object | 自定义用户属性 |
请求示例:
var param = {properties:{gender:"男"}};
moduleHC.userSet(param, function(ret, err){
alert(JSON.stringify(ret));
});
返回参数:无
3.2 固定初始值的属性
说明:同一个 key 多次设置时,value 值只会记录初次设定的值;适用于为用户设置首次激活时间、首次注册时间等属性。
方法名: userSetOnce()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
properties | json-object | 自定义用户属性(固定初始值) |
请求示例:
var param = {properties:{register_date:"2022-01-01"}};
uzmoduledemo.userSetOnce(param, function(ret, err){
alert(JSON.stringify(ret));
});
返回参数:无
3.3 数值类型的属性
说明:同一个 key 多次设置时,value 值(数值类型)进行求和计算;常用于记录用户付费次数、付费额度、积分等属性。
方法名: userAdd()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
properties | json-object | 自定义用户属性(注意json里面的value值是数值类型) |
请求示例:
var param = {properties:{score:80}};
uzmoduledemo.userAdd(param, function(ret, err){
alert(JSON.stringify(ret));
});
返回参数:无
3.4 集合类型的属性
说明:同一个 key 多次设置时,value 值(字符串类型)都会被添加到集合里;适用于用户喜爱的电影、用户点评过的餐厅等属性。
方法名: userAppend()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
propertyName | String | 属性name |
appendList | String集合 | 要追加的属性值集合 |
请求示例:
var param = {propertyName:"books",appendList:["童话世界","三字经"]};
uzmoduledemo.userAppend(param, function(ret, err){
alert(JSON.stringify(ret));
});
返回参数:无
3.5 属性取消
说明:取消已设置的某个用户属性。
方法名: userUnset()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
propertyName | String | 属性name |
请求示例:
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()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
eventName | String | 事件名 |
properties | json-object | 自定义事件属性 |
请求示例:
//比如:点击“开始阅读”按钮,并添加属性:小说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()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
eventName | String | 事件名 |
请求示例:
// 比如:开始观看视频;
var param = {eventName:"watch_video"};
moduleHC.trackTimerStart(param, function(ret, err){
alert(JSON.stringify(ret));
});
返回参数:无
方法名: trackTimerEnd()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
eventName | String | 事件名 |
properties | json-object | 自定义事件属性 |
请求示例:
// 比如:结束观看视频;
// 调用 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()
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
properties | json-object | 自定义公共属性 |
请求示例:
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));
});
返回参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
? | json-object | SDK内部预置参数 |
返回示例:
{
"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 方法:
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
flushPendSize | int |
请求示例:
var param = {flushPendSize:50};//最少50条。
uzmoduledemo.setFlushPendSize(param, function(ret, err){
alert(JSON.stringify(ret));
});
返回参数:无
6.1.2 发送间隔
说明:设置埋点数据发送的间隔,默认为 15s。
方法名: setFlushInterval 方法:
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
flushInterval | int |
请求示例:
var param = {flushInterval:5000};//最小 5 秒,单位毫秒。
uzmoduledemo.setFlushInterval(param, function(ret, err){
alert(JSON.stringify(ret));
});
返回参数:无
6.1.3 设置数据的网络上传策略
说明:默认情况下,在 WIFI/3G/4G/5G 网络条件下,SDK 都会尝试去同步数据。
方法名: setFlushNetworkPolicy 方法:
请求参数:
参数key(String类型) | 参数value类型 | 参数说明 |
---|---|---|
networkTypePolicy | int |
请求示例:
/**
* 设置 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));
});
最后编辑:超级管理员 更新时间:2024-09-05 21:06