@jasolar/tracker-sdk 1.0.5 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -72,7 +72,28 @@ import { performancePlugin, errorPlugin, routerPlugin, autoTracker } from '@jaso
72
72
 
73
73
  tracker.use(performancePlugin);
74
74
  tracker.use(errorPlugin);
75
+
76
+ // 路由监控 - 基础用法(监听所有路由)
75
77
  tracker.use(routerPlugin);
78
+
79
+ // 路由监控 - 只监听指定路由(白名单)
80
+ tracker.use(routerPlugin, {
81
+ system: 'my-app',
82
+ include: ['/dashboard', '/user/*', /^\/product\//]
83
+ });
84
+
85
+ // 路由监控 - 排除指定路由(黑名单)
86
+ tracker.use(routerPlugin, {
87
+ system: 'my-app',
88
+ exclude: ['/login', '/register', '/admin/*']
89
+ });
90
+
91
+ // 路由监控 - 自定义过滤函数
92
+ tracker.use(routerPlugin, {
93
+ system: 'my-app',
94
+ filter: (path) => !path.startsWith('/test-') // 排除测试路由
95
+ });
96
+
76
97
  tracker.use(autoTracker);
77
98
  ```
78
99
 
@@ -95,8 +116,8 @@ tracker.enter({
95
116
  - **options.appId**: 应用唯一标识。
96
117
 
97
118
  ### `tracker.enter(module)`
98
- 记录进入某个模块/页面的开始。
99
- - **module**: 对象,通常包含 `module` (模块名), `sub_module` (子模块名) 等字段。调用此方法会自动计算上一个模块的停留时长并上报。
119
+ 记录进入某个模块/页面的开始,并自动上报 `module_enter` 事件。
120
+ - **module**: 对象,通常包含 `system` (系统名), `module` (模块名), `sub_module` (子模块名) 等字段。调用此方法会自动计算上一个模块的停留时长并上报 `module_leave` 事件,然后上报当前模块的 `module_enter` 事件。
100
121
 
101
122
  ### `tracker.leave()`
102
123
  手动记录离开当前模块。通常配合 `enter` 使用。在 `enter` 新模块或页面关闭/隐藏时会自动触发。
@@ -118,6 +139,52 @@ tracker.enter({
118
139
  加载并启用插件。
119
140
  - **plugin**: 插件函数。用于扩展 SDK 的采集能力(如 `performancePlugin`, `errorPlugin` 等)。
120
141
 
142
+ #### Router Plugin 配置选项
143
+
144
+ `routerPlugin` 支持以下配置项:
145
+
146
+ ```javascript
147
+ tracker.use(routerPlugin, {
148
+ system: 'my-app', // 系统标识,默认 'router'
149
+
150
+ // 模块名称映射函数(可选)
151
+ moduleMapper: (path) => {
152
+ if (path === '/dashboard') return '仪表盘';
153
+ return path;
154
+ },
155
+
156
+ // 白名单:只监听这些路由(可选)
157
+ include: [
158
+ '/dashboard', // 完全匹配
159
+ '/user/*', // 前缀匹配(所有 /user/ 开头的路径)
160
+ /^\/product\/\d+$/ // 正则表达式匹配
161
+ ],
162
+
163
+ // 黑名单:排除这些路由(可选)
164
+ exclude: [
165
+ '/login',
166
+ '/admin/*'
167
+ ],
168
+
169
+ // 自定义过滤函数(优先级最高)
170
+ filter: (path) => {
171
+ // 返回 true 表示追踪,false 表示不追踪
172
+ return !path.startsWith('/test-');
173
+ }
174
+ });
175
+ ```
176
+
177
+ **过滤选项说明:**
178
+ - **include**(白名单):只有匹配的路由会被追踪,其他路由被忽略
179
+ - **exclude**(黑名单):匹配的路由不会被追踪,其他路由都被追踪
180
+ - **filter**(自定义函数):最灵活的方式,可以实现任意复杂的过滤逻辑
181
+ - **优先级**:filter > include > exclude(如果同时配置多个,只有优先级最高的生效)
182
+
183
+ **匹配模式:**
184
+ - 字符串完全匹配:`'/dashboard'` 匹配 `/dashboard`
185
+ - 字符串前缀匹配:`'/user/*'` 匹配所有以 `/user/` 开头的路径
186
+ - 正则表达式:`/^\/product\/\d+$/` 匹配 `/product/123` 等
187
+
121
188
  ## 插件系统
122
189
 
123
190
  SDK 通过插件机制扩展功能。目前内置支持:
package/dist/index.cjs.js CHANGED
@@ -486,6 +486,29 @@ var Tracker = /*#__PURE__*/function () {
486
486
  this.current = _objectSpread2(_objectSpread2({}, module), {}, {
487
487
  enterTime: now()
488
488
  });
489
+
490
+ // 构建 context 对象
491
+ var context = {
492
+ device_id: this.deviceId,
493
+ session_id: this.sessionId,
494
+ user_id: this.userId
495
+ };
496
+
497
+ // 构建 ext 对象(合并全局扩展参数和当前模块的额外信息)
498
+ var extData = _objectSpread2(_objectSpread2({}, this.globalExt), this.current.ext);
499
+
500
+ // 上报 module_enter 事件
501
+ var event = {
502
+ system: this.current.system || '',
503
+ module: this.current.module || '',
504
+ sub_module: this.current.sub_module || '',
505
+ duration: 0,
506
+ event: 'module_enter',
507
+ timestamp: formatTime(now()),
508
+ context: context,
509
+ ext: extData
510
+ };
511
+ this.queue.push(event);
489
512
  }
490
513
 
491
514
  /**
@@ -689,13 +712,22 @@ function errorPlugin(tracker) {
689
712
  * @param {Object} options - 插件配置项
690
713
  * @param {string} [options.system='router'] - 系统标识,默认为 'router'
691
714
  * @param {Function} [options.moduleMapper] - 自定义模块名称映射函数,接收路径作为参数,返回模块名称
715
+ * @param {Array<string>} [options.include] - 白名单:只监听匹配的路由(支持字符串前缀匹配或正则表达式)
716
+ * @param {Array<string>} [options.exclude] - 黑名单:排除匹配的路由(支持字符串前缀匹配或正则表达式)
717
+ * @param {Function} [options.filter] - 自定义过滤函数,接收路径作为参数,返回 true 表示需要追踪
692
718
  */
693
719
  function routerPlugin(tracker) {
694
720
  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
695
721
  var _options$system = options.system,
696
722
  system = _options$system === void 0 ? 'router' : _options$system,
697
723
  _options$moduleMapper = options.moduleMapper,
698
- moduleMapper = _options$moduleMapper === void 0 ? null : _options$moduleMapper;
724
+ moduleMapper = _options$moduleMapper === void 0 ? null : _options$moduleMapper,
725
+ _options$include = options.include,
726
+ include = _options$include === void 0 ? null : _options$include,
727
+ _options$exclude = options.exclude,
728
+ exclude = _options$exclude === void 0 ? null : _options$exclude,
729
+ _options$filter = options.filter,
730
+ filter = _options$filter === void 0 ? null : _options$filter;
699
731
 
700
732
  // 获取完整路径:pathname + search + hash
701
733
  var lastPath = window.location.pathname + window.location.search + window.location.hash;
@@ -712,6 +744,66 @@ function routerPlugin(tracker) {
712
744
  return path;
713
745
  };
714
746
 
747
+ /**
748
+ * 检查路径是否应该被追踪
749
+ * @param {string} path - 要检查的路径
750
+ * @returns {boolean} - 是否应该追踪
751
+ */
752
+ var shouldTrack = function shouldTrack(path) {
753
+ // 如果提供了自定义过滤函数,优先使用
754
+ if (typeof filter === 'function') {
755
+ return filter(path);
756
+ }
757
+
758
+ // 检查白名单
759
+ if (include && include.length > 0) {
760
+ var isIncluded = include.some(function (pattern) {
761
+ return matchPath(path, pattern);
762
+ });
763
+ if (!isIncluded) {
764
+ console.log('[Tracker SDK] Route excluded by whitelist:', path);
765
+ return false;
766
+ }
767
+ }
768
+
769
+ // 检查黑名单
770
+ if (exclude && exclude.length > 0) {
771
+ var isExcluded = exclude.some(function (pattern) {
772
+ return matchPath(path, pattern);
773
+ });
774
+ if (isExcluded) {
775
+ console.log('[Tracker SDK] Route excluded by blacklist:', path);
776
+ return false;
777
+ }
778
+ }
779
+ return true;
780
+ };
781
+
782
+ /**
783
+ * 匹配路径和模式
784
+ * @param {string} path - 路径
785
+ * @param {string|RegExp} pattern - 匹配模式(字符串或正则表达式)
786
+ * @returns {boolean} - 是否匹配
787
+ */
788
+ var matchPath = function matchPath(path, pattern) {
789
+ // 如果是正则表达式
790
+ if (pattern instanceof RegExp) {
791
+ return pattern.test(path);
792
+ }
793
+
794
+ // 如果是字符串,进行前缀匹配或完全匹配
795
+ if (typeof pattern === 'string') {
796
+ // 如果模式以 * 结尾,进行前缀匹配
797
+ if (pattern.endsWith('*')) {
798
+ var prefix = pattern.slice(0, -1);
799
+ return path.startsWith(prefix);
800
+ }
801
+ // 否则进行完全匹配
802
+ return path === pattern || path.startsWith(pattern + '?') || path.startsWith(pattern + '#');
803
+ }
804
+ return false;
805
+ };
806
+
715
807
  /**
716
808
  * 追踪页面视图变化
717
809
  */
@@ -725,6 +817,12 @@ function routerPlugin(tracker) {
725
817
  trackerCurrent: tracker.current
726
818
  });
727
819
 
820
+ // 检查是否应该追踪此路由
821
+ if (!shouldTrack(currentPath)) {
822
+ console.log('[Tracker SDK] Route filtered out:', currentPath);
823
+ return;
824
+ }
825
+
728
826
  // 避免重复追踪相同的路径
729
827
  if (currentPath === lastPath) {
730
828
  console.log('[Tracker SDK] Route unchanged:', currentPath, moduleMapper ? moduleMapper(currentPath) : currentPath);
@@ -757,13 +855,19 @@ function routerPlugin(tracker) {
757
855
  // 1. 追踪初始页面加载(延迟执行,确保 DOM 和路由已就绪)
758
856
  setTimeout(function () {
759
857
  var initialPath = window.location.pathname + window.location.search + window.location.hash;
760
- lastPath = initialPath; // 更新 lastPath 为实际初始路径
761
858
 
762
- tracker.enter({
763
- module: getModuleName(initialPath),
764
- system: system
765
- });
766
- console.log('[Tracker SDK] Initial route tracked:', initialPath);
859
+ // 检查初始页面是否应该被追踪
860
+ if (shouldTrack(initialPath)) {
861
+ lastPath = initialPath; // 更新 lastPath 为实际初始路径
862
+
863
+ tracker.enter({
864
+ module: getModuleName(initialPath),
865
+ system: system
866
+ });
867
+ console.log('[Tracker SDK] Initial route tracked:', initialPath);
868
+ } else {
869
+ console.log('[Tracker SDK] Initial route filtered out:', initialPath);
870
+ }
767
871
  }, 0);
768
872
 
769
873
  // 2. 监听 Hash 模式路由变化
package/dist/index.esm.js CHANGED
@@ -484,6 +484,29 @@ var Tracker = /*#__PURE__*/function () {
484
484
  this.current = _objectSpread2(_objectSpread2({}, module), {}, {
485
485
  enterTime: now()
486
486
  });
487
+
488
+ // 构建 context 对象
489
+ var context = {
490
+ device_id: this.deviceId,
491
+ session_id: this.sessionId,
492
+ user_id: this.userId
493
+ };
494
+
495
+ // 构建 ext 对象(合并全局扩展参数和当前模块的额外信息)
496
+ var extData = _objectSpread2(_objectSpread2({}, this.globalExt), this.current.ext);
497
+
498
+ // 上报 module_enter 事件
499
+ var event = {
500
+ system: this.current.system || '',
501
+ module: this.current.module || '',
502
+ sub_module: this.current.sub_module || '',
503
+ duration: 0,
504
+ event: 'module_enter',
505
+ timestamp: formatTime(now()),
506
+ context: context,
507
+ ext: extData
508
+ };
509
+ this.queue.push(event);
487
510
  }
488
511
 
489
512
  /**
@@ -687,13 +710,22 @@ function errorPlugin(tracker) {
687
710
  * @param {Object} options - 插件配置项
688
711
  * @param {string} [options.system='router'] - 系统标识,默认为 'router'
689
712
  * @param {Function} [options.moduleMapper] - 自定义模块名称映射函数,接收路径作为参数,返回模块名称
713
+ * @param {Array<string>} [options.include] - 白名单:只监听匹配的路由(支持字符串前缀匹配或正则表达式)
714
+ * @param {Array<string>} [options.exclude] - 黑名单:排除匹配的路由(支持字符串前缀匹配或正则表达式)
715
+ * @param {Function} [options.filter] - 自定义过滤函数,接收路径作为参数,返回 true 表示需要追踪
690
716
  */
691
717
  function routerPlugin(tracker) {
692
718
  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
693
719
  var _options$system = options.system,
694
720
  system = _options$system === void 0 ? 'router' : _options$system,
695
721
  _options$moduleMapper = options.moduleMapper,
696
- moduleMapper = _options$moduleMapper === void 0 ? null : _options$moduleMapper;
722
+ moduleMapper = _options$moduleMapper === void 0 ? null : _options$moduleMapper,
723
+ _options$include = options.include,
724
+ include = _options$include === void 0 ? null : _options$include,
725
+ _options$exclude = options.exclude,
726
+ exclude = _options$exclude === void 0 ? null : _options$exclude,
727
+ _options$filter = options.filter,
728
+ filter = _options$filter === void 0 ? null : _options$filter;
697
729
 
698
730
  // 获取完整路径:pathname + search + hash
699
731
  var lastPath = window.location.pathname + window.location.search + window.location.hash;
@@ -710,6 +742,66 @@ function routerPlugin(tracker) {
710
742
  return path;
711
743
  };
712
744
 
745
+ /**
746
+ * 检查路径是否应该被追踪
747
+ * @param {string} path - 要检查的路径
748
+ * @returns {boolean} - 是否应该追踪
749
+ */
750
+ var shouldTrack = function shouldTrack(path) {
751
+ // 如果提供了自定义过滤函数,优先使用
752
+ if (typeof filter === 'function') {
753
+ return filter(path);
754
+ }
755
+
756
+ // 检查白名单
757
+ if (include && include.length > 0) {
758
+ var isIncluded = include.some(function (pattern) {
759
+ return matchPath(path, pattern);
760
+ });
761
+ if (!isIncluded) {
762
+ console.log('[Tracker SDK] Route excluded by whitelist:', path);
763
+ return false;
764
+ }
765
+ }
766
+
767
+ // 检查黑名单
768
+ if (exclude && exclude.length > 0) {
769
+ var isExcluded = exclude.some(function (pattern) {
770
+ return matchPath(path, pattern);
771
+ });
772
+ if (isExcluded) {
773
+ console.log('[Tracker SDK] Route excluded by blacklist:', path);
774
+ return false;
775
+ }
776
+ }
777
+ return true;
778
+ };
779
+
780
+ /**
781
+ * 匹配路径和模式
782
+ * @param {string} path - 路径
783
+ * @param {string|RegExp} pattern - 匹配模式(字符串或正则表达式)
784
+ * @returns {boolean} - 是否匹配
785
+ */
786
+ var matchPath = function matchPath(path, pattern) {
787
+ // 如果是正则表达式
788
+ if (pattern instanceof RegExp) {
789
+ return pattern.test(path);
790
+ }
791
+
792
+ // 如果是字符串,进行前缀匹配或完全匹配
793
+ if (typeof pattern === 'string') {
794
+ // 如果模式以 * 结尾,进行前缀匹配
795
+ if (pattern.endsWith('*')) {
796
+ var prefix = pattern.slice(0, -1);
797
+ return path.startsWith(prefix);
798
+ }
799
+ // 否则进行完全匹配
800
+ return path === pattern || path.startsWith(pattern + '?') || path.startsWith(pattern + '#');
801
+ }
802
+ return false;
803
+ };
804
+
713
805
  /**
714
806
  * 追踪页面视图变化
715
807
  */
@@ -723,6 +815,12 @@ function routerPlugin(tracker) {
723
815
  trackerCurrent: tracker.current
724
816
  });
725
817
 
818
+ // 检查是否应该追踪此路由
819
+ if (!shouldTrack(currentPath)) {
820
+ console.log('[Tracker SDK] Route filtered out:', currentPath);
821
+ return;
822
+ }
823
+
726
824
  // 避免重复追踪相同的路径
727
825
  if (currentPath === lastPath) {
728
826
  console.log('[Tracker SDK] Route unchanged:', currentPath, moduleMapper ? moduleMapper(currentPath) : currentPath);
@@ -755,13 +853,19 @@ function routerPlugin(tracker) {
755
853
  // 1. 追踪初始页面加载(延迟执行,确保 DOM 和路由已就绪)
756
854
  setTimeout(function () {
757
855
  var initialPath = window.location.pathname + window.location.search + window.location.hash;
758
- lastPath = initialPath; // 更新 lastPath 为实际初始路径
759
856
 
760
- tracker.enter({
761
- module: getModuleName(initialPath),
762
- system: system
763
- });
764
- console.log('[Tracker SDK] Initial route tracked:', initialPath);
857
+ // 检查初始页面是否应该被追踪
858
+ if (shouldTrack(initialPath)) {
859
+ lastPath = initialPath; // 更新 lastPath 为实际初始路径
860
+
861
+ tracker.enter({
862
+ module: getModuleName(initialPath),
863
+ system: system
864
+ });
865
+ console.log('[Tracker SDK] Initial route tracked:', initialPath);
866
+ } else {
867
+ console.log('[Tracker SDK] Initial route filtered out:', initialPath);
868
+ }
765
869
  }, 0);
766
870
 
767
871
  // 2. 监听 Hash 模式路由变化
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jasolar/tracker-sdk",
3
- "version": "1.0.5",
3
+ "version": "1.0.7",
4
4
  "type": "module",
5
5
  "main": "dist/index.cjs.js",
6
6
  "module": "dist/index.esm.js",