一、核心設計目標

1. ??精細化監控??：定位到頁面中??單個模塊??的曝光、點擊等行為。
2. ??低侵入性??：業務代碼與埋點邏輯解耦，降低開發維護成本。
3. ??鏈路可追蹤??：串聯用戶從曝光到操作的完整行為路徑。
4. ??實時性??：快速發現并定位頁面模塊級問題（如曝光率異常、點擊失效）。

---

二、模塊標識與注冊機制

1. ??模塊唯一標識生成??

• ??維度選擇??：使用搭建系統生成的物料模塊UUID作為標識，確保跨頁面唯一性。
• ??擴展標識??：對同一模塊在不同位置的多次出現，追加位置索引（如 module_uuid:position_index）。
• ??數據結構示例??：

  {moduleId: "banner_001",       // 模塊業務ID（可選）uuid: "7a3e8b1f-2c9d",       // 全局唯一標識page: "/home",               // 所屬頁面路徑type: "ad_banner"            // 模塊類型
  }

2. ??注冊時機與方式??

• ??注冊表管理??：在頁面渲染時，由搭建系統自動將模塊信息寫入中央注冊表（內存或Redis）。
• ??前端掛載屬性??：將模塊UUID注入DOM節點的data-module-uuid屬性，供采集SDK識別：

  <div data-module-uuid="7a3e8b1f-2c9d" data-track-type="exposure">...</div>

---

三、行為采集機制

1. ??曝光檢測??

• ??技術方案??：使用IntersectionObserver API監聽模塊是否進入視口。
• ??關鍵配置??：
  • 閾值（threshold: 0.5）：50%面積可見時觸發曝光。
  • 防抖機制：避免滾動頻繁觸發（默認300ms）。
• ??曝光后動作??：記錄日志后立即取消監聽，避免重復上報。
• ??代碼示例??：

  const observer = new IntersectionObserver(entries => {entries.forEach(entry => {if (entry.isIntersecting) {logExposure(entry.target.dataset.uuid);observer.unobserve(entry.target); // 僅上報一次}});
  }, { threshold: 0.5 });

2. ??點擊/操作采集??

• ??事件委托??：在根節點監聽全局點擊事件，通過event.target回溯帶標識的模塊。
• ??優勢??：
  • 無需為每個模塊綁定事件。
  • 動態新增模塊自動生效。
• ??攔截邏輯??：

  document.body.addEventListener('click', event => {const moduleElem = event.target.closest('[data-module-uuid]');if (moduleElem) {logClick(moduleElem.dataset.uuid, event);}
  });

3. ??其他行為擴展??

• ??懸浮事件??：監聽mouseover，用于分析用戶注意力分布。
• ??異步加載追蹤??：對動態渲染模塊，通過MutationObserver自動注冊監聽。

---

四、行為鏈路跟蹤方案

1. ??SPM（來源位置模型）編碼??

借鑒阿里系方案，用分層編碼定位行為來源：

• ??編碼結構??：a.b.c.d
  • a：應用/站點（如main_app）
  • b：頁面ID（如home_page）
  • c：頁面內區域（如header）
  • d：模塊位置（如banner_slot_1）
• ??傳遞方式??：
  • 用戶點擊時，將當前模塊SPM編碼作為參數附加到跳轉URL。
  • 下級頁面通過URL參數解析上級來源，形成鏈路。

2. ??會話標識（SessionID）??

• 生成全局唯一的會話ID，串聯單次訪問中的所有行為日志。

---

五、后端處理架構

graph LR
A[前端SDK] -->|HTTP/Syslog| B[日志網關]
B -->|Kafka| C[流處理引擎]
C -->|實時分析| D[監控告警]
C -->|存儲| E[Elasticsearch]
E --> F[可視化看板]

1. ??日志網關??：

   • 協議支持：HTTP/Syslog/UDP，適配不同場景。
   • 數據脫敏：過濾敏感字段（如用戶ID加密）。

2. ??流處理層（Flink/Spark）??：

   • 實時統計模塊曝光率、點擊率。
   • 異常檢測：基于歷史基線觸發告警（如點擊率驟降30%）。

3. ??存儲方案??：

   • ??Elasticsearch??：支持行為日志的全文檢索與聚合分析。
   • ??ClickHouse??：適用于海量日志的OLAP分析（如用戶路徑分析）。

---

六、核心數據結構設計

??日志字段??需包含環境、行為、位置三部分信息：

{"common": {                      // 環境信息"appVer": "2.1.3","os": "iOS 16.5","userId": "u_9a8b7c"},"behavior": {                    // 行為數據"type": "exposure",            // 事件類型"moduleUUID": "7a3e8b1f-2c9d","timestamp": 1720000000000},"position": {                    // 位置信息"page": "/home","spm": "main_app.home.banner","scrollDepth": 75              // 頁面滾動深度}
}

---

七、關鍵問題解決方案

1. ??性能影響??：

   • ??懶加載監聽??：僅對可視區域附近的模塊啟用IntersectionObserver。
   • ??采樣上報??：高并發時按比例采樣（如10%）。

2. ??數據一致性??：

   • ??端到端追蹤ID??：從前端生成traceId直通存儲，便于問題定位。

3. ??隱私合規??：

   • ??GDPR兼容??：提供用戶級日志刪除接口。
   • ??本地緩存開關??：按用戶授權狀態啟停采集。

---

八、部署與監控建議

1. ??資源隔離??：日志采集API獨立部署，避免影響業務服務。
2. ??熔斷機制??：當日志隊列積壓超過閾值時，自動降級采樣率。
3. ??監控看板??：
   • 實時模塊曝光/點擊率
   • 日志延遲熱力圖
   • 錯誤類型分布（如曝光未觸發）