zmdms-track

v0.1.7

Published

10 months ago

``` yarn add zmdms-track --registry https://registry.npmmirror.com ```

0High
0Medium
0Low

下载

yarn add zmdms-track --registry https://registry.npmmirror.com

引入

import ZmdmsTrack from  'zmdms-track';

<script src="zmdms-track.min.js"></script>

用法

初始化

在入口处初始化

// 初始实例化
const zmdmsTrackInstance = new ZmdmsTrack({
	// 初始化传递的基础信息
	basicInfo: {
		system: '', // 系统标识
		appName: '', // 应用名称, app端专用
		appVersion: '', // 应用版本，app端专用
		offlineVersion: '', // 离线包版本，app端专用
		userCode: '', // 用户工号
		createBy: '', // 用户姓名
		runtimeInfo: {
			uuid: '', // 设备码 移动端专属
			buildVersion: '', // 构建版本 移动端专属
		}
	},
	// 是否开启调试
	isDebugger: false,
	// 数据存储key
	cacheKey: 'cache_key_001',
	// 全局监听按钮的行为
	globalClickListeners: [
        {
            selector: "button",
            callback: (data) => {
              console.log("点击了全局按钮", data);
              // 某些条件不需要上报
              if (data.innerText === "儿豁") {
                return {
                  isTrack: false,
                };
              }
            },
        },
	],
	// 个性化处理发送请求事件
	report: {
		url: '',
		reportType: 'http',
		nonHttpMethod: jsBridge,
	}
});

用户自定义事件

用户可以自定义事件，调用实例方法即可

// 直接上报数据
zmdmsTrackInstance.report({
    eventKey: '', // 事件类型 'click' | 'error' 等等，客户端需要整体控制下这个类型，以便后续统计分析
    eventValue: '', // 事件描述
    extra: '', // 扩展信息
})

// 存储上报数据 ，等待合适时机上报
zmdmsTrackInstance.add({
    eventKey: '',
    eventValue: '',
    extra: '',
})

可以在适当时机更新基础信息，如果有需要的话

// 如果想要更新基础信息
zmdmsTrackInstance.updateBasicInfo({
	system: '', // 系统标识
	appName: '', // 应用名称, app端专用
	appVersion: '', // 应用版本，app端专用
	offlineVersion: '', // 离线包版本，app端专用
	userCode: '', // 用户工号
	createBy: '', // 用户姓名
	runtimeInfo: {
		uuid: '', // 设备码 移动端专属
		buildVersion: '', // 构建版本 移动端专属
	}
})

注意事项

开启 debugger

new ZmdmsTrack({
	...,
	// TODO: 线上环境不要开启debugger，开发环境是否开启 自行选择
	isDebugger: process.env.NODE_ENV === 'development',
	...,
})

如果初始化时，没有一些基础信息（像 uuid）等可以通过 updateBasicInfo 方法设置

instance.updateBasicInfo({
	...,
	runtimeInfo: {
		uuid: '', // 设备码 移动端专属
		buildVersion: '', // 构建版本 移动端专属
	}
	...,
})

配置参数

IOptions

| 选项 | 描述 | 类型 | 默认 | | -------------------- | ------------------------------------------------------------ | ---------------------- | ------------------------ | | basicInfo | 初始化时传递的基础信息 | IBasicInfo | 内部自动填充一些信息 | | pvReport | 是否开启 PV 统计(在微前端下，子应用应该不需要开启 pv) | boolean | true | | countPvType | 统计 PV 的方式 repeat：每次路由切换都会统计single：不刷新页面统计不会重新计数已经统计过的路由 | "repeat""single" | repeat | | uvReport | 是否开启UV统计 | boolean | true | | uvMaxTime | 统计UV的最大时间间隔（uvByDay的优先级高于这个） | number | 24 * 60 * 60 * 1000 | | uvByDay | 是否按天统计UV | boolean | true | | customUvReport | 自定义统计UV。UV的统计方式完全由系统自定义。如果传入了这个参数，需要完成记录 UV和上报UV的行为。(即判断是否记录UV和调用实例的add方法记录UV都由自己去实现) | function | null | | | getUVKey | 返回自定义统计UV的key值。主要是在基座下面，需要统计各个系统的UV访问情况，需要通过这个参数来识别当前路由属于哪个系统，并记录一个这个系统的专属UVkey。内部会实现统计UV和上报UV的行为。 | function | | | isTriggerPathUv | 路由发生改变时，是否触发UV统计，需要返回一个boolean值。具体是否记录上报UV，具体要看UV的统计规则。默认时按天系统是否被访问。 | function | | | report | 上传的接口信息 | IReport | 有默认值，通常不需要处理 | | errorReport | 是否开启报错上报(默认会统计 error、unhandledrejection 事件) | boolean | true | | performanceReport | 是否开启页面性能上报(默认会统计FCP FID LCP CLS TTFB) | boolean | false | | hashchangeReport | 是否开启 hash 变化上报 | boolean | true | | historyReport | 是否开启 history 变化上报 | boolean | true | | isDebugger | 是否开启 debugger | boolean | false | | historyUrlsNum | 记录路由最大长度 | number | 4 | | cacheMaxNum | 缓存上报数据的阈值；超过这个长度后，立即上报 | number | 15 | | reportMaxNum | 每次上报请求最长数据条数 | number | 20 | | cacheKey | 数据存储 key | string | 确保存储 key 唯一 | | globalClickListeners | 全局点击监听 | IGlobalClickListener[] | | | dataRewrite | 插入数据重写方法。如果需要对插入的数据做重写的话，可以传入这个参数。 | (data:IData) =>IData | (data) => data; |

