## 安装

```
npm install @x-edu/hub-tracker
```

## 使用

> 关于qt的用法详见：https://help.aliyun.com/document_detail/602417.html#title-hh8-ors-p02

### 初始化

```js
import { HTracker, defaultCallback } from '@x-edu/hub-tracker'

/**
 * 完成 SDK 加载，以及 qt 的初始化功能
 * （ SDK 加载完成后的业务相关内容请放在 callback 中，@x-edu/hub-tracker 提供了默认的 defaultCallback，如果不能满足业务需要，请使用自定义回调）
 */
HTracker.init({
  // QT 初始化配置参数
  qt: {
    serverUrl: '', // 必传，数据接收地址
    appKey: '', // 必传，集成应用的appKey
    trackHost: '', // 必传，采集日志上报域名
    bridge: true // 是否开启 app 代理上报。boolean | ()=>boolean，默认true（只在被 app 内嵌时有效）。aplus-jsbridge-only
    enable: true, // 是否启用。boolean，默认 true
    clientId: '' // 通用参数 client_id，该参数由外部(区域平台)传入
  },
  // 完成 SDK 加载后的回调
  // qt: qt对象（qt.push.xx）
  callback: ({ qt }) => {
    // 需要 qt iframe双报时，可以调用该默认方法（请自行根据业务需要判断是否调用）。
    defaultCallback.qt({
      subAppkey: '', // 必传
      subTrackingHost: '', // 必传
      subSdkUrl: '' // 必传
    })
  }
})
```

### 上报
请结合 [关于qt上报的注意事项](#tips) 一起看
#### 点击埋点（注：需在 HTracker.init 完成后调用）

```js
HTracker.track({
  eventName: '', // 事件名
  pageName = eventName, // 页面名。可选，默认等于事件名
  eventType = 'CLK' // qt事件类型：'EXP' | 'CLK' | 'OTHER'。可选，默认为 'CLK'，如有需要可进行覆盖
  params: {} // 事件参数
})
```
#### PV 埋点（注：需在 HTracker.init 完成后调用）

```js
HTracker.pv({
  eventName: '', // 事件名
  pageName = eventName, // 页面名。可选，默认等于事件名
  params: {} // 事件参数
})
```

### 关于 window.aplus_queue

qt对象，相当于 HTracker.init 中 callback 的回调参数 qt。

注意：`window.aplus_queue` 需要在 HTracker.init 完成后使用，否则 window 上不存在该属性。

需要调整 qt 的功能时，请在 HTracker.init 完成后使用 `window.aplus_queue.push` 或在 HTracker.init 的 callback 中通过回调参数  `qt.push` 调用。
   
使用示例：
qt覆盖全局属性（https://help.aliyun.com/document_detail/602417.html#c3ddace087ocg）

```js
window.aplus_queue.push({
  action: 'aplus.setMetaInfo',
  arguments: ['globalproperty', {
    xxx: xxx
  }]
})
```

<h3 id="tips">关于qt上报的注意事项</h3>

在 @x-edu/hub-tracker 中，考虑到会有异步采集信息的需要，所以 qt 采集上报方式为手动上报。

***逻辑是在 sdk 内设置了 BLOCK 埋点（_hold=BLOCK），阻塞上报，直到设置 _hold=START 后，事先被 block 住的日志才会携带上用户信息逐条发出。***

为了 qt 能够正常上报，需要在调用 HTracker.track 或 HTracker.pv 前，执行以下方法：

```js
window.aplus_queue.push({
  action: 'aplus.setMetaInfo',
  arguments: ['_hold', 'START'] 
});
```

tips：如果没有采集异步信息的需要，可以将上述代码直接放在 HTracker.init 的 callback 中，通过 `qt.push` 调用，之后再去调用 HTracker.track 或 HTracker.pv 上报数据。

> 如果还有疑问，这里附上 qt 文档里关于设置 _hold=BLOCK 的一些应用，以帮助你更好地理解：
> https://help.aliyun.com/document_detail/602417.html#706ac2b086560