@x-edu/tracker

安装

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.init 完成后调用）

XTracker.track({
  eventName: '', // 事件名
  params: {  // 事件参数
    event_type: 'clickEvent' | 'businessEvent', // 神策事件类型，可选，默认为 clickEvent，如有需要可进行覆盖
    ...otherParams
  }
})

PV 埋点（注：需在 XTracker.init 完成后调用）

XTracker.pv({
  eventName: '', // 事件名
  params // 事件参数（传不传 event_type 都可以，神策上报时会自动加上 event_type: 'pageEvent'）
})

关于 window.sensors（仅针对未使用神策双报的情况）

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: ''
})

关于使用神策双报的注意事项（2.0.0 版本开始支持）

神策双报是通过 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。