npm install @x-edu/tracker
关于神策的用法详见:https://manual.sensorsdata.cn/sa/latest/tech_sdk_client_web_high-7538088.html
import { XTracker } from '@x-edu/tracker'
/**
* 完成 SDK 加载,以及神策的初始化功能(SDK 加载完成后的业务相关内容请放在 callback 中)
*/
XTracker.init({
env = window.__global_env, // 环境:test/preproduction/product/ncet-xedu,用于获取默认配置。不传时,默认取 window.__global_env(不存在该变量时,env = 'ncet-xedu')
// 神策初始化配置参数(神策最终的上报地址由 serverUrl 和 appKey 拼接)
sensors: {
serverUrl: '', // 非必传,数据接收地址(用于覆盖默认配置中的神策上报地址)
appKey: '', // 非必传,xstudy_web/xstudy_pc(用于覆盖默认配置中的神策上报地址)
bridge: true, // 是否开启 app 代理上报。默认true,由于移动端数据接收地址与h5不同,所以需要配置白名单,不能使用 true(只在被 app 内嵌时有效)。app_js_bridge(https://manual.sensorsdata.cn/sa/latest/app-h5-1573914.html)
heatmap: {
// 是否开启点击图,默认关闭。
clickmap: 'not_collect',
// 是否开启触达图,默认关闭。
scroll_notice_map: 'not_collect'
}, // 神策全埋点和点击图 https://manual.sensorsdata.cn/sa/latest/zh_cn/tech_sdk_client_web_all_use-7545310.html
subServerUrl: '', // 非必传,神策双报的数据接收地址(2.0.0 新增)
subAppKey: '' // 非必传,神策双报的应用appKey(2.0.0 新增,默认和 appKey 一致)
},
// 完成 SDK 加载后的回调
callback: ({ sensors }) => {
// 关于 sensors
// 1. 如果未使用神策双报:sensors = window.sensors,支持所有神策方法
// 2. 如果使用神策双报:sensors 返回的是内部实例化的神策对象,目前仅支持 sensors.registerPage、sensors.quick 方法。如果调用的是 sensors.quick('autoTrack'),那么请注意,自动采集的页面浏览事件并不会上报到 subServerUrl,只能上报到 serverUrl
// 加载完成后的操作...
},
_qt: false // 必传
})
XTracker.track({
eventName: '', // 事件名
params: { // 事件参数
event_type: 'clickEvent' | 'businessEvent', // 神策事件类型,可选,默认为 clickEvent,如有需要可进行覆盖
...otherParams
}
})
XTracker.pv({
eventName: '', // 事件名
params // 事件参数(传不传 event_type 都可以,神策上报时会自动加上 event_type: 'pageEvent')
})
window.sensors
: 神策对象,相当于 XTracker.init 中 callback 的回调参数 sensors。
注意:window.sensors
需要在 XTracker.init 完成后使用,否则 window 上不存在该属性。
由于 XTracker.init 是一个异步的过程,在实际使用中可能出现初始化还未完成就去取 window.sensors
的情况,此时该属性可能还不存在,以下提供了两种方法避免这种问题:
-
方法1:@x-edu/tracker 提供了异步的静态方法
XTracker.getSensors()
来获取神策对象const getSensors = async () => { const sensors = await XTracker.getSensors() // 不开启(使用)神策上报时,sensors 为 null console.log('window.sensors', sensors) } getSensors()
-
方法2:@x-edu/tracker 提供了异步的静态方法
XTracker.getInitState()
来获取 sdk 初始化的完成状态。完成初始化后,如果启用了神策上报,window.sensors
就一定存在const getTrackInitState = async () => { const state = await XTracker.getInitState() // 已完成初始化 if (state) { // 不开启(使用)神策上报时,window.sensors 为 undefined console.log('window.sensors', window.sensors) } } getTrackInitState()
需要调用神策的方法时,请使用 window.sensors.xx
调用或在 XTracker.init 的 callback 中通过回调参数 sensors.xx
调用。
使用示例:神策注册公共属性
注意:如果有使用 registerPage 方法,该方法要在 XTracker.track 或 XTracker.pv 调用前完成,否则会导致公共属性注册失败
window.sensors.registerPage({
nduser_id: '',
identity: '游客',
application_id: 'xstudy_web',
owned_role: ''
})
神策双报是通过 iframe 上报实现的,没有特殊需求时,并不会使用到神策双报。
- 有无使用神策双报的区别在于:
XTracker.getSensors()
返回值(即下述的 sensors) 和 callback 中的sensors
定义的变化。
- 如果未使用神策双报:
sensors = window.sensors
,支持所有神策方法 - 如果使用神策双报:
sensors = 内部实例化的神策对象
,目前仅支持 sensors.registerPage 方法 - 不开启(使用)神策上报时,sensors 为 null
- 如果是从 1.x 版本升级到 2.x 的,并且需要使用神策双报时:需要注意原本使用
window.sensors.registerPage
的地方,需要做修改。(因为不替换的话,会导致上报到双报地址的数据缺失注册的公共属性)
-
步骤1: 先用
XTracker.getSensors()
获取实例化对象const getSensors = async () => { const sensorsInstance = await XTracker.getSensors() console.og('sensorsInstance', sensorsInstance) } getSensors()
-
步骤2: 把原本的
window.sensors
替换为上面获取的sensorsInstance
如果不存在需要异步获取参数,再注册公共属性的情况,可以直接在 XTracker.init 的 callback 中通过回调参数 sensors.registerPage
调用。
- 使用双报功能后,全埋点和点击图相关的数据采集上报,不支持上报到 subServerUrl,只能上报到 serverUrl。
不支持的原因:神策双报的实现机制是在当前页面创建一个 iframe,然后通过该 iframe 执行数据上报。由于 iframe 中本身没有任何页面元素,因此无法采集到当前页面上的元素信息。这导致
sensors.quick('autoTrack')
和XTracker.init.sensors.heatmap
等功能无法将全埋点数据上报到 subServerUrl。