x-tracker v1.2.0

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 进行查询埋点数据。

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