@fle-sdk/event-tracking-web 1.2.3 → 1.2.5

package/README.md

@@ -1,6 +1,6 @@
 > **构建用户数据体系，让用户行为数据发挥深远的价值。**
 
-**当前版本**: v1.2.3
+**当前版本**: v1.2.4
 
 ## 前言
 
@@ -209,6 +209,10 @@ WebTracking
 | sendMethod                        | string               | 数据发送方式：auto（自动选择）、xhr（XMLHttpRequest）、beacon（sendBeacon） | 否           | auto       |
 | autoTrackPageDurationInterval    | boolean              | 是否定时上报页面停留时长                                     | 否           | false      |
 | pageDurationInterval              | number               | 定时上报页面停留时长的间隔时间（毫秒）                        | 否           | 30000      |
+| autoTrackExposure               | boolean              | 是否启用曝光埋点                                             | 否           | false      |
+| exposureThreshold              | number               | 曝光进入可视区判定阈值（0-1之间）                            | 否           | 0.5        |
+| exposureTime                  | number               | 曝光可见停留时长阈值（毫秒）                                 | 否           | 500        |
+| exposureNum                  | number               | 同一元素允许上报的最大曝光次数（不传则不限制）                | 否           | 不限制     |
 | pageKey                           | string               | 自定义页面唯一标识，如果不传则自动从路由获取                | 否           | 自动生成   |
 
 #### 例子
@@ -276,6 +280,10 @@ export default App;
 | sendMethod                        | string               | 数据发送方式：auto（自动选择）、xhr（XMLHttpRequest）、beacon（sendBeacon） | 否           | auto       |
 | autoTrackPageDurationInterval    | boolean              | 是否定时上报页面停留时长                                 | 否           | false      |
 | pageDurationInterval              | number               | 定时上报页面停留时长的间隔时间（毫秒）                    | 否           | 30000      |
+| autoTrackExposure               | boolean              | 是否启用曝光埋点                                         | 否           | false      |
+| exposureThreshold              | number               | 曝光进入可视区判定阈值（0-1之间）                        | 否           | 0.5        |
+| exposureTime                  | number               | 曝光可见停留时长阈值（毫秒）                             | 否           | 500        |
+| exposureNum                  | number               | 同一元素允许上报的最大曝光次数（不传则不限制）            | 否           | 不限制     |
 | pageKey                           | string               | 自定义页面唯一标识，如果不传则自动从路由获取            | 否           | 自动生成   |
 
 #### 例子
