外观
快速开始
本指南带你启动开发环境,在管理后台查看投放,并通过参考播放器完成“创建会话 → 真实播放 → 资格成立 → 领取奖励凭证”。所有记录进入本地 MySQL;演示素材属于自有广告,不会产生第三方广告联盟收入。
如果你只负责 APP 接入,并且已经拿到部署地址和公开 App ID,可以直接阅读客户端接入。
1. 准备运行环境
| 工具 | 当前项目要求 | 用途 |
|---|---|---|
| Node.js | 22 系列;仓库已在 22.17 验证 | API、worker、前端开发工具 |
| pnpm | 10;仓库声明 10.29.1 | 工作区依赖和启动命令 |
| MySQL | 8.4+,本机有 mysqld、mysql、mysqladmin | 事务、配置、奖励和通知任务 |
| FFmpeg / ffprobe | 命令可从 PATH 调用 | 视频检查、封面及开发视频生成 |
| 浏览器 | 支持现代 Web API 的桌面浏览器 | 管理后台与 Web 参考播放器 |
本地快捷脚本会创建独立开发数据库,使用 127.0.0.1:33307/ad_system 和工作区内的 .runtime/mysql-test,不会把系统已有的 MySQL 数据目录用作开发数据目录。开发端口需要空闲。
2. 安装并启动
在仓库根目录执行:
sh
pnpm install --frozen-lockfile
pnpm dev1
2
2
首次启动会生成未纳入 Git 的根目录 .env,其中包含随机管理员密码、数据库密码、JWT 签名密钥和应用密钥的加密密钥。已有 .env 会保留。业务后端使用的 X-App-Key 不在这里生成给客户端,而是在管理后台创建或轮换应用密钥时显示。
启动脚本依次执行以下工作:
- 载入环境变量,检查目标数据库为本机专用开发数据库。
- 初始化或复用工作区对应的 MySQL,等待数据库就绪。
- 构建广告来源接口包、生成 Prisma 客户端、应用数据库迁移。
- 初始化管理员和开发演示投放。
- 启动 API、worker、管理后台、参考播放器和开发者文档。
按 Ctrl+C 会停止这个命令启动的进程;已经存在并被复用的同工作区 MySQL 不属于本次新启动进程。运行目录中的上传文件、配置和数据会保留。
使用已有数据库
如果根目录 .env 已指向其他端口或数据库,pnpm dev 会拒绝接管它。这是快捷脚本的范围限制。请填写自己的环境配置并使用独立启动命令,见本页后面的“使用已有 MySQL”。
3. 打开入口
| 页面 | 本地地址 |
|---|---|
| 管理后台 | http://127.0.0.1:5173 |
| Web 参考播放器 | http://127.0.0.1:5174/?appId=app_demo |
| 开发者文档 | http://127.0.0.1:5175;管理后台侧栏也有入口 |
| API 路由文档 | http://127.0.0.1:3000/docs |
| 健康检查 | http://127.0.0.1:3000/v1/health |
健康检查成功示例:
json
{
"status": "ok",
"version": "0.1.0",
"database": "mysql"
}1
2
3
4
5
2
3
4
5
管理员登录信息来自根目录 .env 中的 ADMIN_EMAIL 和 ADMIN_PASSWORD。不要把整个 .env 粘贴到日志、工单或客户端工程中。初始管理员密码必须非空;当前实现不设置密码字符数上下限。
重复执行 seed 不会覆盖已有管理员密码和已经修改的广告规则。修改 .env 中的初始密码后再运行 seed,并不会自动修改已有管理员的密码。
4. 完成一次图片激励
开发 seed 提供以下对象:
| 对象 | 标识或内容 |
|---|---|
| 应用公开 ID | app_demo |
| 图片广告位 | daily_bonus |
| 视频广告位 | daily_video |
| 奖励交付模式 | client_claim |
| 图片素材 | 本地生成的 PNG |
| 视频素材 | 本地生成的 8 秒 MP4 |
在参考播放器操作:
- Public App ID 输入
app_demo。 - Identity mode 保持 Anonymous installation。播放器会创建并保存安装 ID。
- 点击 Connect application,确认显示已连接和可用广告位。
- 选择
daily_bonus,点击 Load ad。这一步创建服务端会话并冻结本次规则,还没有开始计时。 - 点击 Watch advertisement,保持页面前台可见,实际观看广告。
- 出现 Reward ready — close to claim. 后关闭广告,再点击 Claim reward。
- 检查 Credential claimed 和 Local demo inventory;后台奖励记录应显示同一笔
CLAIMED。 - 再点击 Recover same claim 或 Restore history,同一
grantId不应再次增加演示库存。
初始图片时长一般为 5 秒,但以当前后台配置和创建会话返回的 rules 为准。开发数据被修改过时,seed 不会把它重置为默认值。
领取凭证与业务入账
CLAIMED 表示广告服务已交付奖励凭证。参考播放器把它映射为浏览器本地演示库存,不是可信游戏资产账户。需要可信发奖的应用应使用业务后端模式,详见奖励交付。
5. 验证视频、暂停和中断
切换到 daily_video,重新加载并观看。视频默认静音、正常速度播放;可以通过播放器按钮暂停、恢复或打开声音。
- 切换到隐藏标签页会暂停视频,隐藏和暂停期间不累计有效播放时间。
- 完整播放模式需要到达视频末尾并满足服务端时长条件。
- 最低观看时长模式按本次会话的
rules.videoSeconds判断,后台创建或编辑投放时可以覆盖广告位规则。 - 提前关闭没有达到要求的广告,不会因为触发了关闭回调就自动产生奖励。
- 刷新后可以恢复奖励查询,但当前参考播放器不会续播刷新前已经开始的视频。
如果提示 FREQUENCY_CAPPED,请等待该广告位冷却结束,或在开发后台调整测试规则。不要通过在生产端反复生成新安装 ID 来绕过频控。
6. 使用自己的素材
在管理后台按以下顺序配置:
- 应用:创建应用,选择交付模式。记录公开 App ID;创建时返回的服务端 key 仅供业务后端保管。
- 广告位:创建稳定的业务编码,例如
revive,设置奖励与频控。 - 素材:上传实际图片或视频,确认检查通过并可预览。
- 投放:关联应用、广告位和素材,设置时间、权重及可选观看规则覆盖,发布为启用状态。
- 参考播放器:使用新应用的公开 App ID 和广告位编码测试。
只有广告位存在还不够:没有已发布、处于排期内且素材可用的投放时,加载会返回 NO_FILL。素材、广告位和投放必须属于同一应用。
7. 用 TypeScript 验证连接
@ad/client-core 是仓库中的私有工作区包,尚未发布到 npm。先按客户端接入中的引入方式配置依赖或本地别名,再使用:
ts
import { AdClient } from '@ad/client-core';
const installationKey = 'my-game:ad-installation';
let installationId = localStorage.getItem(installationKey);
if (!installationId) {
installationId = crypto.randomUUID();
localStorage.setItem(installationKey, installationId);
}
const ads = new AdClient({ baseUrl: 'http://127.0.0.1:3000/v1' });
const identity = await ads.initializeAnonymous('app_demo', installationId);
const config = await ads.getConfig();
console.log({ subjectId: identity.subjectId, placements: config.placements });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
这段代码只验证身份和配置,不会假装完成观看。完整集成需要实际渲染媒体并测量前台播放,见播放与事件及客户端完整示例。
8. 使用已有 MySQL
复制 .env.example 为 .env,填写数据库连接与随机密钥。以下命令均从仓库根目录运行:
sh
pnpm --filter @ad/provider-core build
pnpm db:generate
pnpm db:migrate
pnpm db:seed
pnpm dev:api1
2
3
4
5
2
3
4
5
在另外的终端分别运行:
sh
pnpm worker1
sh
pnpm dev:admin1
sh
pnpm dev:player1
sh
pnpm dev:docs1
数据库约束以 SQL 迁移为准。不要用 prisma db push 代替迁移,因为复合外键和部分约束由手写 SQL 定义。NODE_ENV=production 时 seed 仅初始化管理员,不创建上述演示应用与素材。
常见启动与接入问题
| 现象 | 检查方向 |
|---|---|
| 提示找不到 MySQL 或 FFmpeg 命令 | 检查工具是否已安装并进入启动进程的 PATH |
| 开发启动拒绝数据库地址 | 快捷启动只管理 127.0.0.1:33307/ad_system;其他数据库改用独立命令 |
无法登录,但修改 .env 无效 | 已有管理员密码不被 seed 覆盖,检查实际账户而非反复初始化 |
| 播放器配置为空 | 检查公开 App ID 和广告位是否启用 |
NO_FILL | 检查投放启用、排期、素材状态、展示配额及观看规则是否可达 |
SESSION_ACTIVE | 当前身份还有未结束会话;完成或关闭原会话,异常退出时查询并等待过期 |
| 视频或图片加载失败 | 检查 PUBLIC_API_URL、媒体 URL、API 可达性和浏览器控制台 |
| 页面有响应但跨域请求失败 | 检查 API 的 CORS_ORIGINS 是否包含客户端页面的实际 origin |
| 显示奖励确认中 | 查询同一会话;不要因为超时重新创建一笔奖励或直接修改余额 |
接下来阅读核心概念,理解应用、广告位、会话和奖励之间的关系。