外观
接入验收
本页是一份面向接入方的验证清单。广告系统自己的自动化测试不能替代你的 APP、播放器和业务资产服务的联调。
基础接入
| 场景 | 操作 | 预期 |
|---|---|---|
| 正常身份 | 用正确 App ID 和稳定安装 ID 或业务 token 连接 | 配置返回目标应用的广告位 |
| 身份隔离 | 用户 B 读取用户 A 的会话/奖励 | 返回找不到,不泄露其他用户数据 |
| 应用隔离 | APP B 的凭据访问 APP A 的记录 | 被拒绝 |
| token 过期 | 过期后刷新同一身份的 token | 原身份数据仍可恢复 |
| 服务端模式 | 尝试匿名连接 server_pull/webhook 应用 | 返回 SERVER_IDENTITY_REQUIRED |
| 密钥放置 | 检查 APP 代码、网络和持久化 | 不包含 X-App-Key 的服务端 key |
广告与播放
- 图片正常前台展示达到会话规则,服务器返回
ELIGIBLE。 - 视频正常播放完成;最低时长模式使用实际返回阈值。
- 隐藏页面、切后台、暂停视频不继续增加有效观看时间。
- 拖动到视频末尾或直接发送 complete,不能当成正常完整观看。
- 提前退出允许关闭,并显示实际奖励状态。
- 普通展示广告的
reward为 null,不显示“领取奖励”。 - 投放暂停、素材失效、无填充时显示可理解的结果,不无限加载。
- 操作期间修改后台奖励,已创建会话仍使用原快照,新会话采用新配置。
防重与断网恢复
| 注入故障 | 预期行为 |
|---|---|
| 创建会话后响应丢失 | 相同 Idempotency-Key 重试返回同一会话 |
| 事件请求响应丢失 | 重发原 eventId 和 sequence,不能重复计分 |
| 多次点击领取 | 取得相同 grantId,业务资产最多增加一次 |
| 发奖后 APP 崩溃 | grantId 与本地资产或业务事务一起恢复,避免只记其中一项 |
| 后端入账后确认失败 | 重放同一 grant,再确认,不生成第二笔业务奖励 |
| Webhook 重复或并发到达 | 数据库唯一约束及同一事务确保只入账一次 |
| 回调入账后响应丢失 | 后续相同 grant 回调返回同一成功确认 |
| 登录身份切换 | 旧用户的待处理会话不能记入新用户 |
| close 比心跳先到 | 先关闭展示;补齐原始连续证据后重新判断资格,不把关闭后的时间计入 |
| 播放期间 token 过期 | 同身份刷新后重放同一事件,不丢失队列或重复计分 |
| 刷新页面 | 恢复原会话、创建 key 和待传事件;不计离线时间 |
| 过期队列阻塞 | 确认会话终止后归档旧证据,允许新会话;临时失败保留队列 |
| 超过 100 条历史奖励 | 分页恢复所有记录,已入本地账本的 grant 不重复增加资产 |
| 奖励并发提交 | 保存游标后仍能看到稍后提交的另一事务,忽略墙钟时间差 |
纯客户端存储可以被用户清除或篡改,它只提供本地体验层面的去重。需要可信资产的场景应由你自己的业务后端控制余额与入账。
业务后端检查
/server/client-tokens的subjectId来自已验证的业务登录身份,不直接信任浏览器传入的任意用户 ID。- 发奖前核对应用、用户、rewardCode、数量及业务上下文。
- 用数据库唯一 grantId 约束防重,并把防重记录与资产修改放在同一个事务中。
- 分页恢复保存
nextCursor,按状态更新幂等处理;历史记录因更新再次出现是正常行为。 - 相同 grantId 出现不同业务内容时拒绝并告警,不静默覆盖。
- 错误日志可关联 requestId,但不记录凭据。
- 对复活、任务等一次性机会,启用广告位
requireRewardIntent;无意图请求应被拒绝,通知和拉取结果中的businessKey必须匹配已授权业务记录。 - 过期
AVAILABLE变成EXPIRED;既有CLAIMED、CONSUMED_PENDING_ACK可恢复,不因首次消费期限过去而丢单。
项目内自动化命令
在独立开发环境中运行,不对正式运营数据库运行集成测试:
sh
pnpm build
pnpm test
pnpm test:integration
pnpm test:client
pnpm test:examples
pnpm test:providers1
2
3
4
5
6
2
3
4
5
6
数据库集成测试需要 MySQL 和 API。未开启集成测试开关时,部分数据库场景会明确跳过;pnpm test:integration 会要求服务可用。
HTTP 客户端真实接口测试:
sh
cd examples/business-server
AD_API_URL=http://127.0.0.1:3000/v1 \
node --import tsx --test ../../packages/client-core/test/live.test.ts1
2
3
2
3
此类测试会构造计时播放证据,不能替代目标设备上的真实图像、视频、前后台生命周期和网络体验验收。
发布前补齐的环境事项
检查实际 HTTPS 域名、CORS、素材持久化、数据库备份、密钥保管、通知 worker 监控、容量及目标平台隐私流程。初版尚未交付正式原生 SDK、真实第三方联盟、跨区域高可用、自动长期数据归档和外部开发者计费。
对 Android、iOS、Cocos、Unity 或小游戏接入,需要另外实现其渲染、生命周期、网络与平台能力适配。HTTP API 契约可以复用,Web 页面通过并不代表已完成这些平台的发布验收。