外观
TypeScript 客户端参考
可直接下载与当前仓库对应的 client-core.ts,保存为 src/lib/ad-client.ts。它是私有工作区包的源码副本,尚未发布公共 npm;下载不包含播放器、事件调度或业务资产服务。
本文对应当前 packages/client-core/src/index.ts 的实现。工作区包名为 @ad/client-core,版本 0.1.0、private: true,直接导出 TypeScript 源码;尚未发布到 npm。引入方式见客户端接入。
导出内容
ts
import {
AdClient,
AdApiError,
type DeliveryMode,
type Reward,
type AdSession,
type Placement,
type ClientConfig,
type AdEvent,
type AdClientOptions,
type RewardPage,
} from '@ad/client-core';1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
这些接口是 TypeScript 编译期类型。HTTP 客户端不会在运行时逐字段验证响应,也不会把服务端状态字符串转换为封闭枚举。
构造器
ts
new AdClient(options?: {
baseUrl?: string;
timeoutMs?: number;
token?: string;
refreshToken?: () => Promise<string>;
})1
2
3
4
5
6
2
3
4
5
6
| 参数 | 默认值 | 说明 |
|---|---|---|
baseUrl | /v1 | API 根地址,包含版本前缀;末尾一个 / 会被移除 |
timeoutMs | 12000 | 每次请求的超时毫秒数;超时中止当前 fetch |
token | 空字符串 | 已有短期客户端 token;不是应用 server key |
refreshToken | 未配置 | 认证请求收到 401 时获取同一应用、同一用户的新 token;并发请求共享一次刷新 |
ts
const ads = new AdClient({
baseUrl: 'https://ads.example.com/v1',
timeoutMs: 12_000,
token: shortLivedClientToken,
});1
2
3
4
5
2
3
4
5
超时不代表服务端没有处理成功。对创建、事件、领取的重试应遵循对应幂等规则。
配置 refreshToken 后,每个认证请求最多进行一次刷新后的重试。请求体在首次发送前序列化,重试沿用完全相同的 body、事件证据和创建幂等键;第二次 401 直接返回错误。网络错误不会因此自动重试,匿名认证接口自身也不会触发此回调。回调必须返回同一身份的短期 token,不能在失败时悄悄切换账号。
ts
const ads = new AdClient({
baseUrl: '/v1',
refreshToken: async () => {
// 自己的业务接口:用已验证的登录身份换取新 token。
const response = await fetch('/api/ads/client-token', { method: 'POST', credentials: 'same-origin' });
if (!response.ok) throw new Error('无法刷新广告令牌');
const result = await response.json() as { token: string };
return result.token;
},
});1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
方法总览
| 方法 | HTTP 请求 | 返回 |
|---|---|---|
setToken(token) | 不发请求 | void |
initializeAnonymous(appId, installationId) | POST /client/anonymous-sessions | token、subjectId、expiresAt |
getConfig() | GET /client/config | ClientConfig |
load(placementCode, options?) | POST /client/ad-sessions | AdSession |
start(sessionId) | POST /client/ad-sessions/:id/start | AdSession |
events(sessionId, events) | POST /client/ad-sessions/:id/events | AdSession |
getSession(sessionId) | GET /client/ad-sessions/:id | AdSession |
getRewards() | GET /client/rewards | Reward[] |
getRewardsPage({ after }?) | GET /client/rewards?after=... | RewardPage |
claim(rewardId, idempotencyKey?) | POST /client/rewards/:id/claim | Reward |
reportApplied(rewardId) | POST /client/rewards/:id/reported-applied | unknown,当前为记录结果对象 |
表中路径都追加到 baseUrl,例如实际请求为 /v1/client/config。路径参数会经过 encodeURIComponent。
setToken
ts
setToken(token: string): void1
替换实例内存中的 token。不验证签名、不检查过期、不发网络请求,也不持久化。下一次需要认证的调用将携带该 token,由服务端决定是否有效。
ts
ads.setToken(await obtainTokenFromOwnBackend());
const config = await ads.getConfig();1
2
2
obtainTokenFromOwnBackend 是接入应用自己实现的函数。客户端不得持有 X-App-Key。
initializeAnonymous
ts
initializeAnonymous(
appId: string,
installationId: string,
): Promise<{
token: string;
subjectId: string;
expiresAt: string;
}>1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
appId是公开 App ID,不是数据库内部应用 ID。installationId的服务端长度限制为 8–128 字符,应跨重启保持稳定。- 此请求不携带实例原有的 Bearer token。
- 成功后自动更新实例 token。
- 仅允许
client_claim应用;其他模式返回SERVER_IDENTITY_REQUIRED。 - 当前 token 有效期为 1 小时,
expiresAt为 ISO UTC 字符串。
ts
const identity = await ads.initializeAnonymous('app_demo', persistentInstallationId);
console.log(identity.subjectId, identity.expiresAt);1
2
2
getConfig
ts
getConfig(): Promise<ClientConfig>1
返回当前 token 所属应用及启用的广告位。没有应用 ID 参数,不能使用这个方法切换到另一应用。
ts
const { app, placements } = await ads.getConfig();
const target = placements.find((placement) => placement.code === 'daily_bonus');1
2
2
配置中包含广告位默认观看条件;投放可覆盖这些字段,因此真正播放时使用会话的 rules。有配置不代表一定有可填充广告。
load
ts
load(
placementCode: string,
options?: {
idempotencyKey?: string;
rewardIntentId?: string;
},
): Promise<AdSession>1
2
3
4
5
6
7
2
3
4
5
6
7
| 参数 | 说明 |
|---|---|
placementCode | 当前应用内的广告位编码,服务端长度 1–64 字符 |
idempotencyKey | 同一次创建操作的稳定标识;服务端要求非空、最多 128 字符 |
rewardIntentId | 业务后端创建的意图 ID;只能由对应应用、用户和广告位使用 |
广告位 requireRewardIntent=true 时必须提交匹配的 rewardIntentId,否则返回 REWARD_INTENT_REQUIRED。这类广告位需要业务后端身份和服务端交付;客户端不能自行生成可信意图或奖励数量。
不传 key 时,方法内部每次生成一个新 UUID。需要重试创建请求时,应在外部先保存 key:
ts
const key = crypto.randomUUID();
const session = await ads.load('daily_bonus', { idempotencyKey: key });
// 网络失败时重试同一 placementCode 和同一 key,不能重新生成 key。1
2
3
2
3
创建请求体只包含广告位编码及可选意图 ID,不包含客户端自己指定的奖励数量。成功返回会话快照;此时状态通常为 CREATED,还没有开始播放计时。
start
ts
start(sessionId: string): Promise<AdSession>1
在媒体加载成功、准备真实展示时调用。初次成功设置开始时间、播放与证据截止时间,并计算展示及冷却。若会话此前已经开始,重复调用返回现有会话,不重新开始计时。
ts
const started = await ads.start(session.id);
if (started.status !== 'SHOWING') {
// 可能是已结束会话的重试结果,不能仅因 HTTP 成功就重新播放。
throw new Error('该会话当前不能展示');
}1
2
3
4
5
2
3
4
5
未开始会话创建后 5 分钟失效。素材或投放在开始前被停用时可能返回 AD_UNAVAILABLE。
events
ts
events(sessionId: string, events: AdEvent[]): Promise<AdSession>1
服务端每次接收 1–20 条事件。当前参考播放器每批最多发送 10 条,并保证同一会话只有一个发送队列。
ts
interface AdEvent {
eventId: string;
type: 'heartbeat' | 'complete' | 'close' | 'click';
sequence: number;
visible: boolean;
positionSeconds?: number;
visibleSeconds: number;
elapsedSeconds?: number;
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
| 字段 | 要求 |
|---|---|
eventId | 1–128 字符;同一事件重试必须保持不变 |
type | heartbeat 播放观察、complete 完成声明、close 关闭、click 点击 |
sequence | 会话内正整数、按产生顺序递增;重试不产生新序号 |
visible | 生成事件时是否仍在真实前台展示 |
visibleSeconds | 本次会话累计有效可见时长,有限非负数,当前上限 36000 秒 |
positionSeconds | 视频当前真实播放位置,有限非负数;图片省略 |
elapsedSeconds | 从收到 start 成功响应后开始、用 performance.now() 单调累计的秒数;包括暂停/后台间隔,重试保留原值 |
下面只展示上报结构,measuredEvent 必须由真实媒体测量代码产生:
ts
const updated = await ads.events(session.id, [measuredEvent]);
if (updated.reward?.eligibility === 'ELIGIBLE') {
// 展示“奖励已就绪”,后续按 deliveryMode 交付。
}1
2
3
4
2
3
4
不得使用固定延时后构造 visibleSeconds 的方式代替真实观看。完整测量与队列示例见播放与事件。
服务端保存事件并按连续序号重放;乱序到达可先保存,但存在序号缺口时不会凭后续证据新授予资格。相同事件 ID 或序号对应不同内容返回 EVENT_CONFLICT,每会话最多 2048 条。仍应串行发送,避免主动制造缺口。lastSequence 表示连续处理到的位置,不一定是已入库存储的最大序号。
补传可以在展示截止后、证据截止前上传原先测量并保存的事件。新增 elapsedSeconds 用于说明真实采样位于展示窗口内;它不得主张超过服务端首次接收时已经过的时间,不能在重试时改成当前时刻。旧客户端省略该字段时使用保守的接收时间边界,不保证恢复全部离线观看时长。
开始前只接受全为 close 的事件批次,用于取消未开始的会话;其他事件会返回 SESSION_NOT_STARTED。
getSession
ts
getSession(sessionId: string): Promise<AdSession>1
查询当前身份自己的会话。适合网络结果不明、关闭后确认、页面重新打开或奖励状态刷新。
ts
const current = await ads.getSession(savedSessionId);
console.log(current.status, current.reward?.eligibility, current.reward?.deliveryStatus);1
2
2
这个接口可能触发该用户已过期会话的清理。它不会把未上报的播放事实补进服务端,也不会自动续播。
getRewards
ts
getRewards(): Promise<Reward[]>1
这个兼容方法读取第一页并解包 items,返回最近最多 100 条。需要完整历史时,使用下面的 getRewardsPage() 循环。
ts
const rewards = await ads.getRewards();
const recoverable = rewards.filter(
(reward) => reward.deliveryMode === 'client_claim' && reward.deliveryStatus === 'CLAIMED',
);1
2
3
4
2
3
4
它不能作为无限期资产流水或完整历史备份。业务后端需要增量同步时,使用对应 /server/rewards 契约;客户端历史翻页与业务后端增量同步是两套语义。
getRewardsPage
ts
getRewardsPage(options?: { after?: string }): Promise<RewardPage>
interface RewardPage {
items: Reward[];
hasMore: boolean;
nextCursor: string | null;
}1
2
3
4
5
6
7
2
3
4
5
6
7
每页最多 100 条,按 createdAt / id 降序翻阅历史。首次不传 after;后续把上一页的 nextCursor 原样传回。游标有签名、限定当前应用和用户、有效期 7 天,不可跨身份复用。每次完整恢复从第一页开始,按 grantId 去重应用,不把历史游标当作增量同步水位。
ts
let after: string | undefined;
do {
const page = await ads.getRewardsPage({ after });
for (const reward of page.items) console.log(reward.grantId, reward.deliveryStatus);
if (!page.hasMore) break;
if (!page.nextCursor) throw new Error('分页响应缺少游标');
after = page.nextCursor;
} while (true);1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
claim
ts
claim(rewardId: string, idempotencyKey?: string): Promise<Reward>1
可选 key 默认是 claim: 加奖励 ID,客户端会发送 Idempotency-Key 请求头。当前服务端 claim 控制器不读取这个头,实际幂等由同一奖励记录、稳定 grantId 和数据库事务保证。 更换 claim key 不会让同一奖励再次产生一笔交付。
ts
const claim = await ads.claim(reward.id);
console.log(claim.grantId, claim.code, claim.amount, claim.deliveryStatus);1
2
2
- 仅允许
client_claim模式。 - 尚未成立资格时返回
REWARD_PENDING。 - 资格成立后,首次领取当前限制为 24 小时内。
- 已经
CLAIMED的同一奖励再次调用,会返回原结果;不会因为首次领取期限已过而阻止结果恢复。 - 领取成功不自动修改游戏余额。应用仍需以
grantId在自己的存储中防重兑现。
reportApplied
ts
reportApplied(rewardId: string): Promise<unknown>1
仅对已经 CLAIMED 的客户端模式奖励有效。当前响应:
json
{
"recorded": true,
"verified": false
}1
2
3
4
2
3
4
这是客户端“已应用”的声明记录,不会把交付状态变为 FULFILLED。如果声明请求失败,不应撤销本地成功入账,也不能以“再发一笔奖励”解决;在恢复同一 grant 后可以再次声明。
数据类型
Reward
ts
type DeliveryMode = 'client_claim' | 'server_pull' | 'server_webhook';
interface Reward {
id: string;
grantId: string;
sessionId?: string;
code: string;
type: string;
amount: number;
eligibility: string;
deliveryStatus: string;
deliveryMode: DeliveryMode;
rewardIntentId?: string | null;
businessKey?: string | null;
placementCode?: string;
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
实际 API 还可能返回 reason、createdAt、expiresAt,当前客户端类型尚未声明这些补充字段。amount 当前使用安全整数范围内的一项奖励数量;客户端不应自行把它转换成现金。
AdSession
ts
interface AdSession {
id: string;
status: 'CREATED' | 'SHOWING' | 'ENDED';
endReason?: string | null;
creative: {
id: string;
kind: 'image' | 'video';
url: string;
width: number;
height: number;
durationSeconds?: number | null;
clickUrl?: string | null;
};
rules: {
imageSeconds: number;
videoMode: 'complete' | 'minimum';
videoSeconds: number;
};
reward: Reward | null;
createdAt: string;
startedAt?: string | null;
showDeadline?: string | null;
evidenceDeadline?: string | null;
lastSequence?: number;
creditedSeconds?: number;
}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
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
普通展示的 reward 为 null。creditedSeconds 表示服务端累计认可时长,不等于客户端自测秒数。lastSequence 是服务端已连续处理的序号;收到它不代表本地可以重新编号已有待发事件。
ClientConfig 与 Placement
ts
interface Placement {
code: string;
name: string;
type: 'rewarded' | 'display';
rewardCode: string;
rewardAmount: number;
imageSeconds: number;
videoMode: 'complete' | 'minimum';
videoSeconds: number;
cooldownSeconds: number;
dailyLimit: number;
requireRewardIntent: boolean;
}
interface ClientConfig {
app: {
publicId: string;
name: string;
deliveryMode: DeliveryMode;
};
placements: Placement[];
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
AdApiError
ts
class AdApiError extends Error {
readonly code: string;
readonly status: number;
readonly requestId?: string;
}1
2
3
4
5
2
3
4
5
| 情况 | code / status |
|---|---|
| 服务端返回结构化业务错误 | 采用服务端 code、HTTP 状态和 body 中的 requestId |
| HTTP 非成功且无法解析业务错误 | HTTP_ERROR,保留 HTTP 状态 |
| HTTP 成功但没有可解析的 JSON,且不是 204 | INVALID_RESPONSE,保留 HTTP 状态 |
| 网络失败或请求超时 | NETWORK_ERROR,status=0 |
ts
try {
await ads.getConfig();
} catch (error) {
if (error instanceof AdApiError) {
console.error({ code: error.code, status: error.status, requestId: error.requestId });
} else {
throw error;
}
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
当前不提供的功能
本类没有 show()、dispose()、onRewardEarned 回调、全局网络重试、事件落盘、离线奖励、原生媒体控件或第三方广告 SDK。token 刷新仅在调用者提供 refreshToken 回调时启用。不要把早期规划中的接口名字当作现有方法调用。
仓库参考播放器额外实现按身份隔离的持久事件队列、匿名 token 刷新、手动同身份替换 token、页面可见性和 IndexedDB 演示库存;这些不是 AdClient 自身的存储功能。详见播放与事件;教学版接入组合见客户端示例。