外观
播放、计时与事件
广告系统根据服务端会话规则和客户端播放证据判定奖励资格。客户端负责真实展示、测量和上报;服务端负责校验会话、限制可累计时间并执行一次性的资格变更。初版属于自有广告的客户端证据方案,不能据此宣称具备第三方平台服务端验证或不可伪造的观看证明。
一次播放的正常顺序
text
读取配置 → load → CREATED
↓ 素材就绪、展示 UI 已打开
start → SHOWING
↓ 实际前台观看,每秒提交 heartbeat
complete → 服务端检查累计证据
↓
达标:ENDED / ELIGIBLE;不足:可能仍 SHOWING / PENDING
↓ 关闭展示,读取奖励结果1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
load()预留会话和相应额度,不代表已经展示。- 图片等待加载成功;视频至少等待
loadeddata,再调用start()。 - 检查
start()返回状态确实为SHOWING,随后启用计时和心跳。重复start()可能返回已有的ENDED会话,不能把成功 HTTP 响应直接当作允许重播。 - 只有真实展示的有效时间才能累计。定时器负责发送采样结果,不能用定时器运行次数代替观看时间。
- 达到规则后提交
complete。它表示客户端报告播放完成,不直接授予奖励。 - 使用返回会话的
reward.eligibility显示资格,再进入对应交付流程。
预加载预览图、隐藏的视频、媒体下载时间、暂停时间和网络请求等待时间都不应计入观看。
从会话快照读取要求
加载后使用 session.rules 和 session.creative,不要继续用旧配置覆盖本次规则:
ts
import type { AdSession } from './lib/ad-client';
export function requiredSeconds(session: AdSession): number {
if (session.creative.kind === 'image') return session.rules.imageSeconds;
if (session.rules.videoMode === 'minimum') return session.rules.videoSeconds;
const duration = session.creative.durationSeconds;
if (typeof duration !== 'number' || duration <= 0) {
throw new Error('视频会话缺少有效时长,不能开始奖励计时');
}
return duration;
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
| 素材 / 规则 | 客户端结束条件 | 服务端资格条件 |
|---|---|---|
| 图片 | 实际前台可见时间达到 imageSeconds | 累计有效证据达到图片要求 |
视频 minimum | 正常播放累计时间达到 videoSeconds | 累计有效视频证据达到最短时长 |
视频 complete | 媒体真实触发 ended,同时有完整播放进度 | 累计有效时间达到素材时长,收到 complete,且单调进度接近结尾 |
完整视频不能只检查 currentTime >= duration;拖动到末尾没有足够有效时长,仍不能获奖。最短时长视频也需要真实播放进度,单纯停在某帧等待无效。
当前服务端允许图片 0.05 秒、视频 0.3 秒的判定容差,用于正常采样误差。这是实现细节,客户端不应刻意少播相应时间。
图片计时
参考播放器使用 requestAnimationFrame 和 performance.now() 的差值,在以下条件同时成立时累计:
- 广告弹层仍然打开。
document.hidden === false。- 会话处于
SHOWING。 - 尚未发送完成、尚未请求关闭。
每帧的时间差最多计入 0.25 秒,避免浏览器长时间停顿后把整段停顿补算为观看。实际游戏还应把场景切换、应用失焦或原生进入后台接入同一暂停机制。
document.hidden 无法证明用户真的注视屏幕,也无法识别所有原生遮挡。它是 Web 参考实现的可见性输入,不是高价值资产的反作弊保证。
视频计时
参考播放器同时读取单调时钟差值和 video.currentTime 差值;仅在以下情况累计:
- 广告在前台可见,媒体没有暂停,也没有处于
seeking。 - 播放速率为
1。 - 播放进度向前正常增长,没有异常跳跃。
- 累计值不超过本帧允许的实际时间和视频进度。
初版播放器没有拖动进度条,并在 ratechange 时恢复正常速率。业务播放器也应关闭倍速、跳播等与激励规则冲突的控件。不能通过先跳到结尾、再等待墙钟时间的方式补出一次完整观看。
服务端保留收到的最高视频进度。回退重播不能把同一段进度反复换成有效观看时间。如果进度上报错误或发生跳播,后续回退重播不保证修复当前会话;应展示实际判定结果,不应修改累计值伪造修复。
前后台、暂停与播放被拦截
| 事件 | 客户端处理 |
|---|---|
| 页面隐藏 / APP 进入后台 | 立即暂停视频,停止累计,重置本地采样基线,可发送 visible: false 心跳 |
| 回到前台 | 重置采样基线;视频由用户恢复,不能把后台间隔补进计时 |
| 用户暂停 | 不累计视频时间;允许继续查询和发送真实状态 |
浏览器拒绝 play() | 显示可点击的继续按钮,等待实际播放;不要虚增进度 |
| 素材加载失败 | 显示错误并允许关闭;未开始会话也应提交 close 释放预留 |
| 网络失败 | 保留原事件内容与顺序,展示待验证状态;重试失败时不承诺奖励 |
事件字段
AdEvent 的字段含义如下:
| 字段 | 含义 | 重试要求 |
|---|---|---|
eventId | 本会话中一个逻辑事件的唯一 ID,1–128 字符 | 相同事件必须复用 |
sequence | 从 1 开始递增的正整数 | 不重新编号,不倒序发送 |
type | heartbeat / complete / close / click | 重试不更改 |
visible | 采样时广告是否在前台可见 | 重试保留原采样值 |
visibleSeconds | 从本会话开始累计的有效可见秒数,非本次增量 | 单调不减,允许小数;最大 36,000 |
positionSeconds | 视频的实际播放位置;图片省略 | 保留事件创建时的位置 |
elapsedSeconds | 从收到 start 成功响应后开始,用单调时钟计量的已过秒数,包含暂停和后台时间 | 持久保存原采样值,不能在补传时更新 |
例如连续采样到累计 1.02、2.01、3.03 秒,应分别上报这三个累计数值。不能上报三次 1,也不能把累计值再次相加后上报 1.02、3.03、6.06。
click 用于记录用户实际点击广告落地页,不增加观看时间。只应在真实点击发生时发送;跳转前先检查 URL 协议,参考播放器仅开放 HTTPS 落地页并使用 noopener noreferrer。
服务端怎样累计证据
当前实现验证归属、截止时间和格式,保存不可变事件,再按 sequence 顺序重放。eventId 和 sequence 都在会话内唯一;相同 ID、序号及全部字段完全相同才是幂等重试。修改任一内容或用不同 ID 占用同一序号,返回 EVENT_CONFLICT。
资格只由从序号 1 开始的连续前缀决定。乱序事件可以先保存;如果缺少较早序号,就等待缺口补齐,不能跳过可能存在的关闭事件发奖。响应中的 lastSequence 是连续处理终点,不一定是已保存的最大序号。每会话最多保存 2048 条事件。
elapsedSeconds 使用 performance.now(),从收到 start() 成功响应后开始,包括暂停与后台间隔。它必须非负、有限、最多 36000 秒,并且不超过首次接收时服务端已过时间加 0.25 秒容差;实际计入时间仍受服务端已过时间限制。已知事件按序号的显式 elapsed 必须单调,超过 1 毫秒的倒退返回 INVALID_EVENT_TIMELINE,不能用本地日期时钟伪造补传。
服务端根据事件时间的增量形成预算,并同时限制累计可见秒数增量;视频还受单调播放进度约束。同一段时间不会因为批量发送或重放多次而重复累计。关闭事件之后的新证据不能继续观看计时。
这意味着:
- 大量瞬间发送的心跳不会凭空产生对应观看秒数。
- 展示截止前采样并持久保存的显式 elapsed 事件,可以在证据截止前补传;仍需通过连续序号、时间和视频进度校验。
- 旧客户端没有 elapsed 时采用首次接收时间的保守边界;首次到达已经超出展示窗口的旧格式证据,不能靠后来附加 elapsed 倒推获奖。
- 提前上报很大的累计值会消耗后续增量的基线,不能靠再发送正常值来“补差”。
complete记录完成声明;时间和完成条件满足才结束为ENDED / COMPLETED。证据不足时可能仍是SHOWING。如果close因网络乱序先到达,会立即结束展示,但后来补齐的较低序号、真实关闭前的合法证据仍会重算;不能把所有ENDED都当作禁止补证。- HTTP 成功只代表请求已处理,不能代替检查返回的资格状态。
保序队列:可复制实现
下面的队列只负责事件可靠顺序,不会生成观看时间,也不会自动重试。保存为 src/ad-events.ts,配合完整 Web 配方中真实媒体采样使用。
这是独立教学示例的内存队列。仓库 Player Lab 已有持久化 journal 和刷新恢复,见本页末尾;复制此示例不会自动获得那些能力。
设计原则:一个会话只有一个发送者;同一时刻只有一个请求;确认成功后才移除队头;网络失败保留原来的 ID、序号、时间和位置。接口单次允许 1–20 个事件,示例每批取 10 个。
ts
// src/ad-events.ts
import {
AdClient,
type AdEvent,
type AdSession,
} from './lib/ad-client';
export type PlaybackSample = {
visible: boolean;
visibleSeconds: number;
positionSeconds?: number;
elapsedSeconds?: number;
};
export class OrderedEventQueue {
private sequence = 0;
private pending: AdEvent[] = [];
private sending?: Promise<AdSession | undefined>;
private last?: AdSession;
constructor(
private readonly client: AdClient,
readonly sessionId: string,
private readonly onSession: (session: AdSession) => void,
) {}
get size(): number {
return this.pending.length;
}
enqueue(type: AdEvent['type'], sample: PlaybackSample): void {
// 有界内存。上层应在溢出时停止播放并提示恢复,不能丢队头后继续承诺奖励。
if (this.pending.length >= 300) {
throw new Error('离线事件已达上限,请停止播放并先重试上传');
}
if (!Number.isFinite(sample.visibleSeconds) || sample.visibleSeconds < 0) {
throw new Error('visibleSeconds 必须来自有效的真实播放采样');
}
this.pending.push({
eventId: crypto.randomUUID(),
sequence: ++this.sequence,
type,
visible: sample.visible,
visibleSeconds: Math.round(sample.visibleSeconds * 1000) / 1000,
...(sample.positionSeconds === undefined
? {}
: { positionSeconds: Math.round(sample.positionSeconds * 1000) / 1000 }),
...(sample.elapsedSeconds === undefined
? {}
: { elapsedSeconds: Math.round(sample.elapsedSeconds * 1000) / 1000 }),
});
}
flush(): Promise<AdSession | undefined> {
if (this.sending) return this.sending;
this.sending = this.sendInOrder().finally(() => {
this.sending = undefined;
});
return this.sending;
}
private async sendInOrder(): Promise<AdSession | undefined> {
while (this.pending.length > 0) {
const batch = this.pending.slice(0, 10);
// 抛错时不移除 batch。下一次 flush 会重发完全相同的事件。
const updated = await this.client.events(this.sessionId, batch);
this.pending.splice(0, batch.length);
this.last = updated;
this.onSession(updated);
}
return this.last;
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
注意此类从序号 1 开始,只适用于一个新会话的唯一上报器。不能在同一已上报会话上销毁后重建队列,也不能让多个浏览器标签页各自从 1 开始发送。同样,不应使用 Promise.all() 并发发送同一会话的不同批次。
超时存在“服务端已处理、客户端没收到响应”的可能。保留队列后重试即可;不要创建新的事件 ID,因为这会把一次逻辑事件变成另一个事件。
仓库播放器会持久化会话、序号、创建操作和原事件,刷新后可补传已有证据;它不会自动续播或把刷新后的时间计入原观看。本节教学类仍是内存实现,需要额外接入持久化才能跨刷新补传,不能把仅保存 sessionId 描述为支持断点续播。
完成和关闭
正常完成
先记录最后一个真实 heartbeat,再记录 complete,按顺序上传。完整视频的 complete 应来自真实 ended;图片和 minimum 模式应来自实测累计达到要求。
返回奖励 ELIGIBLE 时可显示“奖励已就绪,关闭后领取”。服务端交付模式则应显示“奖励资格已通过,等待业务后端确认”。资格仍为 PENDING 时应允许重查、重试保留的事件或关闭,不要把界面永久停在无操作的加载状态。
提前关闭
CREATED:只发送close,可释放尚未播放的预留。SHOWING:先采样最后一帧,发送最后的heartbeat,再发送close;停止媒体和本地累计。ENDED:关闭 UI,查询已有奖励状态即可。已成立的资格不会因为关闭 UI 自动撤销。
关闭事件本身不增加观看时间。高于 close 序号的后续心跳不能让广告继续累计。较早产生、原样保存的低序号完成事件允许在证据窗口内补齐;不能在关闭后新造一个“之前发生”的事件填空。
页面被直接关闭
浏览器关闭或进程终止时不能保证最后一个请求成功。仓库播放器先把事件和序号同步存入本地 journal,再发送;重新认证同一身份后会补传未确认事件。pagehide 尽量保存最后的真实可见采样,但进程被强制终止前尚未保存的帧无法保证恢复。没有 Service Worker 后台投递或离线奖励承诺,不能因为本地显示过完成动画就补发资产。
当前时间边界
| 限制 | 当前实现 | 含义 |
|---|---|---|
| 开始播放窗口 | 创建后 5 分钟 | 超过后不能首次开始 |
| 展示窗口 | 开始后 10 分钟 | 超过后不再累计有效观看 |
| 证据接收窗口 | 开始后 20 分钟 | 超过后事件请求返回 SESSION_EXPIRED |
| 奖励首次领取窗口 | 资格成立后 24 小时 | 未领取资格会过期;已领取可返回同一凭证 |
这些是当前服务端常量,并不是后台创建广告时的可配置表单项。20 分钟证据窗口也不意味着关闭或超时后可以继续累计;它只为已发生的证据处理留出边界。
与仓库参考播放器的关系
仓库播放器已实现实际媒体测量、隐藏暂停、单飞批量队列、页面存活期间的心跳重试、手动重查和同一身份恢复奖励。AdClient 本身没有这些调度行为。
仓库播放器把创建 key、原请求参数、会话、累计采样、序号和待确认事件保存到按应用/用户隔离的 localStorage journal,不保存 token。Web Locks 保证同一身份仅一个标签页写队列,因此需要支持 Web Locks 的现代浏览器。切换身份不会把旧事件送给新账号。
普通事件积压到 300 条时暂停继续观看,并额外保留 4 个位置给最终心跳、完成和关闭;不会截掉队尾。上传确认后才移除队头。写入本地存储失败时停止产生新证据,不把失败当作已保存。断网重试有退避,匿名 token 可自动续期,手动业务 token 可以同身份替换。
遇到 SESSION_EXPIRED 时,播放器再次读取同一会话,确认服务端已结束后才把原队列完整归档,释放当前操作以便加载下一条广告;不会在普通网络失败或 401 时清空队列。页面上的“Close saved session”可结束刷新后未完成的旧会话;新 close 没有可恢复的单调起点时省略 elapsed,不编造旧观看时间。
本页独立内存示例在队列满时直接拒绝追加,仍需调用方停止播放。它与仓库完整实现都不能承诺离线必定获奖。