外观
核心概念
广告系统管理“展示什么、满足什么条件、把哪个奖励交给谁”。游戏或业务 APP 管理“金币如何增加、道具如何入库、复活如何执行”。分清这些责任,才能正确处理重复回调、网络中断和多应用接入。
对象关系
text
组织
└── 应用 Application
├── 广告位 Placement:在哪个业务场景展示,奖励是什么
├── 素材 Creative:具体图片或视频
└── 投放 Campaign:把素材关联到广告位,规定排期和选择策略
└── 观看会话 AdSession:某个用户的一次展示机会及规则快照
└── 奖励 Reward:本次机会的资格、稳定 grantId 和交付状态1
2
3
4
5
6
7
2
3
4
5
6
7
组织和应用
组织是后台权限边界。应用代表接入广告系统的一个 APP,拥有自己的广告位、素材、投放、用户命名空间、服务端 key 和交付方式。
公开 App ID,例如 app_demo,用于找到应用。它可以出现在客户端中,但不具备服务端认证权限。内部数据库 ID 和公开 App ID 不是同一个字段,客户端匿名接入使用公开 ID。
同一个 subjectId 出现在两个应用中时,属于两个应用各自的身份范围。APP 不能通过修改请求体中的应用或用户字段来读取另一应用的奖励。
广告位
广告位是稳定的业务入口,而不是某个素材文件。例如:
| 广告位编码 | APP 中的入口 | 奖励映射示例 |
|---|---|---|
revive | 失败后的复活按钮 | revive × 1 |
daily_bonus | 每日福利入口 | coin × 100 |
extra_energy | 体力不足时的补充入口 | energy × 5 |
客户端只依赖广告位编码。后台换素材、改投放优先级时,不需要修改业务入口代码。
初版广告位形式为 rewarded 和 display。display 可以展示广告,但对应会话的 reward 为 null,不能调用奖励领取流程。
素材与投放
素材保存图片或视频本身及其实际尺寸、时长、媒体地址等信息。image、video 是素材类型。
投放把素材关联到广告位,并配置启用状态、排期、优先级、权重和展示上限。优先级较高的有效投放先进入候选集合,同优先级再按权重选择;配置权重不代表保证某次请求一定命中指定素材。
投放可以覆盖广告位的 imageSeconds、videoMode 和 videoSeconds。空值表示继承广告位规则。实际展示时,客户端必须使用 load() 返回会话里的规则,不能只使用先前 getConfig() 读到的广告位默认值。
身份、令牌和密钥
| 标识 | 保存在哪里 | 能做什么 |
|---|---|---|
| 公开 App ID | APP、网页、后台 | 找到应用,不是认证密钥 |
| 安装 ID | 匿名客户端的持久存储 | 帮助同一安装恢复匿名身份;不是可信账号 |
| 客户端 token | 客户端内存;由应用自行决定安全存储策略 | 以限定的应用和用户身份调用 /client/* |
| 服务端 key | 应用业务后端 | 生成客户端 token、消费奖励、接收与核验回调 |
| 管理员会话 Cookie | 管理后台浏览器 | 管理应用、素材和投放,不用于 APP 广告接入 |
当前客户端 token 有效期为 1 小时。参考 AdClient 将 token 保存在内存,可配置 refreshToken 回调;401 时合并刷新并重放原请求一次。它不持久化凭据,也不代替业务登录。Web 参考播放器对匿名身份提供同安装 ID 刷新,业务后端模式由接入方提供同身份的新 token。
服务端 key 不应进入安装包、前端环境变量或 Web 页面。即使代码经过混淆,也不应把它当作客户端秘密。
会话不是奖励
load() 成功创建一个观看会话,冻结本次素材、观看规则、奖励内容和交付方式。它还会占用必要的配额预留。它不表示广告已经展示,也不表示奖励成立。
start() 在真正准备展示时调用。服务端检查投放是否仍可开始,记录开始时间、冷却起点和展示状态。
events() 传递客户端观察到的播放事实。服务端结合经过时间、可见时长、视频进度、事件序列和规则判断资格。自有广告的客户端证据仍可能被伪造,不能证明真人确实看了内容。
claim() 仅适用于 client_claim 模式:领取已经成立的奖励凭证。它不会替应用修改金币或道具数据库。
四个容易混淆的标识
| 字段 | 含义 | 使用原则 |
|---|---|---|
session.id | 一次广告机会 | 播放、上报和状态恢复围绕同一个 ID |
reward.id | 该机会对应的奖励记录 | 查询、claim、consume、acknowledge 使用它 |
reward.grantId | 同一笔业务奖励的稳定交付标识 | 应用资产入账以它防重,重试不能生成新的 grant |
eventId | 一条播放观察事件 | 重传同一事件保留 ID 和内容 |
创建会话另有 Idempotency-Key。它用于把重复的创建请求归并为同一个会话,不等于 grantId。相同创建 key、相同应用与用户、不同请求内容会产生冲突。
资格与交付是两个状态维度
奖励的 eligibility 回答“是否已满足规则”:
| 值 | 含义 |
|---|---|
PENDING | 等待足够证据 |
ELIGIBLE | 当前系统已按本次规则判定资格成立 |
REJECTED | 资格被明确拒绝,例如开始前关闭 |
EXPIRED | 待验证流程超过证据窗口后被清理为过期 |
deliveryStatus 回答“奖励凭证交到了哪里”,包括 NOT_READY、AVAILABLE、CLAIMED、CONSUMED_PENDING_ACK、DELIVERY_PENDING 和 FULFILLED。不同交付模式走不同路径,见奖励交付。
ELIGIBLE 不等于资产已经到账;CLAIMED 不等于可信入账;FULFILLED 表示业务后端已确认处理,仍由该后端负责真实资产事务。
配置快照
管理员可以修改广告位规则、投放覆盖和应用限额。这些配置供新的广告会话使用;已经创建的会话沿用保存的素材、奖励与观看规则快照。
例如用户创建了“观看图片 5 秒获得 100 金币”的会话,运营随后改为 8 秒、50 金币,原会话仍按自己的快照处理。客户端应展示返回的 session.reward,不自行从旧配置拼装奖励。
投放、广告位或素材被暂停后,尚未开始的会话在 start() 时可能被拒绝。规则快照不意味着暂停和安全停用失效。
频控与展示配额
初版区分以下口径:
- 每用户每广告位每日奖励次数:广告位的
dailyLimit。 - 每用户每应用每日奖励总次数:应用的
dailyLimit。 - 广告位冷却:该用户最近一次实际开始该广告位的时间,加上
cooldownSeconds。 - 投放每日展示限额:投放的
dailyLimit,按投放共享,而不是每用户一份。 - 活跃会话:当前实现同一应用、同一用户一次只允许一个活跃会话,普通展示也使用这一约束。
奖励配额在创建时预留、资格成立时消费;资格已经成立但尚未领取,不会自动返还奖励次数。播放关闭会释放活跃槽位,但已开始且仍待证据的奖励预留可能继续保留到证据窗口结束。
日切按应用配置的时区计算。创建会话时已经确定的配额日期不会因为午夜后的迟到处理而重新扣一次新日额度。
首期能力边界
当前真实来源是 house 自有广告。来源接口预留了平台、样式和证据能力;这不意味着 Android/iOS 原生 SDK、小游戏适配器、AdMob 或其他第三方已经接通。
初版每笔奖励是一项配置权益。组合奖励、玩家统一钱包、现金提现、广告联盟结算和正式多平台 SDK 不属于当前已实现的客户端契约。