外观
接口总览与约定
本文档对应当前初版实现,覆盖 APP 客户端、APP 业务后端和奖励通知接口。广告系统负责广告选择、播放证据记录、奖励资格和交付状态;金币、体力、复活次数、道具等实际权益由接入方兑现。
基础地址
| 环境 | API Base URL | 说明 |
|---|---|---|
| 本地开发 | http://localhost:3000/v1 | 下文请求路径都相对于这个地址 |
| 自行部署 | https://ads.example.com/v1 | 将示例域名替换为实际部署地址 |
请求和响应采用 UTF-8 JSON;带 JSON 请求体时设置 Content-Type: application/json。时间返回 ISO 8601 UTC 字符串,例如 2026-11-18T08:00:00.000Z,时长字段以秒为单位。金额/数量是整数,没有浮点货币结算语义。
当前 GET 成功返回 200,以下所有 POST 成功返回 201,包括重复请求、start、claim、consume 和 acknowledge。客户端应接受成功的 2xx 状态,不要只接受 200。
API 没有统一的 { data: ... } 外层:单个对象直接返回,列表使用 { items: [...] }。客户端历史奖励与业务后端同步列表还返回各自的分页字段。响应可能新增字段,接入方应忽略未知响应字段;请求字段则应严格按文档发送。
认证分层
| 调用方向 | 认证 | 使用者 | 保密要求 |
|---|---|---|---|
APP → POST /client/anonymous-sessions | 公开 appId + 安装标识 | 无业务后端的 APP,仅 client_claim | appId 不是密钥;安装标识应随机且持久化 |
APP → 其余 /client/* | Authorization: Bearer <clientToken> | APP、Web 参考播放器、未来 SDK | Token 属于当前用户,避免记录到日志或 URL |
业务后端 → /server/* | X-App-Key: <serverKey> | 可信的 APP 业务后端 | 必须留在后端,不能打包进 APP、H5、SDK |
| 广告系统 → 业务后端 Webhook | HMAC-SHA256 请求签名 | 广告系统 Worker | 业务后端按原始请求体验签 |
这些接口不使用管理后台登录 Cookie,也不要求管理后台的 CSRF Token。管理账号权限与客户端用户身份是不同体系。X-App-Key 决定可访问的应用,不能通过请求体中的 appId 切换其他应用。
客户端 Token 有效期为 1 小时。没有 refresh-token 接口:匿名模式重新调用匿名会话接口;有后端模式由业务后端重新签发。已签发 Token 不会因为应用密钥轮换自动失效。应用暂停会阻止新的配置读取、广告创建和启动;不要把应用暂停理解为对每个历史查询接口的 Token 即时吊销。
三种奖励交付模式
模式在管理后台按应用设置,新建广告会话时冻结到奖励记录中。修改应用模式不会改写已有奖励的模式。
| 模式 | 客户端身份 | 达标后的动作 | 最终可观察状态 | 适用场景 |
|---|---|---|---|---|
client_claim | 匿名或业务后端签发的 Token | APP 调用 claim,按 grantId 在本地去重后应用奖励 | CLAIMED;本地报告不代表服务端验证到账 | 无业务后端、低价值本地权益 |
server_pull | 必须由业务后端签发 Token | 后端 consume → 自己的数据库事务发奖 → acknowledge | FULFILLED | 有业务后端,主动拉取与恢复 |
server_webhook | 必须由业务后端签发 Token | 接收签名通知 → 自己的数据库事务发奖 → 返回确认 JSON | FULFILLED | 有公网 HTTPS 接收端,希望异步自动发奖 |
广告系统的 ELIGIBLE 表示已满足当前广告证据规则。CLAIMED 表示客户端取得了领取结果。FULFILLED 表示业务后端已确认兑现。三者含义不同,不能仅凭播放器完成动画就增加服务端资产。
详细流程参见 业务后端接入 和 Webhook 接入。
全量接口索引
客户端接口
| 方法与路径 | 请求认证 | 用途 | 成功响应 |
|---|---|---|---|
POST /client/anonymous-sessions | 无 Token | 取得匿名客户端 Token | 201,Token 对象 |
GET /client/config | Bearer | 读取应用与启用的广告位 | 200,配置对象 |
POST /client/ad-sessions | Bearer + Idempotency-Key | 选择广告并创建一次广告会话 | 201,Session |
GET /client/ad-sessions/:id | Bearer | 查询/恢复一次会话 | 200,Session |
POST /client/ad-sessions/:id/start | Bearer | 确认开始展示 | 201,Session |
POST /client/ad-sessions/:id/events | Bearer | 上报心跳、完成、关闭、点击 | 201,Session |
GET /client/rewards?after= | Bearer | 当前用户历史奖励,每页 100 条 | 200,{ items, hasMore, nextCursor } |
POST /client/rewards/:id/claim | Bearer | 领取 client_claim 奖励 | 201,Reward |
POST /client/rewards/:id/reported-applied | Bearer | 报告已在本地应用奖励 | 201,{ recorded, verified } |
请求字段、示例与重试规则见 客户端 API。
业务后端接口
| 方法与路径 | 请求认证 | 用途 | 成功响应 |
|---|---|---|---|
POST /server/client-tokens | X-App-Key | 为已登录业务用户签发客户端 Token | 201,Token 对象 |
POST /server/reward-intents | X-App-Key | 创建一次性业务意图,广告位可要求必填 | 201,{ id } |
GET /server/rewards | X-App-Key | 应用范围奖励查询、分页与恢复 | 200,{ items, hasMore, nextCursor } |
POST /server/rewards/:id/consume | X-App-Key | 领取 server_pull 发奖凭据 | 201,带用户身份的 Reward |
POST /server/rewards/:id/acknowledge | X-App-Key | 业务数据库提交后确认到账 | 201,Reward |
请求字段和分页算法见 业务后端 API。没有单独的 /server/rewards/:id GET 接口。
标识符不要混用
| 标识符 | 示例占位值 | 含义与边界 |
|---|---|---|
| 公开应用 ID | app_demo | 匿名登录请求的 appId;配置中的 app.publicId;业务奖励响应与 Webhook 中的 appId |
| 数据库内部应用 ID | cm_internal_app | 管理后台/数据库关联键;不要拿它调用匿名登录,也不需要客户端解析 JWT 获得它 |
| 广告位代码 | revive | 应用内唯一的 placementCode,不是内部广告位 ID |
| 用户标识 | player_42 | 后端确定的 subjectId,应用内隔离,大小写敏感;匿名标识由系统生成 |
| 会话 ID | cm_session_01 | Session 的 id,用于 start/events/get |
| 奖励 ID | cm_reward_01 | Reward 的 id,用于 claim/consume/acknowledge |
| 发放 ID | 7fc5e85b-6aa3-40c2-92cc-5e6015d0c5cc | grantId,一次奖励的稳定去重标识;用于业务入账唯一约束 |
| 业务意图 ID | cm_intent_01 | rewardIntentId,一次性绑定会话;启用 requireRewardIntent 的广告位必须提供 |
| 通知 ID | 5a84cb21-5514-4760-a4ef-45ae010752b4 | notificationId,同一 Webhook 任务重试保持不变;不要用它替代资产入账的 grantId |
示例 ID 用来解释字段,不保证是当前数据库中的真实记录。除你自己定义的 subjectId、businessKey 和广告位代码外,其他 ID 应按不透明字符串保存,不推导长度以外的结构。
幂等与恢复
| 操作 | 幂等依据 | 正确重试方式 |
|---|---|---|
| 创建广告会话 | 应用 + 用户 + Idempotency-Key,同时核对请求体 | 同一操作保持相同 key 和请求体;新广告生成新 key |
| start | 已有会话的 startedAt | 使用同一会话 ID 重试 |
| events | 会话 + eventId/sequence,不可变事件内容 | 从 1 连续编号;乱序暂存并重放连续前缀,重试保留原事件 |
| 创建业务意图 | 应用 + businessKey,核对用户和广告位 | 同一业务操作保持同一 key;不因请求超时换 key |
| claim | 奖励行和 CLAIMED 状态 | 使用同一奖励 ID 重试;当前实现不读取 Idempotency-Key |
| consume / acknowledge | 奖励状态与稳定 grantId | 重试原奖励;自己数据库以 grantId 去重 |
| Webhook | 重试稳定 notificationId + 稳定 grantId | 重复通知仍返回同一成功确认,资产只增加一次 |
这些机制保证广告系统的状态转换可重试,不会自动保证第三方业务数据库只发一次。业务后端必须把“去重记录”和“资产变化”放在同一数据库事务中。
当前实现与扩展边界
| 能力 | 当前状态 |
|---|---|
| 自有图片、视频投放;激励/展示广告位 | 已实现;display 会话的 reward 为 null |
| 三种奖励交付模式、用户范围隔离、奖励资格与额度 | 已实现 |
| HTTP API、TypeScript 接入层、Web 参考播放器 | 已实现 |
| 投放选择 | 已实现:可用候选中先取最高优先级,再按权重选择;没有可用候选返回 NO_FILL |
| 第三方广告网络真实接入 | 未实现;已预留 Provider 抽象,不能直接把第三方 SDK 当作现有能力使用 |
| Android/iOS/Unity/Cocos 原生 SDK | 后续封装;本期通过通用 HTTP 接入 |
| 服务端真实性证明、设备完整性验证、第三方 SSV | 未实现;自有广告依据客户端播放数据与服务端计时判断 |
| 现金钱包、提现、支付、自动修改接入方资产 | 未实现 |
| 奖励意图指定动态数量/币种、签名离线奖励凭证 | 未实现;奖励内容来自后台广告位快照 |
| 客户端历史奖励分页、服务端按提交序号同步 | 已实现;两个游标协议分别绑定用户身份或应用/筛选条件 |
| 广告位强制业务意图、奖励业务上下文回传 | 已实现;后台开关默认关闭,服务端交付的激励广告位可开启 |
| 单独 Token 撤销、Webhooks 密钥版本头 | 未实现 |
通用限制
当前 API JSON 请求体上限为 256kb。进程内按来源 IP 限流:匿名 Token 接口每 60 秒 60 次,其余请求共享每 60 秒 1200 次的桶。超限返回 429 RATE_LIMITED,当前不返回 Retry-After。这不是分布式限流,也不同于后台配置的用户激励次数与冷却规则。
部署在反向代理后时,需要配置明确的 TRUST_PROXY 白名单;默认不信任转发头。Compose 只信任两个固定 Nginx 网关地址,Nginx 覆盖外部转发链。详见 可信代理与限流。
Web 跨域访问的页面 Origin 必须出现在部署的 CORS 允许列表中。HTTP 客户端应设置请求超时、对瞬时网络错误退避重试,并保留 X-Request-Id 或错误体中的 requestId 便于排查。完整错误表见 错误与重试。