IBasicInfo

| 选项 | 描述 | 类型 | 默认 | | -------------- | ---------------------- | ------------------ | --------------------------- | | system | 系统标识 | string | number | | | systemName | 系统标识名称 | string | | | client | 客户端标识 | string(web app h5) | 默认会从UA中判断(web还是h5) | | appName | 应用名称，app 端专用 | stirng | | | appVersion | 应用版本，app 端专用 | stirng | | | offlineVersion | 离线包版本，app 端专用 | string | | | userCode | 用户工号 | string | number | | | createBy | 用户姓名 | string | | | orgId | 部门信息 | string | | | navigator | 浏览器信息 | string | 内部会自动获取 | | runtimeInfo | 设备相关信息 | IDeviceInfo | 内部会自动获取一部分 |

IDeviceInfo

| 选项 | 描述 | 类型 | 默认 | | ------------ | ------------------- | ------ | ------------ | | os | 系统信息 | string | 内部自动获取 | | device | 设备信息 | string | 内部自动获取 | | engine | 浏览器内核 | stirng | 内部自动获取 | | browser | 浏览器信息 | string | 内部自动获取 | | uuid | 设备码移动端专属 | string | | | buildVersion | 构建版本移动端专属 | string | |

IReport (自定义上传配置)

| 选项 | 描述 | 类型 | 默认 | | ------------- | ------------------------------------------------------------ | ---------------------------- | ------------------------------------ | | url | 埋点接口地址 | string | /api/zmdms-log/event-tracking/submit | | reportType | 请求的方式（http会默认调用fetch） | http | beacon | | | headers | 请求头 | | | | format | 上报数据格式化 | (data: IData[]) => IData[] | | | customReport | 请求完全自定义(外部不要将异常捕获。异常捕获会导致，如果上报接口失败了，内部无法判断是否成功，会直接清空数据) | (data: IData[]) => Promise | | | isReport | 自定义决定是否上报 | (data: IData[]) => boolean; | | | nonHttpMethod | 非http、https场景下的请求方法。当在这些场景下会先取这个方法发送请求。但是这个方法要支持下面这种调用方式。在我们项目中一般指h5的flutter场景。 | | | | | | | |

nonHttpMethod({
	url: url,
    method: "POST",
    headers: {
    	"Content-Type": "application/json",
    	...report.headers,
    },
    body: JSON.stringify({
    	eventTrackings: reportData,
    }),
})
.then((res) => {
	if (res.status !== 200) {
		throw new Error("上报失败");
	}
});

IGlobalClickListener

| 选项 | 描述 | 类型 | 默认 | | ------------ | ------------------------------------------------------------ | ------------------- | ----------- | | selector | 选择器 | string | | | elementText | 元素文本 | string | | | callback | 交给开发自行处理的时机。根据传递的data信息（包含：targetEl,currentEl,innerText）来判断是否需要执行埋点。如果不需要执行埋点。这个方法应该return { isTrack: false }。需要埋点不需要返回isTrack字段。但是可以返回一些用于统计的数据，如果有需要的话。 | (data: any) => any; | ----------- | | | | | |

实例方法

instance.add (存储到本地，等待合适的时机发送)

//
instance.add({
	eventKey: 'click',
	eventValue: '埋点测试',
	extra: JSON.stringify({ message: '用户提交了合同信息' }),
})

instance.report (立即上报)

instance.report({
	eventKey: 'click',
	eventValue: '埋点测试',
	extra: JSON.stringify({ message: '用户提交了合同信息' }),
})

instance.updateBasicInfo (修改基础信息)

instance.updateBasicInfo({
	system: '', // 系统标识
	appName: '', // 应用名称, app端专用
	appVersion: '', // 应用版本，app端专用
	offlineVersion: '', // 离线包版本，app端专用
	userCode: '', // 用户工号
	createBy: '', // 用户姓名
	runtimeInfo: {
		uuid: '', // 设备码 移动端专属
		buildVersion: '', // 构建版本 移动端专属
	}
})

项目地址

https://gitlab.zmd.com.cn/zmdms-core/front/zmdms-track

其他说明

上报接口说明：
默认接口是：/api/zmdms-log/event-tracking/submit。如果是外部系统需要接入的话，需要配置全路径，要么就做转发到运管这边的服务器。
上报缓存的最大数据长度：

默认是15条会上报一次（除非是异常或者主动立即上报的行为）

单次上报最大长度：
默认是20条
上报接口失败处理
失败超过3次后，会5分钟内不进行任何上报