曝光埋点别放在组件渲染里：连续可见与去重范围怎么验收

列表组件更新一次，曝光数就加一次；用户明明没滚到那张卡片，后台却已经收到曝光。这类问题通常不是报表计算慢，而是把"内容被创建"误当成"内容进入了约定的可见范围"。曝光埋点应先写触发契约，再把浏览器信号接到契约上。

本文由 SensorFlow 项目维护方整理，AI 协助起草；代码仅使用离线合成观测，不代表真实用户、浏览器兼容性实测或产品内置能力。

一次曝光究竟证明了什么

本文把一次合格曝光定义为：同一页面实例里，同一内容与位置组合，在页面可见时，元素几何相交比例持续不低于约定阈值，达到持续时间后最多产生一个候选事件。它不证明用户读懂、记住或点击，也不证明候选事件已送达服务端。

示例使用比例 0.5、连续 1000 毫秒，只是为了让测试边界清晰，不是广告计费标准，也不是所有列表的推荐值。产品、前端、分析和测试应共同决定真实阈值；不要用"业内都是这样"替代定义。

DOM 节点创建、接口成功返回、组件 mounted 和虚拟列表复用，都可以发生在用户尚未看到内容时。相反，同一条内容因为状态更新重新渲染，不应自动成为一次新曝光。

浏览器提供观测，业务负责解释

Intersection Observer 可以异步观测元素与视口或指定根的相交变化；intersectionRatio 描述面积比例。它们提供的是几何信号，不是人类注意力证明。

还要检查 document.visibilityState。切到后台后，不能仅因为上一次元素比例合格，就继续累计一次"前台连续曝光"。普通相交观测也不能独自保证元素未被遮挡；透明、覆盖、复杂容器以及可选的 trackVisibility 支持都需要单独评估。

实现时可以分四步：

在页面或路由进入时建立页面实例范围，确定内容ID和位置ID。
将相交、页面前后台及计时检查转换为同一时钟上的观测。
只在持续区间未中断且达到阈值时创建候选曝光。
创建后固定事件ID交给上报层；传输重试不重新触发业务曝光。

相交回调不会保证恰好在1000毫秒再次执行。真实适配器还需要到期检查，并在到期时重新确认页面和元素条件。下面的程序只验证已经提供的观测序列，不会替你注册监听、定时器或发请求。

用边界样本验收，而不是盯着总数猜

保存为 impression.cjs，执行 node impression.cjs。代码只依赖 Node 标准库；所有字符串ID均为合成标识，没有请求、Cookie、DOM或用户数据。

javascript 复制代码

const assert = require('node:assert/strict');
function detector() {
  const since = new Map(), fired = new Set();
  let last = -Infinity;
  return function observe(at, item, slot, ratio, visible) {
    assert(Number.isFinite(at) && at >= 0 && at >= last);
    assert(typeof item === 'string' && item.length > 0);
    assert(typeof slot === 'string' && slot.length > 0);
    assert(Number.isFinite(ratio) && ratio >= 0 && ratio <= 1);
    assert.equal(typeof visible, 'boolean');
    last = at;
    const key = JSON.stringify([item, slot]);
    if (!visible) since.clear();
    if (!visible || ratio < 0.5) {
      since.delete(key);
      return false;
    }
    if (fired.has(key)) return false;
    if (!since.has(key)) since.set(key, at);
    if (at - since.get(key) < 1000) return false;
    fired.add(key);
    return true;
  };
}
const first = detector();
assert.equal(first(0, 'card-a', 'feed', 0.5, true), false);
assert.equal(first(999, 'card-a', 'feed', 0.5, true), false);
assert.equal(first(1000, 'card-a', 'feed', 0.5, true), true);
assert.equal(first(2000, 'card-a', 'feed', 1, true), false);
const interrupted = detector();
interrupted(0, 'card-a', 'feed', 1, true);
interrupted(700, 'card-a', 'feed', 0.49, true);
interrupted(800, 'card-a', 'feed', 1, true);
assert.equal(interrupted(1000, 'card-a', 'feed', 1, true), false);
assert.equal(interrupted(1800, 'card-a', 'feed', 1, true), true);
const background = detector();
background(0, 'card-a', 'feed', 1, true);
background(800, 'card-a', 'feed', 1, false);
assert.equal(background(1200, 'card-a', 'feed', 1, true), false);
assert.equal(background(2200, 'card-a', 'feed', 1, true), true);
assert.throws(() => background(2100, 'card-a', 'feed', 1, true));
assert.throws(() => detector()(0, 'card-a', 'feed', 1.1, true));
const anotherPage = detector();
anotherPage(0, 'card-a', 'feed', 1, true);
assert.equal(anotherPage(1000, 'card-a', 'feed', 1, true), true);
console.log('PASS: 11 synthetic impression checks');

999毫秒不触发、1000毫秒触发，能防止"看起来差不多"的边界漂移。700毫秒时比例跌破阈值后，重新进入要从800毫秒重新计时；切后台也会清空尚未合格的持续区间。同一页面实例内已经触发的卡片再次观察不重复，新页面实例则重新建立自己的去重范围。

这里用 Set 保存已经触发的逻辑键，用 Node strict assert 让失败明确中断。它是内存教学模型，不具备进程恢复、跨标签页共享或分布式去重。

去重键不要跟着节点身份走

虚拟列表可能把同一个节点先用于内容A，再用于内容B。如果用DOM节点本身作为唯一键，后者可能被错误压掉；如果每次渲染都生成随机新键，前者又可能被重复计数。键应来自明确的业务范围，而不是渲染框架的实现细节。

本文选择"页面实例＋内容＋位置"。实际业务也可能选择"会话＋内容"或"内容展示机会ID"；这些口径不能混着比较。同一内容在主列表和推荐栏出现，是否应该算两个机会，需要先回答报表要解释哪个位置，而不是在查询时临时拼补。

多卡片适配器在收到页面隐藏信号时，应及时向模型提供这一状态，使全部未完成区间失效。卡片卸载、换内容或退出观察时也要取消相应的等待检查。模型假设影响条件的状态变化已按顺序提供；中途信号丢失时，不能仅用首尾两点证明真实连续可见。示例没有处理资源释放、观察数据丢失、乱序补报或完整设备生命周期，不能直接贴进生产当成完整SDK。

上线前保留三层验收证据

前端测试先证明候选事件何时产生：卡片未进入视口、短暂划过、反复进出、切后台、虚拟列表换内容和路由返回都要覆盖。真实设备测试再检查时序、遮挡、定时节流及低版本行为，Node断言不能替代这一步。

接收测试证明一个固定事件ID在重试后怎样落地；报表测试最后证明"候选次数、唯一曝光、曝光人数"分别取什么范围。一个事件在控制台出现，只覆盖了这条链路的一小部分。

运营对点击率有疑问时，先把点击与曝光的内容、位置、页面范围和统计窗口对齐。不要拿全站点击人数除某个组件的曝光次数，也不要因为用户先点击就倒推出缺失的曝光事实。下一步最有效的行动，是把上面的合成边界换成自己组件的真实场景测试，而不是先改报表颜色。