SDK接入
帮助中心 > 技术文档 > 客户端SDK > uni小程序 SDK > SDK接入
1.下载SDK
此SDK仅适用于在uni-sdk环境中运行的小程序使用(官网),其他小程序请移步小程序SDK查看。
下载地址,文件结构:
├── hina-uni.esm.full.js # 用于 import 方式 推荐使用
└── hina-uni.cjs.full.js # 用于 require 标签方式
2.初始化
准备工作:获取”采集上报地址URL”,用于上报采集的数据,参考。
在项目入口文件中引入(例如:main.js)
// main.js
// vue3项目
import hina from '/hina-uni.esm.full.js'
hina.init({
serverUrl: '采集上报地址URL',
// 是否允许控制台打印查看埋点数据(建议开启查看)
showLog: true,
// 全埋点控制开关
autoTrack: {
appLaunch: true, // 默认为 true,false 则关闭 H_MPLaunch 事件采集
appShow: true, // 默认为 true,false 则关闭 H_MPShow 事件采集
appHide: true, // 默认为 true,false 则关闭 H_MPHide 事件采集
pageShow: true, // 默认为 true,false 则关闭 H_MPViewScreen 事件采集
pageLeave: false // 默认为 false, true 则开启 H_MPPageLeave事件采集
}
})
export function createApp() {
const app = createSSRApp(App);
hina.setInstance(app) // 这里很重要,需要将vue实例传递给SDK
return {
app,
};
}
// vue2项目
import miniSdk from '/hina-uni.esm.full.js'
hina.init({
serverUrl: '采集上报地址URL',
showLog: true,
autoTrack: {
appLaunch: true, // 默认为 true,false 则关闭 H_MPLaunch 事件采集
appShow: true, // 默认为 true,false 则关闭 H_MPShow 事件采集
appHide: true, // 默认为 true,false 则关闭 H_MPHide 事件采集
pageShow: true, // 默认为 true,false 则关闭 H_MPViewScreen 事件采集
pageLeave: false // 默认为 false, true 则开启 H_MPPageLeave事件采集
}
instance: Vue // 这里直接在初始化的时候 将vue传递给SDK
});
3.配置项
属性 | 类型 | 默认值 | 说明 |
---|---|---|---|
serverUrl | string | 无 | 必填,采集上报地址URL |
showLog | boolean | false | 是否在控制台打印上报的数据 |
dataSendTimeout | number | 3000 | 数据发送超时时间:设定时间内未完成发送将强制取消请求,单位(毫秒) |
autoTrack | object | 无 | 是否开启自动采集,配置项 |
maxStringLength | number | 1024 | 上报数据单个字段长度,默认 1024 字符,上限5120 |
presetEvents | object | 无 | 配置采集指定预置属性 配置项 |
autoTrackExcludePage | object | 无 | 配置指定页面不采集 H_MPViewScreen和H_MPPageLeave 页面浏览事件 配置项 |
globalCallback | function | null | 上报数据后会触发 |
3.1. 全埋点采集逻辑
六个属性参数( appLaunch、 appShow、 appHide、 pageShow、pageShare、pageLeave)
其中 pageLeave 默认是 false,其他是 true。
即默认采集五个事件 H_MPLaunch、H_MPShow、H_MPHide、H_MPViewScreen、H_MPShare。
事件名称 | 生命周期 | 采集时机 | 说明 |
---|---|---|---|
H_MPLaunch(小程序启动) | App.onLaunch | 小程序进程被杀死,重新打开时会触发 | 小程序初始化完成时,全局只触发一次; |
H_MPShow(小程序显示) | App.onShow | 小程序启动,或从后台进入前台显示 | 启动小程序时,后台进入前台; |
H_MPHide(小程序进入后台) | App.onHide | 点击小程序右上角退出按钮、微信进入后台、手机锁屏、小程序进程被杀死时 | 小程序从前台进入后台; |
H_MPShare(小程序分享) | Page.onShareAppMessage/ Page.onShareTimeline |
设置这个函数后,点击分享按钮触发 | 暂时只能获取到用户触发分享,无法监听是否分享成功的反馈; |
H_MPViewScreen(小程序页面浏览) | Page.onShow | 小程序启动打开页面、小程序内打开页面、从后台进入前台打开页面时触发 | 每次打开页面都会调用一次; |
H_MPPageLeave(小程序页面离开) | page.onHide 或 page.onUnload | 小程序页面隐藏或卸载时触发 |
对于H_MPLaunch、H_MPShow、H_MPHide三个事件如果不想自动上报,也可以手动进行触发
// 入口文件:main.js
hina.init({
//...其他配置
// 全埋点控制开关
autoTrack: {
appLaunch: false,
appShow: false,
appHide: false
}
})
//App.vue页面
onLaunch: function(options) {
hina.quick("appLaunch",options)
},
onShow: function(options) {
hina.quick("appShow",options)
},
onHide: function() {
hina.quick("appHide")
}
3.2. 配置采集指定预置属性
属性 | 类型 | 默认值 | 说明 |
---|---|---|---|
deferTrack | boolean | false | 是否延迟上报H_MPClick事件,当设置为true时,会将H_MPClick事件放在setTimeout中延迟上报 |
4.高级功能
4.1. 用户关联
4.1.1. 介绍
关联标记用户时,用户ID取值有两种:一种是匿名ID(随机算法生成)、一种是登录ID(由用户自主设置的ID)。SDK默认使用匿名ID,并持久化存储在本地,用户未登录之前,会以匿名ID作为身份识别。
注意:匿名 ID 在本地缓存清理时会改变。
4.1.2. 基本API
当用户注册成功或登录成功时,您需要调用 SDK 的setUserUId
方法,一般为用户在您业务系统中的唯一身份标识(如手机号、id),多次调用 setUserUId 将会覆盖先前的值,代码示例:
hina.setUserUId('您平台用户的唯一标识');
为了准确记录登录用户的行为信息,建议在以下时机各调用一次用户登录方法:
- 用户在注册成功时
- 用户登录成功时
- 已登录用户每次打开网站时
4.2. 用户属性
用户属性,可以理解为用户的“标签”或“特征”,它描述了用户的某些固有信息或状态,这些信息通常不会频繁变动,例如性别、年龄。
注意:第一步:您需要在嗨数云平台创建用户属性,然后才能操作用户属性。
4.2.1. 设置用户属性
设置用户属性的值,如果值存在则覆盖,如用户所在城市,代码示例:
hina.userSet({ city: 'Shanghai' });
4.2.2. 固定初始值的属性
设置用户仅在首次有效的属性。这些属性在用户生命周期内只会被设置一次,即使后续再次设置,也不会覆盖原有的值,如用户首次注册时间,代码示例:
hina.userSetOnce({
first_register_time: new Date().toISOString()
});
4.2.3. 数值类型的属性
对数值类型的用户属性做递增或递减,如购买数量、账户余额、访问次数,代码示例:
// 购买数量,表示递增2
hina.userAdd({ 'purchase_count': 2 })
// 账户余额,表示递减100
hina.userAdd({ 'account_balance': -100 })
// 用户访问次数,表示递增1次
hina.userAdd('visit_count')
4.2.4. 集合类型的属性
为数组类型的用户属性添加值,如收藏列表,代码示例:
// 增加两个值
hina.userAppend({ 'favorite': ['id1','id2'] })
// 增加一个值
hina.userAppend({ 'favorite': 'id1' })
4.2.5. 属性取消
重置某些用户属性的值,代码示例:
hina.userUnset('name') // 字符串类型的值重置为:''
hina.userUnset('age') // 数值类型的值重置为:0
hina.userUnset('is_login') // 布尔类型的值重置为:''
// 删除name和age的值
hina.userUnset(['name','age','is_login'])
4.3. 发送事件
4.3.1. 内置埋点(H_MPClick)事件
用户可以使用clickTrack方法对元素点击事件进行埋点,接受两个参数:元素对象(event) 和自定义属性(props)。
event:元素对象会自动上报如下属性:
1、元素内容(H_element_content)
元素设置 data-content 属性后自动上报,如:<div data-content="testContent">测试</div>
2、元素ID(H_element_id):
元素设置 id 属性后自动上报,如:<div id="testID">测试</div>
3、元素名称(H_element_name):
元素设置 data-name 属性后自动上报,如:<div data-name="testName">测试</div>
4、元素名称(H_element_type):
元素设置 data-name 属性后自动上报,如:<div data-type="testType">测试</div>
自定义属性需要在嗨数云平台创建:
// 什么都不传
hina.clickTrack()
// 只传递自定义属性
hina.clickTrack({
a:1,
b:2
})
// 传递元素对象和自定义属性
hina.clickTrack(event,{
a:1,
b:2
})
4.3.2. 自定义埋点
准备工作:在嗨数云平台创建元事件,如事件名:novel_read_btn_click,属性名:novel_id。
使用track()方法进行直接埋点,埋点事件支持添加自定义属性。
// 不含自定义属性
hina.track('novel_read_btn_click');
// 添加自定义属性
hina.track(
'novel_read_btn_click ',
{
novel_id: 1,
}
);
4.4. 事件属性
在进行埋点事件追踪时,您可以根据需求对埋点事件进行属性的定义。SDK 中提供了公共属性用于给每个埋点事件添加属性。
4.4.1. 设置公共事件属性
对于所有事件都需要添加的属性,可在初始化 SDK 后,调用 registerCommonProperties
将属性注册为公共事件属性,如设置用户等级为公共事件属性,代码示例:
hina.registerCommonProperties({
role: '黄金会员'
})
当设置动态公共属性的时候,需要使用函数类型作为属性值,函数返回值只能是string、bool、number、date、array类型。
hina.registerCommonProperties({
afterTwoHour: function(){
return new Date().addHours(2)
}
})
4.4.2. 获取预置属性
如需了解和使用预置属性,可以通过此方法获取预置属性。
hina.getPresetProperties()
4.5. 支持动态禁用/启用 API
// 禁用 API 执行
hina.disableSDK()
// 恢复 API 执行
hina.enableSDK()
// 获取 API 状态
hina.getDisabled()
最后编辑:张永健 更新时间:2025-07-03 16:55