外观
客户端 API
所有路径相对于 /v1。除匿名 Token 接口外,每个接口都要求:
http
Authorization: Bearer <clientToken>1
客户端 Token 来自匿名接口或自己的业务后端。APP 中不能保存 X-App-Key。下文的 Session 和 Reward 字段在 数据模型 中完整定义,错误响应在 错误与重试 中定义。
1. 创建匿名身份
POST /client/anonymous-sessions → 201
只适用于应用交付模式为 client_claim。此接口不验证业务登录;服务端将安装标识散列成稳定的匿名 subjectId。
| 请求体字段 | 类型 | 必填 | 默认/范围 | 说明 |
|---|---|---|---|---|
appId | string | 是 | 无默认;最多 64 字符 | 管理后台显示的公开应用 ID,例如 app_demo;空值找不到应用 |
installationId | string | 是 | 无默认;8–128 字符 | 每次安装生成的高熵随机标识,例如 UUID;持久化后重复使用 |
当前这个请求体会忽略未知字段;其他多数业务请求采用严格字段校验。为了兼容后续版本,仍应只发送文档列出的字段。
bash
curl -X POST 'http://localhost:3000/v1/client/anonymous-sessions' \
-H 'Content-Type: application/json' \
--data '{"appId":"app_demo","installationId":"b856b7ac-a054-4672-bbe1-a1683fc013ef"}'1
2
3
2
3
json
{
"token": "<client-jwt>",
"subjectId": "anon_<installationId的SHA256十六进制值>",
"expiresAt": "2026-11-18T09:00:00.000Z"
}1
2
3
4
5
2
3
4
5
相同应用、相同 installationId 会恢复同一匿名身份,但每次返回的 Token 可以不同。卸载、清空本地存储或换 installationId 可能失去旧匿名奖励的访问能力。不要使用手机号、邮箱或容易被猜到的固定 ID;掌握 installationId 的调用者可以恢复相应匿名身份。
主要错误:400 INVALID_INPUT、404 APP_UNAVAILABLE、403 SERVER_IDENTITY_REQUIRED、429 RATE_LIMITED。有效期 1 小时,没有独立刷新接口。
2. 获取应用与广告位配置
GET /client/config → 200
无请求体、无定义的查询参数。返回当前应用和启用的广告位,按创建时间升序排列。
json
{
"app": {
"publicId": "app_demo",
"name": "示例游戏",
"deliveryMode": "client_claim"
},
"placements": [
{
"code": "revive",
"name": "失败后复活",
"type": "rewarded",
"rewardCode": "revive_once",
"rewardAmount": 1,
"imageSeconds": 5,
"videoMode": "complete",
"videoSeconds": 5,
"cooldownSeconds": 60,
"dailyLimit": 10,
"requireRewardIntent": false
}
]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| 响应字段 | 类型 | 说明 |
|---|---|---|
app.publicId | string | 公开应用 ID |
app.name | string | 应用显示名 |
app.deliveryMode | enum string | 当前应用设置的交付模式 |
placements[].code | string,1–64 | 应用内广告位代码,用于创建会话 |
placements[].name | string | 显示名 |
placements[].type | rewarded / display | 激励广告 / 普通展示广告 |
requireRewardIntent | boolean | 是否必须由业务后端先创建意图;默认 false |
rewardCode | string | 配置的奖励业务代码;display 不会创建奖励 |
rewardAmount | integer | 配置的数量 |
imageSeconds / videoMode / videoSeconds | 见 RulesSnapshot | 广告位层规则;实际选中投放可覆盖 |
cooldownSeconds | integer,0–86400 | 此广告位从启动开始的冷却秒数 |
dailyLimit | integer,1–1,000,000,000 | 该用户在该广告位的每日激励上限,不是剩余次数 |
当前不返回 rewardType、应用每日上限、应用时区或实时剩余额度。不能用配置响应替代会话快照决定最终奖励和观看时长。
主要错误:401 UNAUTHORIZED、403 APP_UNAVAILABLE、403 SERVER_IDENTITY_REQUIRED。
3. 创建广告会话
POST /client/ad-sessions → 201
必填请求头:
http
Authorization: Bearer <clientToken>
Content-Type: application/json
Idempotency-Key: 0cc6b294-b2ac-441c-b385-0e17cc92df3a1
2
3
2
3
| 请求字段 | 位置/类型 | 必填 | 默认/范围 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header string | 是 | 无默认;1–128 字符 | 本次用户“看一次广告”操作的随机键;重试保持不变 |
placementCode | body string | 是 | 无默认;1–64 字符 | 例如 revive |
rewardIntentId | body string | 条件必填 | 最多 32 字符 | requireRewardIntent=true 时必填;否则可省略,不能发送 null |
请求体严格校验,不接受 appId、subjectId、amount、rewardCode、providerId 等额外字段。应用与用户来自 Token,奖励来自后台配置。
json
{
"placementCode": "revive",
"rewardIntentId": "cm_intent_01"
}1
2
3
4
2
3
4
成功返回完整 Session:
json
{
"id": "cm_session_01",
"status": "CREATED",
"endReason": null,
"creative": {
"id": "cm_creative_01",
"kind": "video",
"url": "https://ads.example.com/v1/media/cm_creative_01",
"width": 1280,
"height": 720,
"durationSeconds": 15,
"clickUrl": null
},
"rules": {
"imageSeconds": 5,
"videoMode": "complete",
"videoSeconds": 5
},
"reward": {
"id": "cm_reward_01",
"grantId": "7fc5e85b-6aa3-40c2-92cc-5e6015d0c5cc",
"sessionId": "cm_session_01",
"code": "revive_once",
"type": "revive",
"amount": 1,
"eligibility": "PENDING",
"deliveryStatus": "NOT_READY",
"deliveryMode": "server_pull",
"reason": null,
"createdAt": "2026-11-18T08:00:00.000Z",
"expiresAt": null,
"placementCode": "revive",
"rewardIntentId": "cm_intent_01",
"businessKey": "revive:match_123:attempt_1"
},
"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
普通 display 广告的响应结构相同,但 reward: null。创建尚不算展示,也不会立即获得资格。先准备媒体,实际开始展示时再调用 start。创建 5 分钟后还未启动就会失效。
同一应用、同一用户、同一 key 和同一请求体返回原会话;即使原会话已经结束或过期也不会新建。相同 key 改变广告位或意图会返回 409 IDEMPOTENCY_CONFLICT。一次新广告需要新 key。把 key 和拿到的 sessionId 保存到恢复状态,避免请求丢失后无法知道活动会话。
同一应用内一个用户只能有一个活动会话。广告位 requireRewardIntent 默认 false;设为 true 时必须使用业务后端签发的身份并提供意图,缺失返回 403 REWARD_INTENT_REQUIRED。意图必须匹配应用、用户和激励广告位,未过期且未绑定其他会话。后台只允许服务端交付模式的 rewarded 广告位开启要求,业务后端不能将客户端传入的任意业务键当作已授权操作。
主要错误:400 INVALID_INPUT / IDEMPOTENCY_REQUIRED / INTENT_INVALID;403 APP_UNAVAILABLE / SERVER_IDENTITY_REQUIRED / REWARD_INTENT_REQUIRED;404 PLACEMENT_UNAVAILABLE / NO_FILL;409 SESSION_ACTIVE / IDEMPOTENCY_CONFLICT / INTENT_USED;429 FREQUENCY_CAPPED。
4. 查询与恢复会话
GET /client/ad-sessions/:id → 200
:id 为创建响应的 Session id。无请求体、无定义的查询参数。返回同一 Session 完整结构,其状态、有效观看秒数和嵌套奖励更新为当前值。
示例:
http
GET /v1/client/ad-sessions/cm_session_01
Authorization: Bearer <clientToken>1
2
2
json
{
"id": "cm_session_01",
"status": "SHOWING",
"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": null
},
"rules": {
"imageSeconds": 5,
"videoMode": "complete",
"videoSeconds": 5
},
"reward": null,
"creditedSeconds": 2,
"createdAt": "2026-11-18T08:00:00.000Z",
"startedAt": "2026-11-18T08:00:01.000Z",
"showDeadline": "2026-11-18T08:10:01.000Z",
"evidenceDeadline": "2026-11-18T08:20:01.000Z",
"lastSequence": 2
}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
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
这个例子是展示广告,因此 reward 为 null。查询会触发当前用户到期会话的清理,可能观察到 ENDED/EXPIRED。只有同一应用、同一 subjectId 能查询;无权访问与不存在均返回 404 NOT_FOUND。没有“查询当前活动会话 ID”的专门接口,客户端需要保存创建结果或原创建 key。
5. 开始展示
POST /client/ad-sessions/:id/start → 201
只需 Bearer 和会话 ID,不要求请求体或幂等头。可不发送 body;若通用调用器发送 {},当前实现不读取它。
成功返回完整 Session,关键变化:
json
{
"id": "cm_session_01",
"status": "SHOWING",
"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": null
},
"rules": {
"imageSeconds": 5,
"videoMode": "complete",
"videoSeconds": 5
},
"reward": null,
"creditedSeconds": 0,
"createdAt": "2026-11-18T08:00:00.000Z",
"startedAt": "2026-11-18T08:00:01.000Z",
"showDeadline": "2026-11-18T08:10:01.000Z",
"evidenceDeadline": "2026-11-18T08:20:01.000Z",
"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
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
重复 start 不重新设置开始时间,也不延长窗口;在应用仍启用、当前身份模式仍允许的前提下,已启动会话返回当前状态,即使后来已结束。应用暂停或匿名身份因模式切换不再允许时,会先返回 403。未启动会话过期或已关闭返回 409 SESSION_EXPIRED。后台在创建和启动之间暂停投放、素材或广告位,可能返回 409 AD_UNAVAILABLE。
启动成功后才累计观看;不要在媒体预加载阶段提前耗尽展示窗口。图片应可见,视频应可正常开始播放,且需要遵守浏览器的用户手势播放要求。
6. 上报播放事件
POST /client/ad-sessions/:id/events → 201
请求体为严格 JSON 对象:
json
{
"events": [
{
"eventId": "677f033b-f746-489b-a7bc-bf7fd73caa15",
"type": "heartbeat",
"sequence": 1,
"visible": true,
"visibleSeconds": 1.05,
"positionSeconds": 1.05,
"elapsedSeconds": 1.05
}
]
}1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
| 字段 | 类型 | 必填 | 默认/范围 | 说明 |
|---|---|---|---|---|
events | Event[] | 是 | 无默认;1–20 条 | 按 sequence 递增顺序排列 |
eventId | string | 是 | 1–128 字符 | 会话内唯一;重试同一事件保留原值 |
type | enum string | 是 | heartbeat / complete / close / click | 事件类别 |
sequence | integer | 是 | 正整数,从 1 开始递增 | 范围 1–2,147,483,647;从 1 连续编号,不跳号 |
visible | boolean | 是 | 无默认 | 事件发生时广告是否真实可见;页面隐藏/暂停时不能持续声明可见观看 |
visibleSeconds | finite number | 是 | 0–36000 | 从本会话开始累计的有效可见秒数,不是本次增量;可以为小数 |
elapsedSeconds | finite number | 否,推荐始终提供 | 0–36000 | 从 start 成功起累计经过秒数,含暂停/后台,不能改写重试事件 |
positionSeconds | finite number | 否 | >=0,无默认 | 视频播放位置秒数;图片可省略;视频应始终提供 |
对于视频,visibleSeconds 应只在视频正在正常播放且可见时增加,暂停、缓冲、后台不累计。对于图片,只在实际可见时增加。服务端同时使用自身收到请求之间的时间预算限制计入秒数。
| type | 用法 |
|---|---|
heartbeat | 播放期间定期上报;参考策略约每秒一次,可按网络情况批量,保持有序 |
complete | 图片完成所需时长、最短视频达标后结束、完整视频自然结束时发送;不是无条件发奖指令 |
close | 用户主动关闭或播放器退出;已经达标的资格不因此撤销,尚未达标则不会因关闭自动补足 |
click | 记录点击;不增加有效观看时间,不替代 complete;跳转由客户端根据 clickUrl 执行 |
成功返回完整 Session。下面是图片广告达标并 complete 的响应示例:
json
{
"id": "cm_session_01",
"status": "ENDED",
"endReason": "COMPLETED",
"creative": {
"id": "cm_creative_01",
"kind": "image",
"url": "https://ads.example.com/v1/media/cm_creative_01",
"width": 1280,
"height": 720,
"durationSeconds": null,
"clickUrl": null
},
"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": "ELIGIBLE",
"deliveryStatus": "AVAILABLE",
"deliveryMode": "client_claim",
"reason": null,
"createdAt": "2026-11-18T08:00:00.000Z",
"expiresAt": "2026-11-19T08:00:06.000Z",
"placementCode": "revive",
"rewardIntentId": null,
"businessKey": null
},
"creditedSeconds": 5,
"createdAt": "2026-11-18T08:00:00.000Z",
"startedAt": "2026-11-18T08:00:01.000Z",
"showDeadline": "2026-11-18T08:10:01.000Z",
"evidenceDeadline": "2026-11-18T08:20:01.000Z",
"lastSequence": 5
}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
顺序、批量和断网边界
服务端会保存乱序到达的事件,再按 sequence 从 1 开始重放连续前缀。比如先收到 2、3,随后收到 1:前两条先暂存,收到 1 后重新判定 1–3;响应 lastSequence 表示已重放的连续前缀,不是曾收到的最大序号。仍推荐使用一个持久化串行发送队列,避免不必要的缺口与冲突。
同一 eventId 和 sequence 对应的全部字段不可变,包括 elapsedSeconds。完全一致的重试幂等返回;相同 eventId 改内容、相同序号换 eventId 都返回 409 EVENT_CONFLICT,整批不会部分提交。每批仍最多 20 条,每个会话最多保存 2048 条不同事件;超出返回 429 EVENT_LIMIT_EXCEEDED,不是等待一会儿就会恢复的频率限制。
elapsedSeconds 应在 start 成功后用单调时钟计算,表示总经过时间,暂停或切后台时仍流逝;visibleSeconds 只表示有效可见观看。elapsedSeconds 不得超过服务端从 start 到首次接收此事件的经过时间(允许 0.25 秒时钟误差),否则返回 400 INVALID_EVENT_TIMING。客户端刷新后应恢复会话及事件队列,不应把同一会话的序号、累计时间重新归零。
所有已知的显式 elapsedSeconds 还必须随 sequence 单调不减,即使中间有序号缺口也会核对前后关系。最多允许 1 毫秒浮点误差,并与已知最大值比较,不能靠连续小幅倒退积累偏移;不符合返回 400 INVALID_EVENT_TIMELINE,整批不写入。不要使用会受系统时间调整影响的 Date.now 差值代替单调计时。
同一批的多条事件共享可用时间预算,不能把 1 秒实际时间变成 5 秒观看。视频倒退重播旧片段不重复计分,跳到最后一帧也不能替代有效时长。缺少 elapsedSeconds 的旧客户端仍可接入,但采用首次接收时间和后续事件约束保守计分,无法保证补算长时间断网的观看。
未 start 前只有“全部为 close”的批次允许取消预加载会话。启动后的展示窗口为 10 分钟,证据接收窗口为 20 分钟:超过 showDeadline 收到的事件,只有携带 elapsedSeconds、声明发生在截止前并通过重放校验,才可能补计。close 即使乱序先到也会释放活动槽位;随后补到的 close 之前的连续合法证据仍可获得资格,close 后实际发生的观看不计入。超过 evidenceDeadline 不再接收新事件;完全一致的已存事件重试仍返回当前会话。
主要错误:400 INVALID_INPUT / INVALID_EVENT_TIMING / INVALID_EVENT_TIMELINE、404 NOT_FOUND、409 EVENT_CONFLICT / SESSION_NOT_STARTED / SESSION_EXPIRED、429 EVENT_LIMIT_EXCEEDED。HTTP 成功不代表达标,始终检查 reward.eligibility。只有有效秒数足够、完成条件满足且已收到 complete,才会置 ENDED/COMPLETED;证据不足时仍可能 SHOWING,退出时应明确 close。
7. 查询当前用户奖励
GET /client/rewards → 200
无请求体。可选查询参数 after 接受上一页返回的 nextCursor。每页最多 100 条,按 createdAt 降序、id 降序返回当前应用/用户的历史奖励,包括尚未达标和已过期记录。没有 status、page 或 limit 参数。
| 查询参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
after | string | 否 | 不传,从最新奖励开始 | 上一页 nextCursor 原样传入,签名绑定当前用户/应用,7 天有效 |
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": "client_claim",
"reason": null,
"createdAt": "2026-11-18T08:00:00.000Z",
"expiresAt": "2026-11-19T08:00:06.000Z",
"placementCode": "revive",
"rewardIntentId": null,
"businessKey": null
}
],
"hasMore": false,
"nextCursor": null
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
响应包含 { items, hasMore, nextCursor }。hasMore=true 时,把 nextCursor 原样传给下一次请求;最后一页 nextCursor=null。游标是绑定当前应用和 subjectId 的签名不透明字符串,有效期 7 天;跨用户/应用复用、篡改或过期均返回 400 INVALID_CURSOR。重新签发同一身份的客户端 Token 不影响未过期的历史游标。
这是向更早历史翻页的游标,不是增量更新游标;刷新最新奖励时省略 after。客户端与 业务后端奖励分页接口 的游标不可混用。恢复时遍历历史并按 grantId 去重,同时保留本地待处理奖励;不要仅处理第一页或把列表顺序当作实际发放顺序。
8. 客户端领取奖励
POST /client/rewards/:id/claim → 201
:id 是 reward.id,不是 sessionId 或 grantId。无请求体。仅适用于该奖励冻结的 deliveryMode=client_claim。
json
{
"id": "cm_reward_01",
"grantId": "7fc5e85b-6aa3-40c2-92cc-5e6015d0c5cc",
"sessionId": "cm_session_01",
"code": "coin",
"type": "currency",
"amount": 100,
"eligibility": "ELIGIBLE",
"deliveryStatus": "CLAIMED",
"deliveryMode": "client_claim",
"reason": null,
"createdAt": "2026-11-18T08:00:00.000Z",
"expiresAt": "2026-11-19T08:00:06.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
首次领取需要 ELIGIBLE,且在达标后 24 小时内。重复领取同一奖励返回相同 grantId,已 CLAIMED 的重试不受首次领取期限阻断。
当前 claim 接口不读取、不校验也不依赖 Idempotency-Key 请求头。 创建会话接口使用该头,不代表所有 POST 都使用。claim 的幂等性由奖励行和状态转换实现。
客户端先检查本地是否已应用 grantId,再把本地资产变化与 grantId 应用标记尽量放在同一持久化事务中。若收到响应后直接加金币、之后才单独存标记,崩溃恢复仍可能重复加金币。对于有真实服务端资产的应用,应使用 server_pull 或 server_webhook。
主要错误:404 NOT_FOUND、403 DELIVERY_MODE_MISMATCH、409 REWARD_PENDING / REWARD_EXPIRED。
9. 报告本地奖励已应用
POST /client/rewards/:id/reported-applied → 201
无请求体。只有属于当前用户、client_claim 且状态 CLAIMED 的奖励可调用。报告用于记录客户端反馈,不修改成 FULFILLED。
json
{
"recorded": true,
"verified": false
}1
2
3
4
2
3
4
重复请求保持已记录状态;条件不满足返回 404 NOT_FOUND。verified: false 明确表示广告系统无法核实本地资产。接入方不能把这个响应当作服务端到账证明。
最小客户端顺序
text
获取 Token → 获取配置 → 创建会话并保存 key/sessionId
→ 加载媒体 → start → 串行 heartbeat / complete / close
→ 查看服务端 eligibility 与 deliveryMode
client_claim: claim → 本地按 grantId 去重应用 → reported-applied
server_pull: 通知自己的业务后端处理 → 查询自己后端资产
server_webhook: 等待自己后端入账 → 查询自己后端资产1
2
3
4
5
6
2
3
4
5
6
调用完成事件、看到广告窗口消失、或收到 HTTP 201 都不是发奖条件。只有服务端返回的奖励状态和接入方自己的幂等入账结果能决定展示“奖励已到账”。