外观
业务后端 API
这些接口由接入方自己的可信业务后端调用,路径相对于 /v1。每次请求必须携带应用服务端密钥:
http
X-App-Key: <serverKey>
Content-Type: application/json1
2
2
GET 或无 body 的 POST 可以省略 Content-Type。密钥对应一个应用,只能访问该应用的数据。接口不使用客户端 Bearer Token,也不使用管理后台 Cookie。缺少密钥、密钥错误、密钥已轮换或应用暂停均可能返回 401 UNAUTHORIZED。
本文只描述广告系统接口。业务后端仍要验证自己的用户登录、游戏状态和业务权限,并在自己的数据库里发放权益。完整流程见 业务后端接入。
1. 签发客户端 Token
POST /server/client-tokens → 201
| 请求体字段 | 类型 | 必填 | 默认/范围 | 说明 |
|---|---|---|---|---|
subjectId | string | 是 | 无默认;1–191 字符 | 业务后端认证得到的稳定用户 ID;按原值保存,大小写敏感 |
请求体严格校验,不允许额外的 appId、过期时间、奖励数量等字段。
json
{
"subjectId": "player_42"
}1
2
3
2
3
json
{
"token": "<client-jwt>",
"subjectId": "player_42",
"expiresAt": "2026-11-18T09:00:00.000Z"
}1
2
3
4
5
2
3
4
5
Token 有效 1 小时,可返回给已经认证的 APP 用户调用客户端接口。该接口没有业务幂等键;重复调用可签发新的 Token,不会产生广告或奖励。没有指定 Token TTL、refresh-token、逐用户吊销接口。
业务后端必须从自己的登录会话中确定 subjectId,不能直接相信客户端提交的任意用户 ID。Player_A 与 player_a 是两个身份;如果业务用户系统要求大小写不敏感,应在业务后端统一规范化后始终发送相同规范值。不同应用可以使用相同 subjectId,但奖励和额度仍按应用隔离。
主要错误:400 INVALID_INPUT、401 UNAUTHORIZED。
2. 创建奖励业务意图
POST /server/reward-intents → 201
业务意图用于把一个经过后端授权的操作与一次广告会话关联,例如“第 123 局的第一次复活机会”。广告位 requireRewardIntent 默认 false;开启后,它就是创建该广告位会话的强制前置条件。只有服务端交付模式的 rewarded 广告位可以开启。
| 请求体字段 | 类型 | 必填 | 默认/范围 | 说明 |
|---|---|---|---|---|
subjectId | string | 是 | 无默认;1–191 字符 | 后续客户端 Token 的同一用户 |
placementCode | string | 是 | 无默认;1–64 字符 | 必须是当前应用启用的 rewarded 广告位 |
businessKey | string | 是 | 无默认;1–128 字符 | 该应用内唯一的业务操作键,例如 revive:match_123:attempt_1 |
json
{
"subjectId": "player_42",
"placementCode": "revive",
"businessKey": "revive:match_123:attempt_1"
}1
2
3
4
5
2
3
4
5
json
{
"id": "cm_intent_01"
}1
2
3
2
3
当前只返回 id,不返回 expiresAt 或完整业务键。服务端有效期为创建后 1 小时,最多绑定一个会话。业务后端应保存业务键、意图 ID 与自己的业务操作关联,并将 ID 交给客户端,作为创建会话的 rewardIntentId。
相同应用下重复 businessKey:如果 subjectId 和 placementCode 相同则返回原 ID;不同则 409 IDEMPOTENCY_CONFLICT。返回原 ID不会延长有效期,也不会解除已经绑定的会话。用户锁、唯一约束和事务重试保护并发创建;网络超时仍应保持原参数和 businessKey 重试。
该接口不接受自定义数量、奖励代码、金额或有效期,奖励仍来自广告位快照。requireRewardIntent=true 时客户端不能省略意图,缺失返回 REWARD_INTENT_REQUIRED;应用也不能在仍有要求意图的广告位时切换为 client_claim。
Reward 和 Webhook 均回传 placementCode、rewardIntentId、businessKey,后端可与自己的授权记录核对。业务后端必须先验证登录、游戏状态和操作是否被允许,再创建意图;不要仅因为前端传入某个 businessKey 就签发。意图限制一次广告会话,不能自动替代接入方的游戏规则或资产事务。
主要错误:400 INVALID_INPUT、404 PLACEMENT_UNAVAILABLE、409 IDEMPOTENCY_CONFLICT / CONFLICT。
3. 分页查询应用奖励
GET /server/rewards → 200
| 查询参数 | 类型 | 必填 | 默认/范围 | 说明 |
|---|---|---|---|---|
after | string | 否 | 默认从最早记录开始 | 原样传入上次 nextCursor;URL 编码由 URLSearchParams 等标准库处理 |
status | enum string | 否 | 默认不筛选 | AVAILABLE / CONSUMED_PENDING_ACK / DELIVERY_PENDING / FULFILLED / CLAIMED / EXPIRED |
当前不支持 page、limit、subjectId、placementCode、from、to 等查询条件。每页最多 100 条,按应用内按提交顺序分配的 syncVersion 升序读取。status 筛选交付状态,不是 eligibility;EXPIRED 可筛选,NOT_READY/REJECTED 暂不能单独筛选,但不筛选时会返回。
http
GET /v1/server/rewards?status=AVAILABLE
X-App-Key: <serverKey>1
2
2
json
{
"items": [
{
"id": "cm_reward_01",
"grantId": "7fc5e85b-6aa3-40c2-92cc-5e6015d0c5cc",
"sessionId": "cm_session_01",
"code": "coin",
"type": "currency",
"amount": 100,
"eligibility": "ELIGIBLE",
"deliveryStatus": "AVAILABLE",
"deliveryMode": "server_pull",
"reason": null,
"createdAt": "2026-11-18T08:00:00.000Z",
"expiresAt": "2026-11-19T08:00:05.000Z",
"appId": "app_game_public",
"subjectId": "player_42",
"updatedAt": "2026-11-18T08:00:05.000Z",
"syncVersion": "42",
"placementCode": "revive",
"rewardIntentId": null,
"businessKey": null
}
],
"hasMore": false,
"nextCursor": "<服务端返回的不透明游标>"
}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
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
| 响应字段 | 类型 | 说明 |
|---|---|---|
items | RewardWithOwner[] | 基础 Reward + 公开 appId、subjectId、updatedAt、syncVersion |
hasMore | boolean | 此次查询时,在当前筛选和游标后是否还有下一页 |
nextCursor | string | 本页末尾的 v2 游标;空页保留当前序号,没有 after 时生成序号 0 的游标 |
cursorReset | boolean,可能省略 | 旧 at/id 游标迁移时返回 true,表示本次从头安全重放 |
syncVersion 是十进制字符串,不要转换为 JavaScript Number;需要数值比较时使用 BigInt。updatedAt 仍供展示,不能再用它作为同步进度。
v2 游标携带版本、公开应用 ID、status 筛选和同步序号,接入方应视为不透明字符串。跨应用或改变 status 后复用游标返回 400 CURSOR_SCOPE_MISMATCH;畸形游标返回 400 INVALID_CURSOR。客户端历史列表的签名游标与此处格式不同,不能混用。
兼容旧 { at, id } 游标:第一次收到旧游标时,服务端从序号 0 开始安全重放当前筛选结果,不把旧时间戳推算为序号;响应带 cursorReset: true 和新 v2 nextCursor。保留已有 grantId 入账记录,允许重复读取,并保存新游标,不能因重放再发奖励。
有界分页示例
ts
type RewardRow = {
id: string;
grantId: string;
subjectId: string;
appId: string;
deliveryMode: string;
deliveryStatus: string;
eligibility: string;
updatedAt: string;
syncVersion: string;
};
type RewardPage = {
items: RewardRow[];
hasMore: boolean;
nextCursor: string;
cursorReset?: boolean;
};
// apiBase、appKey 来自后端配置;不是前端环境变量。
async function syncRewards(
apiBase: string,
appKey: string,
checkpoint: string | null,
acceptPage: (page: RewardPage) => Promise<void>,
) {
let cursor = checkpoint;
// 限制单轮工作量,下一轮从持久化检查点继续。
for (let pageNumber = 0; pageNumber < 100; pageNumber++) {
const url = new URL(`${apiBase.replace(/\/$/, '')}/server/rewards`);
if (cursor) url.searchParams.set('after', cursor);
const response = await fetch(url, {
headers: { 'X-App-Key': appKey },
signal: AbortSignal.timeout(10_000),
redirect: 'error',
});
if (!response.ok) throw new Error(`Ad API HTTP ${response.status}`);
const page = (await response.json()) as RewardPage;
// 在自己的数据库事务中持久化本页记录/待处理任务及 nextCursor。
// 业务处理失败前不要仅保存游标跳过本页。
await acceptPage(page);
cursor = page.nextCursor;
if (!page.hasMore) return cursor;
}
return cursor;
}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
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
这段代码的 acceptPage 是接入方要实现的持久化函数。建议将收到的奖励以 rewardId/upsert 保存到自己的待处理表,和游标一起提交,再由独立任务进行 consume/入账/ack,避免游标已推进而业务处理任务丢失。
增量视图的边界
这是按提交序号读取的当前奖励行视图,不是每个中间状态都保存一条的事件日志。正常写入由 reward-sync-store 在同一个业务事务中锁定应用的 RewardSyncState 行、分配序号并写奖励,锁保持到提交;后分配的序号不会先于前一个事务提交,避免单用 updatedAt 时低时间戳晚提交造成漏读。当前使用显式事务方法,不依赖数据库 trigger;绕过服务直接改表不属于受支持的同步写入路径。
记录更新后以新 syncVersion 再次出现,两个轮询之间的中间状态可能已被最新状态替代。按 rewardId 保存最新视图,以 grantId 去重入账,不能假定每条奖励只出现一次。
hasMore=false 只表示这次读取暂无更多,不意味着永远没有新奖励。保存 nextCursor,后续定时继续读。更改 status 条件应使用独立检查点或从头扫描,不能把一个筛选条件的进度直接复用为另一个筛选条件的完整进度。
生产恢复仍应持久化“已 consume 未 ack”任务,并定期幂等对账,发现业务处理或检查点故障。提交有序的同步游标解决数据读取进度问题,不替代业务任务持久化、资产事务或 grantId 去重。
主要错误:400 INVALID_CURSOR / CURSOR_SCOPE_MISMATCH / INVALID_INPUT、401 UNAUTHORIZED。
4. 领取后端发放凭据
POST /server/rewards/:id/consume → 201
:id 是 Reward 的 id。无请求体,不要求 Idempotency-Key。仅支持奖励自身 deliveryMode=server_pull。
http
POST /v1/server/rewards/cm_reward_01/consume
X-App-Key: <serverKey>1
2
2
json
{
"id": "cm_reward_01",
"grantId": "7fc5e85b-6aa3-40c2-92cc-5e6015d0c5cc",
"sessionId": "cm_session_01",
"code": "coin",
"type": "currency",
"amount": 100,
"eligibility": "ELIGIBLE",
"deliveryStatus": "CONSUMED_PENDING_ACK",
"deliveryMode": "server_pull",
"reason": null,
"createdAt": "2026-11-18T08:00:00.000Z",
"expiresAt": "2026-11-19T08:00:05.000Z",
"appId": "app_game_public",
"subjectId": "player_42",
"placementCode": "revive",
"rewardIntentId": null,
"businessKey": null
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
调用后只是把状态改成 CONSUMED_PENDING_ACK,不会自动给你的用户加金币。业务后端必须核对公开 appId、subjectId 和奖励类型,然后以 grantId 在自己的数据库中去重并发奖。
已经 CONSUMED_PENDING_ACK 或 FULFILLED 时,重复 consume 返回当前记录、同一 grantId 和用户身份,不重新创建奖励,也不被首次领取期限阻断。首次 consume 要求 ELIGIBLE 且在达标后 24 小时内。
主要错误:404 NOT_FOUND、403 DELIVERY_MODE_MISMATCH、409 REWARD_PENDING / REWARD_EXPIRED。接收到由 APP 转交的 rewardId 时,仍必须校验响应 subjectId 是否属于当前已登录用户;应用密钥具有应用范围权限,不能省略自己的用户授权。
5. 确认实际发奖完成
POST /server/rewards/:id/acknowledge → 201
| 请求体字段 | 类型 | 必填 | 默认/范围 | 说明 |
|---|---|---|---|---|
grantId | string | 是 | 无默认;原样使用发放凭据 | 必须与该应用、该奖励 ID 匹配;当前 schema 仅检查字符串类型,空/错误值查不到记录 |
json
{
"grantId": "7fc5e85b-6aa3-40c2-92cc-5e6015d0c5cc"
}1
2
3
2
3
json
{
"id": "cm_reward_01",
"grantId": "7fc5e85b-6aa3-40c2-92cc-5e6015d0c5cc",
"sessionId": "cm_session_01",
"code": "coin",
"type": "currency",
"amount": 100,
"eligibility": "ELIGIBLE",
"deliveryStatus": "FULFILLED",
"deliveryMode": "server_pull",
"reason": null,
"createdAt": "2026-11-18T08:00:00.000Z",
"expiresAt": "2026-11-19T08:00:05.000Z",
"placementCode": "revive",
"rewardIntentId": null,
"businessKey": null
}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
响应是基础 Reward,不包含 appId/subjectId/updatedAt。只有自己的业务资产事务提交成功后才能发送确认。重复确认已 FULFILLED 的同一奖励是幂等的,不延长首次 fulfilledAt。
当前允许非 client_claim 奖励在 CONSUMED_PENDING_ACK、DELIVERY_PENDING 或 FULFILLED 时确认。因此除了 server_pull 正常流程,它也能用于 server_webhook 模式下业务后端完成实际入账后的恢复确认。若选择这种恢复方式,仍必须与回调共用同一 grantId 去重账本,避免两个入口并发重复发放。
主要错误:400 INVALID_INPUT、404 NOT_FOUND(含 grantId 不匹配)、409 INVALID_STATE。不能确认 AVAILABLE、NOT_READY 或 client_claim 奖励。
应用密钥轮换
创建应用或在管理后台轮换密钥时获取 serverKey,安全存入业务后端配置。只读应用列表不会反复返回明文密钥。
轮换成功后,旧 X-App-Key 立即不能再调用 /server/*,当前没有 API 请求认证的双密钥宽限期。提前准备配置热更新或短暂维护窗口,轮换后将新密钥同步到所有后端实例。
Webhook 有不同规则:每条奖励在会话创建时保存当时的签名密钥和通知 URL。已有奖励继续用旧密钥发通知,新会话使用新密钥。接收端需要在迁移期间保留按应用管理的新旧验签密钥,并在旧奖励处理完后再移除旧密钥。通知头没有 keyVersion;完整处理方式见 Webhook 密钥轮换。