外观
数据模型与状态
本页描述对外 JSON,而不是数据库完整表结构。字段名的大小写、null 和状态字符串都具有实际含义。
Token
json
{
"token": "<client-jwt>",
"subjectId": "player_42",
"expiresAt": "2026-11-18T09:00:00.000Z"
}1
2
3
4
5
2
3
4
5
| 字段 | 类型 | 说明 |
|---|---|---|
token | string | 1 小时有效的客户端 JWT;直接放进 Bearer 请求头,不需要解码 |
subjectId | string | 本次身份;后端签发时原样使用业务用户标识,匿名时由系统生成 |
expiresAt | ISO 时间 string | Token 到期时间;到期后重新走原来的身份获取流程 |
Token 不是应用密钥,不可用来调用 /server/*。它属于一个应用、一个用户;客户端不能通过修改请求体切换用户。
Session:一次广告会话
以下是创建后尚未启动的激励图片会话:
json
{
"id": "cm_session_01",
"status": "CREATED",
"endReason": null,
"creative": {
"id": "cm_creative_01",
"kind": "image",
"url": "https://ads.example.com/v1/media/cm_creative_01",
"width": 1280,
"height": 720,
"durationSeconds": null,
"clickUrl": "https://example.com/promotion"
},
"rules": {
"imageSeconds": 5,
"videoMode": "complete",
"videoSeconds": 5
},
"reward": {
"id": "cm_reward_01",
"grantId": "7fc5e85b-6aa3-40c2-92cc-5e6015d0c5cc",
"sessionId": "cm_session_01",
"code": "coin",
"type": "currency",
"amount": 100,
"eligibility": "PENDING",
"deliveryStatus": "NOT_READY",
"deliveryMode": "client_claim",
"reason": null,
"createdAt": "2026-11-18T08:00:00.000Z",
"expiresAt": null,
"placementCode": "revive",
"rewardIntentId": null,
"businessKey": null
},
"creditedSeconds": 0,
"createdAt": "2026-11-18T08:00:00.000Z",
"startedAt": null,
"showDeadline": null,
"evidenceDeadline": null,
"lastSequence": 0
}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
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
| 字段 | 类型 | 含义 |
|---|---|---|
id | string | 会话 ID,最长 32 字符;用于 get/start/events |
status | CREATED / SHOWING / ENDED | 展示生命周期,不等同于奖励交付状态 |
endReason | null / CLOSED / COMPLETED / EXPIRED | 关闭、完成或超时;未结束通常为 null |
creative | CreativeSnapshot | 本次选中的素材快照 |
rules | RulesSnapshot | 本次实际适用规则,包含投放覆盖值 |
reward | Reward / null | 激励广告有奖励对象,普通展示广告为 null |
creditedSeconds | number | 服务端认可的有效秒数,可为小数;不是客户端累计计时的直接复制 |
lastSequence | integer | 服务端已重放的从 1 开始连续事件前缀末尾,初始为 0;不等于收到过的最大序号 |
createdAt | ISO 时间 string | 会话创建时间 |
startedAt | ISO 时间 string / null | 首次 start 成功时间 |
showDeadline | ISO 时间 string / null | 启动后 10 分钟;只计入在此之前发生且通过校验的观看证据 |
evidenceDeadline | ISO 时间 string / null | 启动后 20 分钟;过后拒绝新事件,完全一致的已存事件重试仍可读取当前状态 |
未启动会话有 5 分钟有效期,但当前 Session JSON 没有 expiresAt 字段。 这个时间保存在服务端,不要把嵌套 reward.expiresAt 当作会话启动期限。创建后应尽快开始展示;过期需要新的会话和新的创建幂等键。
CreativeSnapshot
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 素材 ID,不是会话 ID |
kind | image / video | 决定使用图片或视频渲染器 |
url | string | 可直接加载的媒体地址;按完整地址使用,不自行拼接存储路径 |
width / height | integer / null | 素材检测到的尺寸,用于保持比例 |
durationSeconds | number / null | 视频实测时长;图片通常为 null |
clickUrl | string / null | 点击跳转目标;null 时不提供跳转;点击不自动完成奖励条件 |
媒体可能来自本地媒体代理或对象存储/CDN。客户端请求媒体不需要把应用服务端密钥附加到 URL 或请求头。播放失败时显示错误并关闭会话,不要把媒体加载失败当作已观看。
RulesSnapshot
| 字段 | 类型与范围 | 管理后台创建默认值 | 适用方式 |
|---|---|---|---|
imageSeconds | integer,1–600 | 5 | 图片有效可见秒数 |
videoMode | complete / minimum | complete | 完整播放,或最短有效播放时长 |
videoSeconds | integer,1–600 | 5 | 仅 minimum 模式作为达标阈值;complete 按实际素材时长 |
这些默认值只是后台创建配置的初始值,客户端不能写死。广告位规则可修改,投放可覆盖图片时长、视频模式与最短时长。本次播放必须使用 Session 的 rules;GET /client/config 仅返回广告位层面的规则。
视频 minimum 的最终阈值若大于素材时长,该候选不会投放;没有其他候选时返回 NO_FILL。规则和奖励信息在创建会话时冻结。后台更新新规则主要影响新会话;已创建但尚未启动的会话仍会在 start 时检查应用/广告位/投放/素材是否可用。
Reward:奖励资格与交付记录
json
{
"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",
"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
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 奖励 ID,最长 32 字符;调用奖励路由时使用 |
grantId | string,当前为 UUID | 稳定发放 ID;领取重试、通知重试、确认重试都不改变它 |
sessionId | string | 对应的广告会话;一会话最多一条奖励 |
placementCode | string,1–64 | 创建奖励的广告位业务编码 |
rewardIntentId | string / null | 已绑定业务意图 ID;没有意图时为 null |
businessKey | string / null | 意图中由业务后端指定的操作键;没有意图时为 null |
code | string,1–64 | 业务奖励代码,例如 coin、revive_once、item:sword |
type | string enum | currency、energy、revive、item、entitlement、custom |
amount | integer,1–1,000,000,000 | 奖励数量,来自广告位快照;默认 100,可配置 |
eligibility | string enum | 资格状态,见下表 |
deliveryStatus | string enum | 交付状态,见下表 |
deliveryMode | string enum | client_claim、server_pull、server_webhook |
reason | string / null | 尚未满足、拒绝或过期等辅助说明;不能依赖英文文案做逻辑分支 |
createdAt | ISO 时间 string | 奖励随广告会话创建的时间,早于资格达成时间 |
expiresAt | ISO 时间 string / null | 达标后设置为达标时间 +24 小时;未达标通常为 null |
基础 Reward 已包含 placementCode、rewardIntentId 和 businessKey;不含 subjectId、公开 appId、updatedAt 或内部组织 ID。GET /server/rewards 额外提供 appId、subjectId、updatedAt 和十进制字符串 syncVersion;consume 额外提供 appId、subjectId。Webhook 同样回传业务意图上下文,业务后端应核对自己保存的操作关联。
grantId 是去重标识,不是可以离线验签的兑换券。当前没有“拿到 grantId 即可无认证兑现”的接口,也没有签名奖励凭证验证接口。
资格状态 eligibility
| 状态 | 当前含义 |
|---|---|
PENDING | 仍在等待服务端判断观看条件 |
ELIGIBLE | 有效观看条件满足;只表示获得资格 |
REJECTED | 例如未启动就关闭会话 |
EXPIRED | 启动/证据有效期结束,或达标后超过首次领取期限仍未领取 |
交付状态 deliveryStatus
| 状态 | 当前含义 |
|---|---|
NOT_READY | 尚未达标;升级前的部分被拒绝记录可能保持此状态 |
REJECTED | 未启动就关闭等明确拒绝场景 |
AVAILABLE | client_claim 或 server_pull 已达标,可以首次领取 |
CLAIMED | client_claim 已领取;不能证明本地资产确实增加 |
CONSUMED_PENDING_ACK | server_pull 已返回发放凭据,等待业务后端确认 |
DELIVERY_PENDING | server_webhook 已排队或等待投递;自动重试耗尽时奖励仍可能保持这个状态 |
FULFILLED | 业务后端通过确认接口或合格 Webhook 响应确认兑现 |
EXPIRED | 会话/证据到期,或 AVAILABLE 奖励超过首次领取期限未消费 |
首次 claim/consume 超过 24 小时会返回 REWARD_EXPIRED。清理 Worker 和相关读取/领取接口会把已过期、仍 AVAILABLE 的 client_claim/server_pull 奖励持久化为 eligibility=EXPIRED、deliveryStatus=EXPIRED,并产生新的同步序号。状态更新不是精确定时器,仍应结合 expiresAt 判断。已经 CLAIMED、CONSUMED_PENDING_ACK、FULFILLED 的记录不会因首次领取期限结束而过期,幂等恢复和补确认仍可执行。
Webhook 自动重试不按 reward.expiresAt 截断,可超过 24 小时。停止重试属于通知任务状态 failed,不是奖励交付状态 FAILED;当前 Reward 中没有 FAILED 这个值。
状态流转
text
Session: CREATED --start--> SHOWING --完成/关闭/展示超时--> ENDED
└--未启动关闭/5分钟超时----------------------> ENDED
Reward eligibility: PENDING --有效证据达标--> ELIGIBLE
├--未启动关闭------> REJECTED
└--证据窗口超时----> EXPIRED
ELIGIBLE --未领取且首次领取期限结束--> EXPIRED
client_claim: NOT_READY -> AVAILABLE -> CLAIMED
server_pull: NOT_READY -> AVAILABLE -> CONSUMED_PENDING_ACK -> FULFILLED
server_webhook: NOT_READY -> DELIVERY_PENDING -----------------> FULFILLED1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
图片和 minimum 视频可能在一次 heartbeat 后先获得资格,而会话仍为 SHOWING。此时应继续按播放器流程发送 complete 或 close 结束展示,避免占用该用户的活动会话位置。complete 事件本身不保证结束会话:只有有效秒数足够、完成条件满足并且已收到 complete,服务端才置为 ENDED/COMPLETED。 证据不足时 complete 之后仍可能是 SHOWING,应继续查询/上报或明确 close。会话结束不会撤销已经取得的资格;会话为 ENDED 也不保证一定取得了资格。
每个应用内的同一 subjectId 同时只能有一个活动会话,限制覆盖多个广告位。展示超时后,查询/新建与清理 Worker 会释放占用。不能通过重试创建接口生成并行广告。
时效与额度一览
| 项目 | 当前值/规则 |
|---|---|
| 客户端 Token | 签发后 1 小时 |
| RewardIntent | 创建后 1 小时;重复 businessKey 不续期;最多绑定一个会话 |
| 未启动广告会话 | 创建后 5 分钟 |
| 有效展示窗口 | start 后 10 分钟 |
| 事件接收窗口 | start 后 20 分钟;后 10 分钟只允许补报声明发生于展示截止前且通过校验的证据 |
| 首次 claim/consume | 达标后 24 小时 |
| 同广告位冷却 | 后台创建默认 60 秒,范围 0–86400;从 start 计时 |
| 用户每广告位每天激励次数 | 后台创建默认 10,可修改 |
| 用户每应用每天激励次数 | 后台创建默认 30,可修改 |
| 日界线 | 应用配置时区,后台创建默认 UTC;不是用户设备本地零点 |
用户的应用/广告位激励次数在 rewarded 会话创建时预占,达到 ELIGIBLE 时消耗;未完成资格的预占在清理到期时释放,未启动关闭会立即释放。已经 start 后未达标就 close,会释放活动会话位置,但激励次数预占可能保留到证据窗口结束。 普通 display 会话不占用户激励额度,仍受广告位冷却约束。投放自己的每日上限按展示预占,在 start 时消耗,规则与用户激励次数不同。前端不应自行推算还剩多少次;当前配置接口不返回实时剩余额度。
播放证据的含义
服务端保存最多 2048 条不可变事件,按 sequence 从 1 开始重放连续前缀,缺失的早期事件补到后可以重新判定。elapsedSeconds 是自 start 被接受后的单调累计经过秒数,包括后台和暂停时间;visibleSeconds 则只累计有效可见观看。服务端用首次接收时间限制 elapsedSeconds,结合可见时长与视频进度计算 creditedSeconds。缺少 elapsedSeconds 的旧客户端采用首次接收时间及后续事件约束做保守计分,不保证跨展示截止时间补算。
close 即使先于更小序号到达,也会结束活动展示;但在 evidenceDeadline 前补齐 close 之前的合法连续证据,仍可能取得资格。close 后实际发生的新观看不计入。重复 eventId/sequence 只有内容完全一致才幂等返回,改写内容返回 EVENT_CONFLICT。图片有 0.05 秒、视频有 0.3 秒的达标容差;接入方仍按完整阈值播放。
所有已知显式 elapsedSeconds 按 sequence 必须单调不减,跨序号缺口也校验;1 毫秒浮点容差不能逐次累计倒退。首次接收已经超过 showDeadline 且缺少 elapsedSeconds 的旧事件,不会因后续事件提供较小时间而被重新解释为截止前观看。
视频已观察到的最高位置不会因为倒退而减少,重播同一片段不能反复补足有效秒数。跳播也不能用最后一帧直接换取完整观看时间。完整视频模式还要求 complete 事件和接近素材结束的位置。
这些判断依赖客户端报告,不等同于防篡改证明。业务后端签发身份解决用户归属,不能单独证明真实观看行为。第三方服务端验证和设备可信能力属于后续扩展。