外观
版本与能力范围
2026-11-18 · 可靠恢复修复
- 播放证据按连续事件序号重算;关闭先到时保留补传窗口。新增
elapsedSeconds记录原始采样时间,截止后的补传不延长实际观看窗口。 - HTTP 客户端支持同身份 token 刷新回调;参考播放器持久化创建操作和事件,恢复时保持原请求标识。终态过期证据归档后可开始下一次观看。
- 奖励同步改用事务内分配的每应用序号,修复并发提交漏同步;旧游标安全重放。未领取的过期奖励更新为
EXPIRED,已领取/已消费订单仍可恢复。 - 广告位可启用
requireRewardIntent,由业务后端先授权一次业务机会;奖励和通知返回rewardIntentId/businessKey,客户端奖励历史支持分页。 - 代理仅信任显式网关地址,Nginx 覆盖转发来源;登录限流按来源和账号分桶,避免不同用户相互误伤。
这是包含数据库迁移的修复。升级前停止旧 API/worker 并备份,运行 pnpm db:generate、pnpm db:migrate 后重启。不要混跑旧、新版本写入进程。本地快捷启动用户停止原命令后重新运行 pnpm dev。
2026-11-18 · 开发者文档站
- 提供中文接入指南、TypeScript 客户端方法参考、完整客户端/业务后端 HTTP 参考。
- 补充实际播放证据、重试与奖励恢复、Webhook 验签、分页同步及密钥轮换说明。
- 提供全文搜索、代码复制、页内目录、移动端阅读和参考客户端源代码下载。
- 文档站独立运行于默认端口 5175,也随
pnpm dev一起启动。
本次增加文档网页,不改变现有广告 API 路径和奖励协议。
0.1.0 · 初版行为基线
| 能力 | 状态 |
|---|---|
| 自有静态图片、MP4 视频投放 | 已实现 |
| 激励广告、普通展示 | 已实现;参考播放器为 Web |
| 客户端领取、业务后端拉取、签名 webhook | 已实现 |
| 配额、冷却、配置快照、会话和奖励防重 | 已实现 |
| 组织/应用隔离、角色、审计 | 已实现;成员权限为组织范围 |
| 本地文件存储 | 已验证 |
| 私有 S3 适配 | 已提供代码,真实存储环境未完成连接验证 |
| 第三方广告适配能力契约 | 已预留,当前只注册 house |
| 正式 Cocos/Unity/Android/iOS SDK | 后续实现 |
| 外部开发者入驻、计费、现金提现 | 后续范围 |
| 组合奖励、玩家钱包 | 当前未实现;每笔奖励为一项权益 |
管理员密码仅要求非空,不设置最小或最大字符数;首次创建规则与成员创建规则一致。服务端应用密钥与 JWT 签名密钥仍使用独立的随机密钥机制。
HTTP 客户端版本
仓库包名为 @ad/client-core,版本 0.1.0,标记为 private,尚未发布到 npm。它提供 HTTP 调用、类型和可选 refreshToken 回调:并发 401 合并刷新,每个请求最多重放一次。网络重试、持久事件队列和本地账本由 Web 参考播放器演示;包本身不提供原生渲染器或可信玩家资产账本。
正式 SDK 发布之前,接入方可按 客户端接入 引入参考源码,并使用 TypeScript API 参考 核对调用方式。
文档与实现的对应关系
文档以本仓库当前实现为准,示例 App ID、用户 ID、token 和业务记录都是说明性占位值。请求的实际响应由你的后台配置与运行状态决定。
Swagger /docs 当前主要提供路由目录,尚未补齐全部字段 schema。网页中的参数表、响应模型与示例用于补足这部分接入说明,不意味着已经提供可直接生成正式 SDK 的完整 OpenAPI 定义。
如发现差异,记录调用路径、HTTP 状态、code、requestId 及代码版本,按 排查模板 反馈,避免把旧版本示例直接用于另一个版本的服务端。