❤
npm
Sign UpSign In

zmdms-track
TypeScript icon, indicating that this package has built-in type declarations

0.1.7 • Public • Published

下载

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

引入

  • es
import ZmdmsTrack from  'zmdms-track';
  • umd
<script src="zmdms-track.min.js"></script>

用法

  1. 初始化

    在入口处初始化

    // 初始实例化
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,
	}
});

  2. 用户自定义事件

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

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

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

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

    // 如果想要更新基础信息
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分钟内不进行任何上报

Readme

Keywords

none

Package Sidebar

Install

npm i zmdms-track

Weekly Downloads

57

Version

0.1.7

License

ISC

Unpacked Size

386 kB

Total Files

34

Last publish

Collaborators

  • cyxwmm
Try on RunKit
Report malware