轻量埋点方案

特性

• 🚀 零依赖 - 纯原生 JavaScript 实现，无需任何第三方库
• 📦 体积小 - 核心代码精简，适合移动端场景
• 🎯 自动埋点 - 基于 IntersectionObserver 实现自动曝光监听
• 🖱️ 点击埋点 - 自动绑定点击事件，支持动态 DOM
• ✋ 手动埋点 - 提供便捷的手动埋点 API
• 📝 TypeScript - 完整的类型定义支持

安装

npm install md-tracker

快速开始

1. 自动埋点

import createTracker from 'md-tracker';

// 定义埋点配置
const trackingConfig = [
  {
    ele: '.banner',           // CSS 选择器
    data: {
      dpm: '123.110.1.1',     // 页面元素位置标识
      dcm: '202.456.0.0',     // 渠道维度标识
      appId: 'your-app-id',
      dom: 'channel.0.0.0'
    },
    once: false               // 是否只曝光一次
  },
  {
    ele: '.button-group',
    data: {
      dpm: '123.110.2.1',
      dcm: '202.456.0.0',
      appId: 'your-app-id'
    }
  }
];

// 初始化埋点
const destroy = createTracker({
  show: trackingConfig,   // 曝光埋点
  click: trackingConfig   // 点击埋点
});

// 销毁埋点监听（可选）
// destroy();

2. 手动埋点

import { logExposure, logClick, initManualMD } from 'md-tracker';

// 初始化配置（可选）
initManualMD({
  appId: 'your-app-id',
  logInterval: 50  // 日志发送间隔
});

// 手动曝光埋点
logExposure({
  dpm: '123.110.5.1',
  dcm: '202.456.0.0',
  appId: 'your-app-id'
});

// 手动点击埋点
logClick({
  dpm: '123.110.6.1',
  dcm: '202.456.0.0',
  appId: 'your-app-id'
});

3. 配置埋点服务端点

import { setConfig } from 'md-tracker';

setConfig({
  exposureUrl: '/exposure/standard',  // 曝光埋点接口
  clickUrl: '/log/click',             // 点击埋点接口
  useJsonp: true                      // 曝光是否使用 JSONP
});

API 文档

createTracker(config)

创建埋点追踪器。

返回值: 销毁函数，调用后停止所有监听

logExposure(data)

手动发送曝光埋点。

logClick(data)

手动发送点击埋点，参数同 logExposure。

setConfig(options)

设置全局配置。

resetExposure(ele)

重置元素曝光状态，允许再次曝光。

createLogger(baseData)

创建便捷的埋点函数工厂。

import { createLogger } from 'md-tracker';

const logger = createLogger({
  dpm: '123.110',
  dcm: '202.456',
  appId: 'your-app-id'
});

// 使用简化的 API
logger.exposure(1, 1, 0);  // 发送曝光埋点
logger.click(2, 1, 0);     // 发送点击埋点

埋点配置说明

TrackingConfig

interface TrackingConfig {
  ele: string | string[];    // 元素选择器
  data: TrackingData;        // 埋点数据
  once?: boolean;            // 是否只曝光一次，默认 true
  logClick?: boolean;        // 是否记录点击，默认 true
  logExposure?: boolean;     // 是否记录曝光，默认 true
}

TrackingData

interface TrackingData {
  dpm?: string;   // 格式：{appId}.{页面ID}.{元素ID}.{操作类型}
  dcm: string;    // 格式：202.{projectId}.{状态}.{扩展}
  domain?: string;
  appId?: string;
  dom?: string;
  [key: string]: any;
}

HTML 使用示例

<!-- 添加埋点类名 -->
<div class="banner md1">Banner 广告位</div>
<button class="btn md2">点击按钮</button>

<script type="module">
  import createTracker from 'md-tracker';

  // 批量生成配置
  const appId = '123';
  const projectId = '456';
  
  const configs = Array.from({ length: 10 }).map((_, i) => ({
    ele: `.md${i + 1}`,
    data: {
      dpm: `${appId}.110.${i + 1}.1`,
      dcm: `202.${projectId}.0.0`,
      appId
    },
    once: false
  }));

  createTracker({ show: configs, click: configs });
</script>

核心机制

曝光埋点

使用 IntersectionObserver API 监听元素是否进入视口，自动触发曝光埋点请求。

点击埋点

使用 addEventListener 绑定点击事件，配合 MutationObserver 监听 DOM 变化，支持动态添加的元素。

请求方式

• 曝光埋点: 默认使用 JSONP 跨域请求
• 点击埋点: 使用 XMLHttpRequest 发送

文件结构

MD/
├── src/
│   ├── index.js       # 包入口
│   ├── utils.js       # 工具函数
│   ├── request.js     # 网络请求
│   ├── md-core.js     # 自动埋点核心
│   ├── md-index.js    # 埋点入口
│   └── manual-md.js   # 手动埋点
├── types/
│   └── index.d.ts     # TypeScript 类型定义
├── package.json
└── README.md