外观
客户端接入
客户端接入分为身份、配置、观看会话、播放证据和奖励交付五部分。参考 AdClient 封装 HTTP 请求,并支持可选的 401 token 刷新回调;它没有内置播放器、通用网络自动重试、持久队列或游戏资产操作。
推荐先用快速开始跑通参考播放器,再把 HTTP 客户端与自己的 UI、生命周期和存档结合。
选择身份模式
| 场景 | 推荐接法 | 可用交付模式 |
|---|---|---|
| 本地单机游戏,暂无业务后端 | 持久化安装 ID,调用 initializeAnonymous() | 仅 client_claim |
| 已有登录和用户数据库 | 业务后端为已认证用户申请短期 token,客户端调用 setToken() | 由应用配置决定 |
| 需要可信金币、道具或权益入账 | 业务后端持有 server key,使用拉取或 webhook 交付 | server_pull / server_webhook |
匿名身份的安装 ID 可以被重置。跨设备账号、可信资产或具有较高价值的奖励,应由自己的业务后端建立用户身份并兑现。
引入参考客户端
在独立项目中使用源码
下载当前版本的 client-core.ts,保存为项目中的 src/lib/ad-client.ts,然后使用相对路径:
ts
import { AdClient, AdApiError, type AdSession } from './lib/ad-client';1
下载文件在文档站点启动或构建前从仓库真实源码生成。升级服务端时应一起核对客户端版本和接口变化;该文件不包含播放器或业务入账逻辑。后面的完整 Web 配方采用此文件布局。
工作区包
包的真实名称是 @ad/client-core,位于 packages/client-core,目前 private: true,直接导出 TypeScript 源文件。它没有发布到公共 npm,不能把 npm install @ad/client-core 当作可用的安装步骤。
在同一个 pnpm 工作区内,你可以在自己的客户端应用 package.json 添加:
json
{
"dependencies": {
"@ad/client-core": "workspace:*"
}
}1
2
3
4
5
2
3
4
5
然后从仓库根目录执行 pnpm install,在支持 TypeScript 源文件的构建工具中使用:
ts
import { AdClient, AdApiError, type AdSession } from '@ad/client-core';1
包依赖运行时提供 fetch、AbortController 和 crypto.randomUUID()。它不直接提供 Cocos、Unity、Android 或 iOS 的网络与生命周期适配层。没有这些 Web API 的环境需要先实现对应适配,不能只复制 import 就宣称完成原生 SDK 接入。
当前参考播放器的别名
仓库中的 apps/player-demo 使用的是 Vite 本地别名 @ad-system/client-core。该名字不是另一个 npm 包,而是指向同一份源代码:
ts
// apps/player-demo/vite.config.ts 中的实际映射方式
import { defineConfig } from 'vite';
import { fileURLToPath, URL } from 'node:url';
export default defineConfig({
resolve: {
alias: {
'@ad-system/client-core': fileURLToPath(
new URL('../../packages/client-core/src/index.ts', import.meta.url),
),
},
},
});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
本文后续使用真实工作区包名 @ad/client-core。在参考播放器目录复制代码时,可沿用它已经配置的本地别名;两者指向相同的类和类型。
外部项目可以把经过审查的这份客户端源码作为内部依赖维护,或先构建并发布到自己的私有包仓库。当前仓库没有提供已经发布的跨平台 SDK 安装地址。
配置 API 地址
baseUrl 必须包含 API 版本前缀 /v1,不要包含 /client:
ts
import { AdClient } from '@ad/client-core';
// 同源反向代理:浏览器当前站点把 /v1 转发到广告 API。
const sameOriginAds = new AdClient({ baseUrl: '/v1' });
// 跨域部署:API 的 CORS_ORIGINS 必须允许客户端页面的 origin。
const remoteAds = new AdClient({
baseUrl: 'https://ads.example.com/v1',
timeoutMs: 12_000,
});1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
https://ads.example.com 是示例域名,需替换成自己的服务。构造器会移除一个末尾 /,不会替你推断版本路径。
参考播放器开发服务器把 /v1 和 /media 代理到 API。跨域直连时还要保证素材返回的 URL 能由终端访问;浏览器中的 localhost 指当前用户的设备,不是远程服务器。
客户端请求固定使用 credentials: 'omit',通过 Authorization: Bearer ... 认证,不携带管理后台 Cookie。不要把管理员登录会话作为 APP 认证。
匿名安装身份
匿名模式只允许 deliveryMode=client_claim 的应用。安装 ID 长度要求为 8–128 字符,推荐使用首次安装生成并持续保存的 UUID。
ts
import { AdClient } from '@ad/client-core';
const appId = 'app_demo';
const installationKey = `my-game:ad-installation:${appId}`;
function installationId(): string {
const stored = localStorage.getItem(installationKey);
if (stored) return stored;
const created = crypto.randomUUID();
localStorage.setItem(installationKey, created);
return created;
}
export const ads = new AdClient({ baseUrl: '/v1' });
const identity = await ads.initializeAnonymous(appId, installationId());
const config = await ads.getConfig();
// 可以记录 subjectId 作为本地奖励记录的命名空间;不要记录 token。
const subjectId = identity.subjectId;
const tokenExpiresAt = new Date(identity.expiresAt);
console.log(config.app.name, subjectId, tokenExpiresAt);1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
initializeAnonymous() 成功后会把 token 写入这个 AdClient 实例。新建实例、关闭页面或刷新页面后,不会自动恢复 token;再次使用同一安装 ID 认证,才能查询同一匿名身份的会话和奖励。
不要每次广告请求都生成安装 ID。这样既破坏恢复能力,也会改变频控身份。若本地存储不可用,应明确处理失败,不应悄悄把每次打开都当作新用户。
业务后端身份
有业务后端时,由后端完成玩家登录校验,再调用广告系统的 /server/client-tokens。前端只接收短期 token。
ts
import { AdClient } from '@ad/client-core';
// /api/ads/client-token 是你自己的业务接口,需要自己实现登录和授权。
// 它不是广告系统已提供的 URL;不要把 server key 放到这里的前端请求里。
async function getClientTokenFromOwnBackend(): Promise<string> {
const response = await fetch('/api/ads/client-token', {
method: 'POST',
credentials: 'same-origin',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({}),
});
if (!response.ok) throw new Error('无法获取广告访问令牌');
const result = (await response.json()) as { token: string; expiresAt: string };
return result.token;
}
const ads = new AdClient({ baseUrl: 'https://ads.example.com/v1' });
ads.setToken(await getClientTokenFromOwnBackend());
const config = await ads.getConfig();
console.log(config.app.deliveryMode);1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
业务后端应从自己的登录会话推导 subjectId,不能直接信任浏览器随意指定一个玩家 ID。业务接口的 CSRF 和认证机制由业务后端负责,上例不提供完整玩家登录实现。
获取配置与展示入口
ts
const config = await ads.getConfig();
const revive = config.placements.find((item) => item.code === 'revive');
if (!revive) {
// 当前身份的应用没有启用该广告位,不显示对应广告入口。
} else {
const offer = revive.type === 'rewarded'
? `${revive.rewardAmount} ${revive.rewardCode}`
: '普通展示';
console.log(revive.name, offer);
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
配置列表包含启用的广告位,不保证该广告位此刻一定有可投素材。load() 仍可能因排期、素材、限额或冷却返回业务错误。
在展示前再次使用 load() 返回的 session.reward 和 session.rules 更新用户看到的奖励与条件。投放级覆盖、后台修改和会话快照可能与先前的配置查询结果不同。
创建会话与幂等键
一次业务操作分配一个创建 key,只有得到成功结果或明确决定开始新的机会时才换 key。网络超时不代表服务端没有创建成功。
ts
import { AdApiError, type AdSession } from '@ad/client-core';
const placementCode = 'daily_bonus';
const pendingKey = `my-game:pending-ad:${appId}:${subjectId}:${placementCode}`;
let requestKey = sessionStorage.getItem(pendingKey);
if (!requestKey) {
requestKey = crypto.randomUUID();
sessionStorage.setItem(pendingKey, requestKey);
}
async function loadThisOpportunity(): Promise<AdSession> {
// 重试这个函数时继续复用 requestKey。
const loaded = await ads.load(placementCode, { idempotencyKey: requestKey! });
sessionStorage.setItem(`my-game:ad-session:${appId}:${subjectId}`, loaded.id);
sessionStorage.removeItem(pendingKey);
return loaded;
}
try {
const loaded = await loadThisOpportunity();
console.log(loaded.id, loaded.rules, loaded.reward);
// 将 loaded 交给真实播放器;此处不能直接发送 complete 或增加金币。
} catch (error) {
if (error instanceof AdApiError && error.code === 'NETWORK_ERROR') {
// 显示“重新加载”按钮,按钮重新调用 loadThisOpportunity()。
// 保留同一 key;不要因为超时生成另一笔观看机会。
} else {
throw error;
}
}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
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
如果不传 idempotencyKey,load() 每次调用都会自动生成新 UUID。因此“再次调用同一行 load 代码”不一定等于重试同一个请求。
服务端 key 的作用域是应用、用户和创建操作。同一 key 改用另一个 placementCode 或 rewardIntentId 会返回 IDEMPOTENCY_CONFLICT。有业务后端的奖励意图也需要绑定相同的用户和广告位。
如果广告位返回 requireRewardIntent: true,必须先由已认证的业务后端创建意图,再把该 rewardIntentId 传入 load()。Player Lab 提供对应输入框;它不会帮客户端绕过业务认证创建意图。Reward 中的 rewardIntentId、businessKey 和 placementCode 可用于展示关联结果,业务后端仍要核对自身对局或权益状态。
确定未创建会话的错误,例如 NO_FILL、FREQUENCY_CAPPED、REWARD_INTENT_REQUIRED,可以结束这次创建操作,让用户重新选择条件。网络中断、超时和结果不确定时保留原 key;不能一律清空再发起新请求。仓库播放器会持久化创建 key 和原请求内容,刷新后继续使用它们。
APP_UNAVAILABLE、SERVER_IDENTITY_REQUIRED 或认证失败可能发生在服务端查找幂等记录之前,因此不能据此删除原 key。Player Lab 的 Retry saved load 始终重发保存的广告位和意图,即使该广告位已从启用列表消失或列表为空;未决创建期间也不会允许 Inspect 历史记录覆盖这次操作。
加载、展示和关闭的顺序
load()取得会话及媒体地址。- 真正加载图片或视频,处理解码失败、网络失败和加载超时。
- 用户主动选择观看后调用
start(session.id)。 - 根据可见性、播放状态和媒体进度发送有序事件。
- 图片或最低时长模式达到条件、完整视频收到真实
ended时,上报相应完成证据。 - 用户关闭时上报
close;查询同一个会话,判断最终奖励资格。 - 按交付模式领取凭证或等待业务后端确认。
开始前取消也应释放会话:
ts
import type { AdSession } from '@ad/client-core';
async function cancelUnstartedSession(session: AdSession): Promise<AdSession> {
if (session.status !== 'CREATED') {
throw new Error('已开始的会话需要使用播放队列上报关闭');
}
return ads.events(session.id, [{
eventId: crypto.randomUUID(),
sequence: 1,
type: 'close',
visible: false,
visibleSeconds: 0,
}]);
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
上例适用于没有发送过其他事件的未开始会话。已经开始的会话需要保留原序列和已有证据,不应重置为 sequence: 1。完整实现见播放与事件。
token 过期后的恢复
服务端 token 当前有效 1 小时。默认不会自动刷新;配置 AdClientOptions.refreshToken 后,认证请求遇到 401 会共享一次刷新,并用原 body、原幂等键重试一次。匿名认证自身不触发回调,第二次 401 不会无限刷新。
下例创建一个可刷新匿名 token 的客户端。安装 ID 和预期用户固定在闭包中,刷新不改变身份:
ts
import { AdClient } from '@ad/client-core';
export async function connectAnonymous(appId: string, persistentInstallationId: string) {
let expectedSubject = '';
const ads = new AdClient({
baseUrl: '/v1',
refreshToken: async () => {
const renewal = new AdClient({ baseUrl: '/v1' });
const identity = await renewal.initializeAnonymous(appId, persistentInstallationId);
if (identity.subjectId !== expectedSubject) throw new Error('刷新不能改变广告用户身份');
return identity.token;
},
});
const identity = await ads.initializeAnonymous(appId, persistentInstallationId);
expectedSubject = identity.subjectId;
return { ads, identity, config: await ads.getConfig() };
}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
业务模式的回调应访问自己的已认证业务接口获取 token,不能包含 X-App-Key。需要人工粘贴 token 时,Player Lab 允许待传队列存在的情况下重新连接,但会先用 API 验证 token,再核对应用和用户一致;验证失败不会替换原队列。还有待完成任务时,切换到另一个应用或用户会被拒绝。
播放器只持久化身份命名空间、创建操作、会话和事件,不保存 token。刷新页面后先重新认证同一身份,再补传原事件。代码中的单飞刷新不等于磁盘持久化,也不保证业务服务在退出登录后仍能签发 token。
错误分流
| 错误 | 客户端建议 |
|---|---|
NO_FILL | 当前无可投广告,显示“暂时没有广告”,稍后由用户重试 |
FREQUENCY_CAPPED | 达到日限额或仍在冷却,不立即循环重试 |
SESSION_ACTIVE | 找到并结束已有会话,或查询其过期状态 |
UNAUTHORIZED | 重新取得同一身份的 token;只重试有明确幂等保证的操作 |
SERVER_IDENTITY_REQUIRED | 应用要求业务后端身份,不能继续用匿名模式 |
REWARD_INTENT_REQUIRED | 从业务后端获取对应意图,不要在客户端伪造业务关联 |
AD_UNAVAILABLE | 投放、素材或广告位在开始前被停用;关闭原会话后再选广告 |
SESSION_EXPIRED | 当前会话或补证窗口已过期,查询结果并结束当前流程 |
REWARD_PENDING | 资格尚未成立,保留会话并查询,不直接发奖 |
REWARD_EXPIRED | 首次领取时限已过;不自行创建另一笔补发 |
DELIVERY_MODE_MISMATCH | 当前模式不允许客户端 claim,应交给业务后端 |
IDEMPOTENCY_CONFLICT | 同一 key 对应的内容变了,修复业务操作与 key 的映射 |
NETWORK_ERROR | 结果不确定,保留原 key、事件 ID、会话和奖励 ID,提供重试 |
EVENT_CONFLICT | 同一事件 ID 或序号的内容发生变化;保留原记录排查,不能换 ID 规避 |
INVALID_EVENT_TIMING | 核对 start 后的单调计时和原事件重传,不能用本地墙钟拼接补传时间 |
INVALID_EVENT_TIMELINE | 同一会话的显式 elapsed 必须随序号非递减;保留原证据检查采样基线 |
应把 requestId 连同 sessionId 和 grantId 用于故障定位,但不要记录 token、server key 或整份环境变量。
已实现与需要自己完成的部分
参考客户端提供请求、超时和统一错误对象。应用仍需处理实际媒体渲染、前后台生命周期、事件队列、重试节奏、状态持久化、用户取消和资产兑现。
当前仓库播放器使用 localStorage 持久化每个应用/用户的创建操作、会话、事件序号和原始待传事件,通过 Web Locks 限制同一身份只有一个标签页写入。刷新后补传已有证据,不续算离线时间,也不自动续播原媒体。若只复制 AdClient,这些存储和生命周期能力需要自己实现。
普通事件积压达到 300 条时播放器暂停继续累计,另预留完成/关闭事件容量,不截掉队尾。只有收到 SESSION_EXPIRED 并从服务端确认同一会话已结束后,才把整份旧队列归档并释放当前操作;临时断网、401 和确认失败均保留待传证据。归档不会补发奖励,仍以 API 返回资格为准。
继续阅读:播放与事件、奖励交付、TypeScript 客户端参考。
仓库客户端回归可运行 pnpm test:client,覆盖并发刷新、原请求保持、事件持久化、跨身份隔离、队列满、过期归档和全量历史翻页。它们使用内存存储/模拟传输,不替代实际浏览器媒体、IndexedDB 和断网验收。