# x-tracker

> 前端埋点API

Latest version **1.2.0** (published 2021-01-25) · ISC license · 0 weekly downloads

## Install

```sh
npm install x-tracker
pnpm add x-tracker
yarn add x-tracker
bun add x-tracker
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2021-01-25 |
| First published | 2021-01-19 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 41.1 KB |
| Known vulnerabilities | 0 (+23 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | ex-jd |

## Links

- npm: https://www.npmjs.com/package/x-tracker
- npm.io page: https://npm.io/package/x-tracker

## Dependencies (1)

- [axios](https://npm.io/package/axios.md) ^0.21.1

## Recent versions

- 1.2.0 (latest) — 2021-01-25
- 1.1.12 — 2021-01-21
- 1.1.11 — 2021-01-21
- 1.1.10 — 2021-01-21
- 1.1.9 — 2021-01-21
- 1.1.8 — 2021-01-21
- 1.1.7 — 2021-01-20
- 1.1.6 — 2021-01-20
- 1.1.5 — 2021-01-20
- 1.1.4 — 2021-01-20
- 1.1.3 — 2021-01-20
- 1.1.2 — 2021-01-20
- 1.1.1 — 2021-01-20
- 1.1.0 — 2021-01-20
- 1.0.13 — 2021-01-19
- … 13 more at https://npm.io/package/x-tracker/versions

## README

# X-Tracker埋点工具

该工具用于前端项目埋点，核心为XT函数，执行该函数使用不同的命令，传递不同的参数，实现数据的记录。注意：XT函数执行的命令都没有返回值。

该埋点工具仅适用于浏览器环境，小程序的支持有待开发。

## 插件使用

`npm install x-tracker -D`

`import XT from "x-tracker"`

该方式需要babel进行转化。

另外提供一种引入方式

`require("x-tracker/dist/xTracker.min.js")`

这种方式会在window对象上添加XT类，直接使用`window.XT`即可

## 如何执行命令

我们一般使用XT类构造的命令函数，即：`const xt = new XT(apiUrl)`;

XT的构造函数传入请求的api URL，该实例下使用的所有埋点请求都将使用这个api进行发送。构造函数返回了一个命令执行函数，可以对该函数传入具体的命令和参数：`xt('CommandName', <arguments>)`

注意：建议使用实例的命令函数进行调用，从这个入口调用的所有方法有完善的校验，保证发送数据的正确性。

## 可执行的命令

命令执行前会进行校验，只有被许可的命令可以执行，目前包括`create use set pageview event timing`

### 创建跟踪器
跟踪器的创建命令十分重要，其他的命令都依赖于该命令的执行。

`const xt = new XT(apiUrl);
 xt('create', 'TrackId', 'TrackName')`
 
 其中，TrackId表征着一组跟踪器，通常与系统挂钩，不能为空，即，一个系统对应同一个TrackId。
 TrackName则代表着不同的跟踪器，
 你可以在一个系统（TrackId）下构建多个跟踪器，但不允许创建相同的跟踪器名称（即便是在不同TrackId下）。默认情况下，`TrackName`取`default`
 
 `以下命令介绍时统一使用上述xt的命令函数`
 
 ### 跟踪器命令
 跟踪器的命令执行需要先对跟踪器进行创建。在执行命令时，需要指定有效的跟踪器名称。指定跟踪器名称只需要在命令前加上TrackName即可。
 
 `xt('TrackName.CommandName', <arguments>)`
 
 名称为`default`的跟踪器在执行命令时，可以忽略跟踪器名称。
 接下来的介绍以名称为`default`的跟踪器来举例。
 
 ### use
 为跟踪器添加一个拦截方法，该方法会对埋点请求进行拦截，针对参数进行处理，然后将发送处理后的参数。拦截方法仅适用于定义特定TrackName的跟踪器。
 
 `xt('use', function(params){ /* ... */ })`
 
 ### set
 为跟踪器设定跟踪器协议。通俗说来，对特定TrackName的跟踪器设置全局参数。
 
 `xt('set', 'key', 'value')`
 
 或者
 
 `xt('set', {
   key1: 'value1',
   key2: 'value2'
 })`
 
 注意：如果是设置单个属性，key和value是必须填写的
 
 ### pageview
 发送页面曝光的埋点数据。
 
 `xt('pageview', fields)`
 
 其中，fields包含本次埋点的数据包协议，即埋点维度，数据协议以外的特殊字段需要在`fields.extend`字段里进行设置，以下发送数据的命令不再赘述。
 
 注意：埋点工具会自动填写页面相关的参数，在fields里无法进行覆盖。如果硬要修改，在use命令里进行拦截修改。
 
 ### event
 发送事件类的埋点数据
 
 `xt('event', 'eventName', 'eventValue', fields)`
 
或

 `xt('event', 'eventName', fields)`
 
或

 `xt('event', fields)`
 
 ### timing
 发送计时类的数据埋点
 
 `xt('timing', 'status', fields)`
 
 计时类的数据埋点比较特殊，需要在开始计时时调用一次，结束计时时再调用一次，才会发送埋点请求。
 
 `status`用来区分是开始计时还是结束计时，取值为`start` 或 `end`，其他取值抛错。
 
### print
输出埋点数据

`xt('print')`

控制台输出以当前TrackId 和 TrackName 进行查询埋点数据。

注意：该方法仅在预发环境可以使用。

---
_Source: https://npm.io/package/x-tracker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._