广告焚诀——直接复制给嗒啦啦写成.md文档，需要插入广告时照做

广告奖励防刷全流程方案（预发放 + 三层保护）

核心思路

采用**“预发放 → 确认/回滚”**模式，而非传统的"看完广告再发奖励"。奖励在用户点击广告按钮时就先发放到账，然后根据广告是否真正看完来决定保留还是回滚。

为什么不用"看完再发"？

传统模式（看完再发）| 预发放模式

广告成功 → 发奖励 |点击广告 → 先发奖励 → 看完确认 / 没看完回滚

小游戏切出后断线/闪退会导致广告回调丢失|断线也不会丢奖励，服务端重连时自动判定

服务端被动等客户端上报回调|服务端权威控制，客户端只负责展示广告

完整流程（4步）

客户端点击广告按钮

    │

    ▼

① 服务端预发放 ─── 检查每日次数 → 预扣次数 → 发放物品到背包

    │                → 生成唯一 adKey → 记录到 adPending（含时间戳）

    │                → 返回 adKey 给客户端

    ▼

② 客户端播放广告 ── 记录 adGrantTime = 当前时间

    │

    ├── 广告成功 ──→ ③a 客户端发送确认请求（带 adKey）

    │                → 服务端清除 adPending 记录，奖励保留

    │

    └── 广告失败 ──→ ③b 客户端判断耗时，决定回滚还是交给重连

                     → 服务端执行回滚：移除物品 + 恢复次数

三层保护机制（广告失败时）

客户端在广告失败回调中，用 当前时间 - adGrantTime 计算耗时：

耗时 判定 处理

< 12秒 快速关闭，肯定没看完 客户端立即发送回滚请求

12 ~ 70秒 灰色地带，可能看完了但回调丢失 不处理，交给重连时服务端判定

> 70秒 异常超时 客户端立即发送回滚请求

第三层兜底：服务端重连检测

玩家每次登录/重连时，服务端遍历该玩家所有 adPending 记录：

12~70秒内的 → 自动确认（视为看完）

其余一律回滚

function ResolveAdPending(playerData)

    遍历 playerData.adPending:

        elapsed = 当前时间 - pending.timestamp

        if 12 <= elapsed <= 70 then

            自动确认（清除 pending）

        else

            回滚（移除物品 + 恢复次数）

        end

end

服务端回滚操作（通用）

回滚需要做的事情（根据广告类型选择性执行）：

1. 恢复每日次数：countField -= 1

2. 移除预发放物品：从背包中移除对应物品

3. 特殊回滚（如有）：签到取消打卡、礼包取消领取标记等

防刷要点

1. adKey 唯一性

adKey = "类型前缀_" + 时间戳 + "_" + 全局自增序号

每次预发放生成唯一 key，防止重复确认。

2. 幂等性

确认和回滚接口都是幂等的：如果 adKey 已不在 adPending 中（已确认或已回滚），直接返回成功，不重复操作。

3. adPending 持久化

adPending 必须随玩家数据一起保存到云端/数据库。这样即使服务器重启，重连时仍能检测到未处理的广告记录。

4. 每日次数服务端权威

每个广告类型两个字段：dayField（记录日期）+ countField（记录次数）

每次请求先检查：如果 dayField != 今天，重置 countField = 0

接入清单

新项目接入时需要实现以下模块：

模块 职责

预发放接口 检查次数 → 预扣次数 → 发放物品 → 记录 adPending → 返回 adKey

确认接口 收到 adKey → 清除 adPending（幂等）

回滚接口 收到 adKey → 执行回滚 → 清除 adPending（幂等）

回滚函数 恢复次数 + 移除物品 + 特殊回滚逻辑

重连检测 登录时遍历 adPending，按时间窗口自动确认或回滚

客户端三层判定 广告失败时按耗时决定立即回滚还是交给重连

adPending 持久化 随玩家存档一起保存/加载

时间窗口说明

12 秒和 70 秒是基于主流激励视频广告时长（15~60秒）设定的。