@@ -969,11 +977,123 @@ WebTracking.init({
 
 两种方式可以同时使用，互不冲突。
 
+### 5.8 元素曝光埋点
+
+SDK 支持自动监听元素曝光事件，适用于需要追踪元素可见性的场景（如商品卡片曝光、广告曝光等）。
+
+#### 触发条件
+
+仅对包含 `data-exposure="true"` 的 DOM 元素做曝光监听与上报（区分大小写，建议统一为字符串 "true"）。
+
+#### 配置参数
+
+- `autoTrackExposure`: 是否启用曝光埋点（默认：false）
+- `exposureThreshold`: 曝光进入可视区判定阈值，0-1之间（默认：0.5）
+- `exposureTime`: 曝光可见停留时长阈值，单位毫秒（默认：500）
+- `exposureNum`: 同一元素允许上报的最大曝光次数（默认：不限制）
+
+#### 工作原理
+
+1. 使用 `IntersectionObserver` API 判定元素是否进入可视区
+2. 元素进入可视区后开始计时
+3. 元素离开可视区时，如果可见时长达到 `exposureTime` 阈值，则上报曝光事件
+4. 如果设置了 `exposureNum`，同一元素超过该次数后不再上报
+
+#### 上报参数提取
+
+从目标元素（或其祖先节点，按"就近原则"）提取所有 `data-*` 属性作为埋点业务参数，规则如下：
+
+- 属性名从 `data-xxx-yyy` 转为 `xxxYyy`（camelCase）
+- 示例：`data-goods-id` → `goodsId`，`data-list-id` → `listId`
+- 排除属性：`data-exposure`、`data-part-key`、`data-desc`
+
+#### 使用示例
+
+```jsx
+WebTracking.init({
+  appKey: "218844",
+  serverUrl: "https://xxx/push",
+  // 启用曝光埋点
+  autoTrackExposure: true,
+  // 元素进入可视区 50% 时判定为可见
+  exposureThreshold: 0.5,
+  // 元素连续可见 500ms 才算一次有效曝光
+  exposureTime: 500,
+  // 同一元素最多上报 3 次曝光
+  exposureNum: 3,
+});
+```
+
+#### HTML 使用示例
+
+```jsx
+<div className="goods-list">
+  <div
+    data-exposure="true"
+    data-part-key="goods_card"
+    data-desc="商品卡片曝光"
+    data-goods-id="12345"
+    data-goods-name="测试商品"
+    data-list-id="home_list"
+  >
+    <img src="goods.jpg" alt="商品图片" />
+    <h3>商品名称</h3>
+  </div>
+
+  <div
+    data-exposure="true"
+    data-part-key="ad_banner"
+    data-desc="广告横幅曝光"
+    data-ad-id="999"
+    data-ad-position="top"
+  >
+    <img src="ad.jpg" alt="广告图片" />
+  </div>
+</div>
+```
+
+#### 上报数据示例
+
+```json
+{
+  "event": "WebExposure",
+  "desc": "商品卡片曝光",
+  "itemKey": "218844.home_page.goods_card",
+  "requestTime": 1709524231171,
+  "deviceId": "1dd539cdea9332ebb9d5c087f9d4471f",
+  "privateParamMap": {
+    "business": {
+      "goodsId": "12345",
+      "goodsName": "测试商品",
+      "listId": "home_list"
+    }
+  }
+}
+```
+
+#### 注意事项
+
+1. **浏览器兼容性**：需要浏览器支持 `IntersectionObserver` 和 `MutationObserver` API，不支持时会自动禁用曝光埋点
+2. **性能优化**：SDK 会自动去重，避免重复监听同一元素
+3. **动态元素**：自动监听动态添加的曝光元素，无需手动调用
+4. **数据提取**：`data-*` 属性会从目标元素向上遍历到 BODY 标签，按"就近原则"提取
+
 ---
 
 ## 六、版本更新日志
 
-### v1.2.3 (最新)
+### v1.2.4 (最新)
+
+- ✨ 新增元素曝光埋点功能
+  - `autoTrackExposure` - 是否启用曝光埋点
+  - `exposureThreshold` - 曝光进入可视区判定阈值（0-1之间）
+  - `exposureTime` - 曝光可见停留时长阈值（毫秒）
+  - `exposureNum` - 同一元素允许上报的最大曝光次数
+  - 使用 `IntersectionObserver` API 判定元素可见性
+  - 自动提取 `data-*` 属性作为业务参数
+  - 支持自定义曝光次数限制
+
+### v1.2.3
 
 - 🐛 修复批量发送数据格式问题
   - 批量发送时直接发送数组，不再包装在 `events` 参数中

package/lib/index.esm.js

@@ -1253,7 +1253,13 @@ function (_super) {
 
     _this.DEFAULT_PENDING_REQUESTS_MAX_SIZE = 50; // LocalStorage 最大大小限制（4MB）
 
-    _this.MAX_STORAGE_SIZE = 4 * 1024 * 1024; // 用户信息
+    _this.MAX_STORAGE_SIZE = 4 * 1024 * 1024; // IntersectionObserver 实例
+
+    _this.exposureObserver = null; // 曝光元素映射
+
+    _this.exposureElementsMap = new Map(); // MutationObserver 实例（用于监听动态添加的元素）
+
+    _this.mutationObserver = null; // 用户信息
 
     _this.userInfo = null; // 当前路由
 
@@ -1267,7 +1273,8 @@ function (_super) {
       PageView: "Web 浏览页面",
       WebClick: "Web 元素点击",
       PageRetained: "Web 页面浏览时长",
-      CustomTrack: "Web 自定义代码上报"
+      CustomTrack: "Web 自定义代码上报",
+      WebExposure: "Web 元素曝光"
     };
     /**
      * @description 初始化函数
@@ -1312,6 +1319,11 @@ function (_super) {
 
       if (_this.initConfig.autoTrackPageDurationInterval) {
         _this.startPageDurationTimer();
+      } // 如果启用了曝光监听，初始化曝光监听
+
+
+      if (_this.initConfig.autoTrackExposure) {
+        _this.initExposureObserver();
       }
     };
     /**
@@ -1372,6 +1384,13 @@ function (_super) {
         _this.startPageDurationTimer();
       } else {
         _this.stopPageDurationTimer();
+      } // 处理曝光监听配置
+
+
+      if (_this.initConfig.autoTrackExposure) {
+        _this.initExposureObserver();
+      } else {
+        _this.stopExposureObserver();
       }
     };
     /**
@@ -1454,6 +1473,36 @@ function (_super) {
 
           break;
 
+        case 'exposureThreshold':
+          if (typeof value !== 'number' || value < 0 || value > 1) {
+            return {
+              valid: false,
+              message: 'exposureThreshold 必须是 0-1 之间的数字'
+            };
+          }
+
+          break;
+
+        case 'exposureTime':
+          if (typeof value !== 'number' || value <= 0) {
+            return {
+              valid: false,
+              message: 'exposureTime 必须是大于 0 的数字'
+            };
+          }
+
+          break;
+
+        case 'exposureNum':
+          if (value !== undefined && (typeof value !== 'number' || value <= 0 || !Number.isInteger(value))) {
+            return {
+              valid: false,
+              message: 'exposureNum 必须是大于 0 的整数或不限制'
+            };
+          }
+
+          break;
+
         case 'showLog':
         case 'autoTrack':
         case 'isTrackSinglePage':
@@ -2780,8 +2829,275 @@ function (_super) {
         return str + ("" + (str.length ? "." : "")) + key;
       }, "");
     };
+    /**
+     * @description 从元素或其祖先节点提取 data-* 属性
+     * @param element 目标元素
+     * @returns 提取的业务参数对象
+     */
+
+
+    _this.extractDataAttributes = function (element) {
+      var business = {};
+      var currentElement = element;
+
+      while (currentElement) {
+        var attributes = currentElement.attributes;
+
+        for (var i = 0; i < attributes.length; i++) {
+          var attr = attributes[i];
+          var name_1 = attr.name;
+
+          if (name_1.startsWith('data-') && name_1 !== 'data-exposure' && name_1 !== 'data-part-key' && name_1 !== 'data-desc') {
+            var value = attr.value;
+
+            if (value) {
+              var camelCaseKey = name_1.replace(/^data-/, '').split('-').map(function (part, index) {
+                return index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1);
+              }).join('');
+              business[camelCaseKey] = value;
+            }
+          }
+        }
+
+        currentElement = currentElement.parentElement;
+
+        if (currentElement && currentElement.tagName === 'BODY') {
+          break;
+        }
+      }
+
+      return business;
+    };
+    /**
+     * @description 初始化曝光监听
+     */
+
+
+    _this.initExposureObserver = function () {
+      if (!_this.initConfig.autoTrackExposure) {
+        return;
+      }
+
+      if (!('IntersectionObserver' in window)) {
+        if (_this.initConfig.showLog) {
+          _this.printLog('当前浏览器不支持 IntersectionObserver，无法启用曝光埋点');
+        }
+
+        return;
+      }
+
+      var threshold = _this.initConfig.exposureThreshold || 0.5;
+      _this.exposureObserver = new IntersectionObserver(function (entries) {
+        entries.forEach(function (entry) {
+          var element = entry.target;
+
+          var elementInfo = _this.exposureElementsMap.get(element);
+
+          if (!elementInfo) {
+            return;
+          }
+
+          var exposureTime = _this.initConfig.exposureTime || 500;
+
+          if (entry.isIntersecting) {
+            elementInfo.isVisible = true;
+            elementInfo.visibleStartTime = _this.getTimeStamp();
+
+            if (elementInfo.exposureTimer) {
+              clearTimeout(elementInfo.exposureTimer);
+            }
+
+            elementInfo.exposureTimer = window.setTimeout(function () {
+              if (elementInfo.isVisible) {
+                _this.reportExposure(element);
+              }
+            }, exposureTime);
+          } else {
+            elementInfo.isVisible = false;
+
+            if (elementInfo.exposureTimer) {
+              clearTimeout(elementInfo.exposureTimer);
+              elementInfo.exposureTimer = null;
+            }
+          }
+        });
+      }, {
+        threshold: threshold
+      });
+
+      _this.observeExposureElements();
+
+      _this.initMutationObserver();
+    };
+    /**
+     * @description 添加单个曝光元素到监听
+     * @param element 曝光元素
+     */
+
+
+    _this.addExposureElement = function (element) {
+      if (!_this.exposureElementsMap.has(element)) {
+        _this.exposureElementsMap.set(element, {
+          element: element,
+          visibleStartTime: 0,
+          exposureCount: 0,
+          isVisible: false,
+          exposureTimer: null
+        });
+
+        if (_this.exposureObserver) {
+          _this.exposureObserver.observe(element);
+        }
+      }
+    };
+    /**
+     * @description 监听页面上的曝光元素
+     */
+
+
+    _this.observeExposureElements = function () {
+      if (!_this.exposureObserver) {
+        return;
+      }
+
+      var elements = document.querySelectorAll('[data-exposure="true"]');
+      elements.forEach(function (element) {
+        _this.addExposureElement(element);
+      });
+
+      if (_this.initConfig.showLog && elements.length > 0) {
+        _this.printLog("\u5DF2\u76D1\u542C " + elements.length + " \u4E2A\u66DD\u5149\u5143\u7D20");
+      }
+    };
+    /**
+     * @description 上报曝光事件
+     * @param element 曝光元素
+     */
+
+
+    _this.reportExposure = function (element) {
+      var elementInfo = _this.exposureElementsMap.get(element);
+
+      if (!elementInfo) {
+        return;
+      }
+
+      var exposureNum = _this.initConfig.exposureNum;
+
+      if (exposureNum !== undefined && elementInfo.exposureCount >= exposureNum) {
+        if (_this.initConfig.showLog) {
+          _this.printLog("\u5143\u7D20\u5DF2\u8FBE\u5230\u6700\u5927\u66DD\u5149\u6B21\u6570\u9650\u5236: " + exposureNum);
+        }
+
+        return;
+      }
+
+      var business = _this.extractDataAttributes(element);
+
+      var desc = element.getAttribute('data-desc') || _this.eventDescMap['WebExposure'];
+
+      var partkey = element.getAttribute('data-part-key') || 'exposure';
+
+      var params = _this.getParams({
+        event: 'WebExposure',
+        desc: desc,
+        itemKey: _this.getItemKey(partkey),
+        privateParamMap: {
+          business: business
+        }
+      });
+
+      _this.sendData(params).then(function () {
+        elementInfo.exposureCount++;
+
+        if (elementInfo.exposureTimer) {
+          clearTimeout(elementInfo.exposureTimer);
+          elementInfo.exposureTimer = null;
+        }
+
+        if (_this.initConfig.showLog) {
+          _this.printLog("\u66DD\u5149\u4E0A\u62A5\u6210\u529F\uFF0C\u5F53\u524D\u66DD\u5149\u6B21\u6570: " + elementInfo.exposureCount);
+        }
+      }).catch(function (err) {
+        if (_this.initConfig.showLog) {
+          _this.printLog("\u66DD\u5149\u4E0A\u62A5\u5931\u8D25: " + err);
+        }
+      });
+    };
+    /**
+     * @description 初始化 MutationObserver 监听动态添加的元素
+     */
+
+
+    _this.initMutationObserver = function () {
+      if (!('MutationObserver' in window)) {
+        if (_this.initConfig.showLog) {
+          _this.printLog('当前浏览器不支持 MutationObserver，无法监听动态添加的曝光元素');
+        }
+
+        return;
+      }
+
+      _this.mutationObserver = new MutationObserver(function (mutations) {
+        mutations.forEach(function (mutation) {
+          mutation.addedNodes.forEach(function (node) {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+              var element = node;
+
+              if (element.hasAttribute('data-exposure') && element.getAttribute('data-exposure') === 'true') {
+                _this.addExposureElement(element);
+              } else {
+                var exposureElements = element.querySelectorAll('[data-exposure="true"]');
+                exposureElements.forEach(function (exposureElement) {
+                  _this.addExposureElement(exposureElement);
+                });
+              }
+            }
+          });
+        });
+      });
+
+      _this.mutationObserver.observe(document.body, {
+        childList: true,
+        subtree: true
+      });
+
+      if (_this.initConfig.showLog) {
+        _this.printLog('MutationObserver 已启动，监听动态添加的曝光元素');
+      }
+    };
+    /**
+     * @description 停止曝光监听
+     */
+
+
+    _this.stopExposureObserver = function () {
+      if (_this.exposureObserver) {
+        _this.exposureObserver.disconnect();
+
+        _this.exposureObserver = null;
+
+        _this.exposureElementsMap.forEach(function (elementInfo) {
+          if (elementInfo.exposureTimer) {
+            clearTimeout(elementInfo.exposureTimer);
+          }
+        });
+
+        _this.exposureElementsMap.clear();
+      }
+
+      if (_this.mutationObserver) {
+        _this.mutationObserver.disconnect();
+
+        _this.mutationObserver = null;
+      }
+
+      if (_this.initConfig.showLog) {
+        _this.printLog('曝光监听已停止');
+      }
+    };
 
-    _this.sdkVersion = "1.2.3"; // sdk版本
+    _this.sdkVersion = "1.2.4"; // sdk版本
 
     _this.initConfig = {
       appKey: "",
@@ -2802,7 +3118,11 @@ function (_super) {
       pendingRequestsMaxSize: 50,
       autoTrackPageDurationInterval: false,
       pageDurationInterval: 30000,
-      sendMethod: "auto" // 数据发送方式：auto（自动选择）、xhr（XMLHttpRequest）、beacon（sendBeacon）
+      sendMethod: "auto",
+      autoTrackExposure: false,
+      exposureThreshold: 0.5,
+      exposureTime: 500,
+      exposureNum: undefined // 同一元素允许上报的最大曝光次数，不限制
 
     }; // 系统信息