外观
业务后端接入
有自己的登录、存档或资产后端时,推荐由业务后端确定用户身份,并负责实际发放权益。广告系统保存观看证据和奖励资格,你的业务数据库保存用户资产与幂等发奖账本。
选择交付方式
| 条件 | 建议模式 | 需要实现 |
|---|---|---|
| 暂时没有公网通知接收地址,希望主动控制恢复 | server_pull | 获取 Token、consume、数据库幂等发奖、ack、定时恢复 |
| 有稳定公网 HTTPS 接收服务,希望自动异步到账 | server_webhook | 获取 Token、原始 body 验签、数据库幂等发奖、回调确认、失败监控 |
| 完全没有业务后端,本地游戏低价值奖励 | client_claim | 使用客户端流程;不在本文中构建服务端资产可信性 |
两种服务端模式都必须让客户端使用业务后端签发的 Token,不能使用匿名 Token。它们解决交付与用户归属,不会把自有广告的客户端播放证据变成设备级真实性证明。
接入前准备
- 管理后台创建应用,保存公开 appId;选择 server_pull 或 server_webhook。
- 将 serverKey 安全配置到自己的业务后端。APP 只需要公开 appId、客户端 Token、广告位代码和 API 地址。
- 创建激励广告位,确认 rewardCode、rewardType、rewardAmount;上传真实素材并发布投放。
- 在业务后端维护“广告奖励代码 → 自己的资产/权益处理器”的白名单,例如
coin → 金币余额、revive_once → 当前局复活资格。 - 建立持久化 grantId 唯一账本,并让账本插入和真实权益变化使用同一数据库事务。
- Webhook 模式配置公网 HTTPS 地址,按 验签指南 实现接收端;主动拉取模式配置恢复任务。
默认观看时长、冷却和每日次数都是后台创建时的初始值,可以修改。接入代码以每次 Session 返回的 rules 和 reward 为准,不写死“看 5 秒发 100 金币”。
身份签发
APP 先登录自己的业务系统,再向自己的后端请求广告 Token。后端从已认证会话取得用户 ID,调用广告 API:
ts
// 业务后端代码示意;authenticateUser 由自己的登录系统实现。
async function issueAdToken(request: Request) {
const user = await authenticateUser(request);
const response = await fetch(`${AD_API_BASE}/server/client-tokens`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-App-Key': AD_APP_KEY,
},
body: JSON.stringify({ subjectId: String(user.id) }),
signal: AbortSignal.timeout(10_000),
redirect: 'error',
});
if (!response.ok) throw new Error(`Ad token request failed: ${response.status}`);
return response.json(); // 只返回客户端 token、subjectId、expiresAt。
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
AD_API_BASE 包含 /v1,AD_APP_KEY 只存在后端。业务后端不应接受前端提交的任意 subjectId 后直接签发,否则用户可能取得他人的广告身份。
用户 ID 是不透明且大小写敏感的字符串。选择稳定、不暴露邮箱/手机号的内部 ID;不要每次登录随机更换,也不要在不同调用路径使用不同大小写或前缀。
server_pull 完整流程
text
APP 自己的业务后端 广告系统 业务数据库
│ 已登录,申请 Token │ │ │
├────────────────────────>│ POST client-tokens │ │
│ ├──────────────────────>│ │
│<────客户端 Token────────┤<──────────────────────┤ │
│ 创建/启动/上报事件───────────────────────────────>│ │
│<──────────────────────────奖励 ELIGIBLE──────────┤ │
│ 请求处理 rewardId │ │ │
├────────────────────────>│ POST consume │ │
│ ├──────────────────────>│ │
│ │<─grantId/subject/reward┤ │
│ │ 核对用户与奖励后,事务写 grantId + 资产─────────>│
│ │<──────────────────────────────────────提交成功──┤
│ │ POST acknowledge │ │
│ ├──────────────────────>│ │
│<──查询自己的真实资产─────┤ │ │1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
后端可以由 APP 提示某条 rewardId,也可以使用 GET /server/rewards 发现待处理记录。APP 提示只是触发器,不能把 APP 传来的奖励数量当作可信数据。
处理器的顺序:
ts
async function fulfillPulledReward(rewardId: string, expectedSubjectId?: string) {
const reward = await adPost(`/server/rewards/${encodeURIComponent(rewardId)}/consume`);
if (reward.appId !== EXPECTED_PUBLIC_APP_ID) throw new Error('Unexpected application');
if (expectedSubjectId && reward.subjectId !== expectedSubjectId) {
throw new Error('Reward belongs to another user');
}
const grant = {
appId: reward.appId,
grantId: reward.grantId,
rewardId: reward.id,
subjectId: reward.subjectId,
sessionId: reward.sessionId,
placementCode: reward.placementCode,
rewardIntentId: reward.rewardIntentId,
businessKey: reward.businessKey,
reward: { code: reward.code, type: reward.type, amount: reward.amount },
};
// 必须在自己的数据库里实现;下面给出事务伪代码。
await fulfillGrantInBusinessDatabase(grant);
await adPost(`/server/rewards/${encodeURIComponent(reward.id)}/acknowledge`, {
grantId: reward.grantId,
});
return { grantId: reward.grantId, status: 'fulfilled' };
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
adPost 应封装后端密钥、JSON、超时、错误响应和有界重试。当前成功 POST 是 201,不能只检查 status===200。
对于客户端触发的接口,应先在自己的业务权限层确认请求与当前用户有关;consume 的响应是广告系统提供的权威用户归属,仍要再次核对。后台批处理没有“当前登录 APP 用户”,则按响应 subjectId 映射自己的用户。
server_webhook 完整流程
text
APP 完成观看
→ 广告系统记录 ELIGIBLE / DELIVERY_PENDING,并建立持久化通知任务
→ Worker 发送签名通知
→ 业务后端校验时间、原始 body HMAC、公开 appId 与字段
→ 业务数据库事务:grantId 去重 + 实际资产变化
→ 提交成功后响应 { grantId, status: "fulfilled" }
→ 广告系统记录 FULFILLED1
2
3
4
5
6
7
2
3
4
5
6
7
不要先返回成功再异步加金币。进程在回复成功后崩溃,会使广告系统认为已经到账而不再自动重试。若你的业务必须异步分发权益,需要先把任务持久化,并设计“真正完成后确认”的恢复流程;当前 Webhook 成功响应的语义是已兑现,而不是仅接收到消息。
验签和 HTTP 服务的完整 Node 示例见 Webhook 接入。两种模式应共用同一事务发奖函数,防止回调和恢复任务竞态。
业务数据库:去重与资产同一事务
以下为接入方自己的 MySQL 业务库设计示意,不是广告系统自动创建的表,也不是把演示代码复制过去就已拥有生产钱包。表名、用户外键和资产模型需要按自己的系统调整。
sql
CREATE TABLE ad_reward_grants (
app_id VARCHAR(64) COLLATE utf8mb4_0900_bin NOT NULL,
grant_id VARCHAR(64) COLLATE utf8mb4_0900_bin NOT NULL,
reward_id VARCHAR(32) COLLATE utf8mb4_0900_bin NOT NULL,
subject_id VARCHAR(191) COLLATE utf8mb4_0900_bin NOT NULL,
session_id VARCHAR(32) COLLATE utf8mb4_0900_bin NOT NULL,
placement_code VARCHAR(64) COLLATE utf8mb4_0900_bin NOT NULL,
reward_intent_id VARCHAR(32) COLLATE utf8mb4_0900_bin NULL,
business_key VARCHAR(128) COLLATE utf8mb4_0900_bin NULL,
reward_code VARCHAR(64) COLLATE utf8mb4_0900_bin NOT NULL,
reward_type VARCHAR(24) COLLATE utf8mb4_0900_bin NOT NULL,
amount BIGINT NOT NULL,
payload_hash CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
applied_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
PRIMARY KEY (app_id, grant_id),
UNIQUE KEY one_reward_once (app_id, reward_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
使用 grantId 稳定去重;notificationId 和 HTTP 请求 ID不能代替它。对同一 grantId 还应比对不可变字段,遇到“同一 grantId、不同用户/数量/奖励”的情况报警并拒绝覆盖旧记录。
事务伪代码:
text
fulfillGrantInBusinessDatabase(grant):
校验字段类型、正整数数量、预期公开 appId
fingerprint = SHA256(固定字段顺序序列化:
appId, grantId, rewardId, subjectId, sessionId,
placementCode, rewardIntentId, businessKey,
reward.code, reward.type, reward.amount)
BEGIN TRANSACTION -- 接入方业务库事务
try:
INSERT ad_reward_grants(所有上述字段)
-- 唯一约束保证并发重复通知只有一个事务能首次插入。
catch duplicate-key:
existing = SELECT * FROM ad_reward_grants
WHERE app_id = ? AND grant_id = ? FOR UPDATE
if existing 不存在或 existing.payload_hash != fingerprint:
ROLLBACK
报警并失败:同一发放标识对应不同内容
COMMIT
return { repeated: true } -- 不再修改任何资产
检查 subjectId 对应真实且允许接收奖励的用户
需要意图的奖励:核对 rewardIntentId、businessKey、placementCode
与业务库保存的用户、局/关卡、授权状态一致
按 reward.code + reward.type 在后端白名单选择处理器
验证 amount 上限、余额溢出和游戏业务条件
UPDATE 自己的金币/体力/道具/权益表
-- 必要时 SELECT ... FOR UPDATE 或条件 UPDATE 保证业务并发正确。
-- 更新必须成功;用户不存在、行数异常、业务拒绝均抛错。
COMMIT
return { repeated: false }
任何其他异常:
ROLLBACK -- 去重行与资产一起回滚,后续可以安全重试
抛出错误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
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
不可变字段 fingerprint 不要包括每次重试会变的签名、时间戳,也不需要包括 notificationId。业务数据库提交前不要调用 acknowledge,提交失败不要回复 Webhook fulfilled。
如果发放需要调用另一个独立服务,跨库/跨服务不具有上述单库事务的原子性。需要自己设计持久化发奖任务、该下游服务的幂等键和完成确认;不要用“先写去重行,再调用非幂等远程接口”冒充一次性发奖。
故障恢复矩阵
| 故障点 | 可观察结果 | 恢复动作 |
|---|---|---|
| consume 请求超时 | 可能已变为 CONSUMED_PENDING_ACK | 重试同一 rewardId,取回相同 grantId |
| consume 成功,业务事务未提交 | 广告系统待确认,本地无入账 | 恢复任务再次处理;事务唯一约束保护并发 |
| 业务事务提交成功,响应丢失 | 本地已入账,调用方不确定 | 再次处理命中 grantId 去重,返回原结果 |
| 已入账,ack 请求超时 | 本地已发,广告系统可能待确认或已完成 | 重复 acknowledge,不重复加资产 |
| Webhook 发放成功但 HTTP 响应丢失 | Worker 重试同一通知 | 验签后命中已发记录,重复返回 fulfilled |
| Worker 停止/服务离线 | DELIVERY_PENDING 堆积 | 恢复 Worker;持久化任务会继续被处理 |
| 自动回调重试耗尽 | 通知任务 failed,奖励仍 DELIVERY_PENDING | 管理后台检查原因、修复后手动重试;保持 grantId 去重 |
| 首次领取超 24 小时 | REWARD_EXPIRED | 业务补偿另行审计,不伪造重新观看或修改原奖励 |
主动拉取模式至少恢复 AVAILABLE 和 CONSUMED_PENDING_ACK。使用 业务后端分页 API 建立本地待处理队列,分页持久化后推进游标,定期全量幂等对账。不能只依赖 APP 在线时调用一次,也不能只处理第一页 100 条。
强制业务意图与可信业务上下文
可以创建 businessKey=revive:match_123:attempt_1 的意图,并让该用户创建会话时带上 rewardIntentId。服务端检查意图用户、应用、广告位、有效期和一次性绑定。业务后端先确认玩家确实处于该局的可复活状态,再创建意图,并保存返回 ID 与业务键的关联。
需要强制授权的广告位,应在后台开启 requireRewardIntent:
- 仅服务端交付模式的 rewarded 广告位可开启,默认 false 保持原接入兼容。
- 开启后缺少意图的创建请求返回 REWARD_INTENT_REQUIRED;意图只能绑定一次会话,换创建幂等键也不能重复消费。
- Reward 与签名 Webhook 回传 sessionId、placementCode、rewardIntentId、businessKey;没有意图时后两项为 null。
- 后端收到凭据后,把这些字段与自己保存的授权记录核对,再在真实业务事务中发奖或执行复活,不能仅检查业务键字符串形式。
意图仍不能指定任意动态数量或覆盖广告位奖励;具体奖励来自配置快照。关闭 requireRewardIntent 的广告位仍允许无意图使用,适合固定通用权益。业务规则、玩家状态、同局操作次数以及真实资产变化由接入方负责;广告系统不会替你判断局/关卡是否存在。
运行仓库业务后端示例
仓库 examples/business-server 是单进程、本机运行的示例,监听 127.0.0.1:3010,演示 Token 转发、Webhook 验签、consume → 本地持久化 → acknowledge。
在仓库根目录的终端配置自己的测试应用密钥和单独的演示访问 Token:
bash
export AD_API_URL='http://127.0.0.1:3000/v1'
export AD_APP_KEY='<从管理后台取得的测试应用serverKey>'
export DEMO_ACCESS_TOKEN='<自己生成的至少16字符随机值>'
pnpm --filter @ad/business-example dev1
2
3
4
2
3
4
这些是占位值,不是仓库中的真实密钥。可选配置:DEMO_PORT 默认 3010;DEMO_LEDGER_FILE 默认 .runtime/business-ledger.json,相对路径以运行进程工作目录为准。
| 示例服务接口 | 认证与用途 |
|---|---|
GET /health | 无认证,本机示例健康检查 |
POST /demo/token | Authorization: Bearer <DEMO_ACCESS_TOKEN>;body { "subjectId": "player_42" } |
POST /demo/reward-intent | 演示 Token;subjectId、placementCode、businessKey |
GET /demo/rewards | 演示 Token;只转发第一页奖励,不是完整分页对账实现 |
POST /demo/pull | 演示 Token;body { "rewardId": "cm_reward_01" },执行领取/幂等写入/确认 |
GET /demo/balances?subjectId=player_42 | 演示 Token;查看本地示例账本累计结果 |
POST /webhooks/rewards | 广告系统 HMAC 签名;原始请求体验签后写账本 |
本机 Webhook 调试需广告系统在非 production 环境显式开启 ALLOW_LOCAL_WEBHOOKS=true,并配置 http://127.0.0.1:3010/webhooks/rewards。生产接收地址必须符合公网 HTTPS 限制。
示例使用文件写队列、临时文件同步并重命名来持久化账本,只适合单进程验证。不提供真实用户登录,不具备多实例数据库事务、正式资产系统、完整分页调度或多密钥轮换接收能力。生产需要替换演示访问 Token、文件账本和业务授权,并使用本指南的数据库事务方案。
接入验收
至少验证:同一用户完整观看可到账;提前关闭不自动发奖;重复 claim/consume/ack/通知只发一次;进程在“入账后确认前”重启能恢复;同一应用不同用户不能串奖;不同应用不能串奖;密钥轮换后旧通知仍能验签;超过 100 条的奖励恢复能翻页完成;无广告、超冷却和 Token 过期有明确 UI 提示。