SDK接入
帮助中心 > 技术文档 > 客户端SDK > Web Js SDK > SDK接入
Web JS SDK 接入流程主要分为两个步骤(两个文档):
1、SDK配置:将对应的SDK集成到您的产品项目中,然后进行初始化代码处理;
2、SDK接入:将需要埋点的数据,按照SDK包装不同的方法进行数据上送,其中功能主要包含两大类:全埋点(自动采集数据上送)、自定义埋点(手动设置业务数据上送)。
1. 开启全埋点
初始化SDK时,可以通过设置autoTrackConfig
参数配置SDK的全埋点功能,更多配置可以参考【全埋点】
// 创建 SDK 全局对象
const hina = window['hinaDataStatistic'];
// 用配置对象初始化 SDK
hina.init({
serverUrl: '数据接收地址',
showLog : true,
//单页面配置,默认开启,若页面中有锚点设计,需要将该配置删除,否则触发锚点会多触发 H_pageview 事件
isSinglePage: true,
sendType: 'ajax',
autoTrackConfig: {
// 是否开启自动点击采集, true表示开启,自动采集 H_WebClick 事件
clickAutoTrack: true,
// 是否开启页面停留采集, true表示开启,自动采集 H_WebStay 事件
stayAutoTrack: true,
// 是否开启页面浏览采集,auto 表示开启,singlePage 表示单页面开启,false 关闭,可配合手动开启使用
// 若页面中有锚点设计,需要将该配置设为 false,否则触发锚点会多触发 H_pageview 事件
pageviewAutoTrack: 'singlePage',
// 是否开启页面离开采集,true 表示开启,具体配置查看插件集成
pageLeaveAutoTrack: true
},
});
开启【pageview全埋点】或手动quick方法后自动写入的相关属性:
属性名 | 名称 |
---|---|
H_first_referrer | 首次前向地址 |
H_first_referrer_host | 首次前向地址域名 |
H_ first_traffic_source_type | 首次流量来源类型 |
H_ first_search_keyword | 首次搜索引擎关键词 |
H_ utm_source | 首次广告系列来源 |
H_ utm_medium | 首次广告系列媒介 |
H_ utm_term | 首次广告系列字词 |
H_ utm_content | 首次广告系列内容 |
H_ utm_campaign | 首次广告系列名称 |
xxx | source_channel 自定义渠道来源属性: [‘xxx’, ‘yyy’] |
yyy | source_channel 自定义渠道来源属性: [‘xxx’, ‘yyy’] |
2.用户关联
2.1 用户关联介绍
在使用常用功能之前,建议你先了解用户识别规则:
关联标记用户时,用户ID取值有两种:一种是设备ID(随机算法生成的匿名ID)、一类是登录ID(由用户自主设置的ID)
SDK默认会使用随机生成的字符串作为设备ID,并持久化存储设备ID在本地;用户未登录之前,会以设备ID作为身份识别ID。
注意:设备 ID 在本地缓存清理时会改变。
2.2 基本API介绍
2.2.1 用户登录关联
当用户注册成功或登录成功时,需要调用 SDK 的setUserUId
方法,SDK优先以账号 ID 作为身份标识,设置后的账号 ID 将会被保存,多次调用 setUserUId 将会覆盖先前的账号 ID
// 用户的登录唯一标识,此数据对应上报数据里的 distinct_id
// 比如:登录手机号、登录邮箱、用户唯一主键值
hina.setUserUId("您平台用户唯一标识");
为了准确记录登录用户的行为信息,建议在以下时机各调用一次用户登录方法:
· 用户在注册成功时
· 用户登录成功时
· 已登录用户每次打开网站 时
2.2.2 获取设备唯一ID
可以调用 getDeviceUId
获取返回设备唯一ID,此方法需要在初始化SDK完成后执行才能使用
hina.getDeviceUId()
2.2.3 自定义设备唯一ID
说明:默认情况下,SDK 会生成设备唯一ID 并可以保证该ID的唯一性,如需替换SDK默认分配的,配置如下:
//初始化时配置
hina.setDeviceUId('自定义ID')
3. 用户属性
3.1 设置用户属性
直接设置用户的属性,如果存在则覆盖
hina.userSet({ name:'xx' });
3.2 固定初始值的属性
如果不存在则设置,存在就不设置
hina.userSetOnce({ name:'xx' });
3.3 数值类型的属性
对当前用户的属性做递增或者递减
// 表示num递增2
hina.userAdd({ 'num': 2 })
//表示num递减2
hina.userAdd({ 'num': -2 })
4. 发送事件
在 SDK 初始化完成之后,您就可以进行数据埋点,收集用户的的行为信息
4.1 自定义埋点
说明:使用track()方法进行直接埋点,埋点事件支持添加自定义属性。
//直接埋点,不含自定义属性,比如:点击“开始阅读”按钮;
hina.track("novel_read_btn_click");
//直接埋点,添加自定义属性,比如:点击“开始阅读”按钮,添加属性:小说id、小说的章节
hina.track(
//事件名称
'novel_read_btn_click ',
//需要上传的事件属性
{
novel_id: "1234567890",
novel_chapter : 3,
}
);
5. 事件属性
在进行埋点事件追踪时,您可以根据需求对埋点事件进行属性的定义。目前 SDK 中提供了公共属性用于给每个埋点事件添加属性。
5.1 设置事件公共属性
对于所有事件都需要添加的属性,可在初始化 SDK 后,调用 registerCommonProperties
将属性注册为公共属性
hina.registerCommonProperties({
title: document.title
})
当设置动态公共属性的时候,需要使用函数类型作为属性值
函数返回值只能是string、bool、number、date、array类型
hina.registerCommonProperties({
afterTwoHour: function(){
return new Date().addHours(2)
}
})
5.2 获取预置属性
此方法可获取,页面地址,页面标题,前向地址,SDK 类型及版本,屏幕宽高,最近一次的相关属性
hina.quick('isReady',function(){
const presetProperties = hina.getPresetProperties();
})
6. 上报数据方式
SDK上报数据的方式分为实时发送和批量发送:
- 实时发送:事件触发之后会立即上报一条最新数据到海纳分析平台,常见的数据发送有image、ajax、beacon发送
- 批量发送: 触发事件后会先保存起来再批量定时发送到海纳分析平台
6.1 实时发送数据
常见的实时发送数据方式有 img 发送、ajax 发送和 beacon 发送:
- img 发送:默认使用 img 发送数据,对于跨域的兼容比较好,发送的形式就是创建一个 img 元素,src 带上所有要发送 的数据
- ajax 发送:常见的请求方式,采用的是 post 形式发送数据,数据较为安全,且发送数据的大小基本不受限制
- beacon发送:beacon是浏览器的最新发送策略,采用post形式发送数据,可以避免页面关闭时数据发送丢失的问题,但不兼容老版本浏览器
// img发送
sendType: 'image'
// ajax发送
sendType: 'ajax'
// beacon发送
sendType: 'beacon'
6.2 批量发送数据
触发事件之后会将数据写入localStorage中,如果浏览器不支持 localStorage存储,请使用实时发送数据的方式。
配置参数send_interval
可以间隔时间定时发送数据
数据发送请求必须成功后,才会删除数据,否则会一直请求直到存储最大条数
// 默认不开启批量发送
batchSend:false,
// 开启批量发送
batchSend:true,
//或者
batchSend:{
datasendTimeout: 6000, //一次请求超过多少毫秒的话自动取消,防止请求无响应
sendInterval: 6000, //间隔多少毫秒发一次数据
storageLimit: 200, // 存储 localStorage 条数最大值,默认:200 。如 localStorage 条数超过该值,则使用 image 方式立即发送数据
},
注意:
- 批量发送功能和回调函数功能不可以同时使用,比如track加了callback,使用批量发送后callback不会执行
- 批量发送默认使用 ajax 的方式发送数据,如果不支持跨域ajax发送数据,会使用img且实时发送数据
- 如果localStorage 里已经存了超过 200 条数据,会导致批量发送功能失效,localStorage 中只保存这 200 条数据,新产生的数据使用 img 且实时发送数据的方式。当进入同域名的新页面时,会自动检查缓存中是否有数据,如果有会继续发送缓存的数据
- useAppBridge和batch_send只能选择一个,开启了打通App就不能再用批量发送
7. 调试查看事件信息
测试阶段在初始化代码中设置 showLog
为true
,页面上有事件触发时,浏览器开发者工具会打印采集的事件信息
hina.init({
...
serverUrl: '数据接收地址',
showLog: true
...
})
最后编辑:刘建雄 更新时间:2024-09-29 11:54