@wovoon/polaris 0.6.3 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/PROTOCOL.md +8 -0
- package/dist/ads.d.ts +77 -0
- package/dist/ads.js +228 -0
- package/dist/client.d.ts +2 -0
- package/dist/client.js +8 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1 -0
- package/dist/protocol.d.ts +1 -1
- package/dist/protocol.js +1 -1
- package/docs/ads.md +78 -0
- package/docs/index.md +1 -1
- package/docs/manifest.md +3 -0
- package/docs/quickstart.md +21 -12
- package/docs/recipes/rewarded-placement.md +88 -0
- package/docs/rewarded-ads.md +82 -0
- package/docs/sdk.md +6 -1
- package/llms.txt +3 -0
- package/package.json +2 -2
package/PROTOCOL.md
CHANGED
|
@@ -43,6 +43,7 @@
|
|
|
43
43
|
| `collection:<name>` | 数据集合:带权限规则(读 WORLD/PLAYER,写 OWNER/SERVER)的 JSON 文档 CRUD 与排序查询 | 已实现 |
|
|
44
44
|
| `function` | 云函数:服务端权威逻辑(受限 Node 沙箱) | 已实现 |
|
|
45
45
|
| `room` | 房间实时通道:WebSocket 消息中继(多人在线) | 已实现 |
|
|
46
|
+
| `ads` | 可选作品广告容器:宿主按作品租约、平台配置和格式选择已授权广告源;无源立即跳过,不影响游戏 | SDK 0.8.0;Android 横幅/插屏/服务端校验激励,网页无源跳过 |
|
|
46
47
|
|
|
47
48
|
- 未知顶层字段、非法能力名、非法 JSON、不支持协议版本 → **上传扫描直接拒绝**,报错信息包含修复指引;
|
|
48
49
|
- 能力声明将在对应服务上线后成为**调用前置条件**(未声明则接口拒绝)。
|
|
@@ -55,6 +56,13 @@
|
|
|
55
56
|
|
|
56
57
|
## 4. 能力契约(Capability APIs)
|
|
57
58
|
|
|
59
|
+
作品广告通过 `WovoonPolaris.ads.capabilities()`、`show()`、`mountBanner()` 调用,
|
|
60
|
+
独立于 `identity`。宿主处理权限、聚合位、频控、加载与关闭;作品仅提供场景名和
|
|
61
|
+
横幅容器,不提供广告源或价格。网页未授权时返回 `unavailable`,不得回退到模拟广告。
|
|
62
|
+
激励广告必须配置服务端验证与作品奖励规则,只信任服务端账本回执。缺配置时 `rewarded` 为 `false`。
|
|
63
|
+
`rewardStatus / rewardBalances / consumeReward` 用于查询与幂等使用作品奖励,见 [激励广告](docs/rewarded-ads.md);开屏由 App 管理。
|
|
64
|
+
完整接口、结果和暂停恢复约定见 [作品广告容器](docs/ads.md)。
|
|
65
|
+
|
|
58
66
|
协议 1 的能力 API 面由 `@wovoon/polaris` SDK(本仓库)承载,数据形状:
|
|
59
67
|
|
|
60
68
|
- `identity`:`POST /api/cloud/session` → `{appId, playerId, loggedIn, displayName, avatarUrl}`;
|
package/dist/ads.d.ts
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/** Optional host capability. Browsers and older/iOS hosts without an approved source skip immediately. */
|
|
2
|
+
export type PolarisAdFormat = "banner" | "interstitial" | "rewarded";
|
|
3
|
+
export type PolarisAdStatus = "shown" | "closed" | "unavailable" | "no_fill" | "busy" | "frequency_capped" | "cancelled" | "error";
|
|
4
|
+
export interface PolarisRewardReceipt {
|
|
5
|
+
requestId: string;
|
|
6
|
+
status: "pending" | "granted" | "expired";
|
|
7
|
+
rewardKey: string;
|
|
8
|
+
rewardName: string;
|
|
9
|
+
amount: number;
|
|
10
|
+
grantedAt: string | null;
|
|
11
|
+
}
|
|
12
|
+
export interface PolarisRewardBalance {
|
|
13
|
+
rewardKey: string;
|
|
14
|
+
balance: number;
|
|
15
|
+
}
|
|
16
|
+
export interface PolarisRewardSpend {
|
|
17
|
+
clientId: string;
|
|
18
|
+
rewardKey: string;
|
|
19
|
+
amount: number;
|
|
20
|
+
balanceAfter: number;
|
|
21
|
+
}
|
|
22
|
+
export interface PolarisAdResult {
|
|
23
|
+
status: PolarisAdStatus;
|
|
24
|
+
reason?: string;
|
|
25
|
+
requestId?: string;
|
|
26
|
+
rewarded: boolean;
|
|
27
|
+
reward?: PolarisRewardReceipt;
|
|
28
|
+
}
|
|
29
|
+
export type PolarisRewardRequest = (action: "status" | "balances" | "consume", body: object) => Promise<unknown>;
|
|
30
|
+
export interface PolarisAdCapabilities {
|
|
31
|
+
surface: "android" | "web";
|
|
32
|
+
banner: boolean;
|
|
33
|
+
interstitial: boolean;
|
|
34
|
+
rewarded: boolean;
|
|
35
|
+
reason?: string;
|
|
36
|
+
}
|
|
37
|
+
export interface PolarisAdOptions {
|
|
38
|
+
/** Stable scene name, not a network ad-unit ID. */
|
|
39
|
+
placement: string;
|
|
40
|
+
onPause?: () => void;
|
|
41
|
+
onResume?: () => void;
|
|
42
|
+
}
|
|
43
|
+
export interface PolarisBanner {
|
|
44
|
+
ready: Promise<PolarisAdResult>;
|
|
45
|
+
closed: Promise<PolarisAdResult>;
|
|
46
|
+
destroy(): void;
|
|
47
|
+
}
|
|
48
|
+
export declare class PolarisAds {
|
|
49
|
+
private readonly host;
|
|
50
|
+
private readonly rewardRequest?;
|
|
51
|
+
private readonly releases;
|
|
52
|
+
private generation;
|
|
53
|
+
constructor(host?: typeof globalThis, rewardRequest?: PolarisRewardRequest | undefined);
|
|
54
|
+
private bridge;
|
|
55
|
+
capabilities(): Promise<PolarisAdCapabilities>;
|
|
56
|
+
show(options: PolarisAdOptions & {
|
|
57
|
+
format: "interstitial" | "rewarded";
|
|
58
|
+
}): Promise<PolarisAdResult>;
|
|
59
|
+
/** Query after a delayed callback, reconnect or reload. Reading a receipt never grants it again. */
|
|
60
|
+
rewardStatus(requestId: string): Promise<PolarisRewardReceipt>;
|
|
61
|
+
/** Durable, work-scoped virtual balances are available on web as well as Android. */
|
|
62
|
+
rewardBalances(): Promise<PolarisRewardBalance[]>;
|
|
63
|
+
/** Keep clientId for retries after uncertain network results. Never generate a new ID for a retry. */
|
|
64
|
+
consumeReward(input: {
|
|
65
|
+
clientId: string;
|
|
66
|
+
rewardKey: string;
|
|
67
|
+
amount: number;
|
|
68
|
+
}): Promise<PolarisRewardSpend>;
|
|
69
|
+
private queryReward;
|
|
70
|
+
mountBanner(container: HTMLElement, options: Pick<PolarisAdOptions, "placement">): PolarisBanner;
|
|
71
|
+
/** Cancel outstanding requests when a game scene/client is replaced. */
|
|
72
|
+
dispose(): void;
|
|
73
|
+
private validPlacement;
|
|
74
|
+
private result;
|
|
75
|
+
private finished;
|
|
76
|
+
private open;
|
|
77
|
+
}
|
package/dist/ads.js
ADDED
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
export class PolarisAds {
|
|
2
|
+
constructor(host = globalThis, rewardRequest) {
|
|
3
|
+
this.host = host;
|
|
4
|
+
this.rewardRequest = rewardRequest;
|
|
5
|
+
this.releases = new Set();
|
|
6
|
+
this.generation = 0;
|
|
7
|
+
}
|
|
8
|
+
bridge() {
|
|
9
|
+
const bridge = this.host.WovoonNativeAds;
|
|
10
|
+
return bridge && typeof bridge.postMessage === "function" &&
|
|
11
|
+
typeof bridge.addEventListener === "function" && typeof bridge.removeEventListener === "function" ? bridge : undefined;
|
|
12
|
+
}
|
|
13
|
+
async capabilities() {
|
|
14
|
+
if (!this.bridge())
|
|
15
|
+
return { surface: "web", banner: false, interstitial: false, rewarded: false, reason: "NO_AUTHORIZED_SOURCE" };
|
|
16
|
+
const response = await this.open("capabilities", {}).ready;
|
|
17
|
+
const value = response;
|
|
18
|
+
return { surface: "android", banner: value.banner === true, interstitial: value.interstitial === true,
|
|
19
|
+
rewarded: !!this.rewardRequest && value.rewarded === true && value.rewardProtocol === 1,
|
|
20
|
+
...(value.reason ? { reason: value.reason } : {}) };
|
|
21
|
+
}
|
|
22
|
+
show(options) {
|
|
23
|
+
if (!options || !["interstitial", "rewarded"].includes(options.format) || !this.validPlacement(options.placement)) {
|
|
24
|
+
return Promise.resolve(this.result("error", "INVALID_ARGUMENT"));
|
|
25
|
+
}
|
|
26
|
+
const generation = this.generation;
|
|
27
|
+
return this.open("show", { format: options.format, placement: options.placement }, options).closed.then(async (result) => {
|
|
28
|
+
if (generation !== this.generation)
|
|
29
|
+
return this.result("cancelled");
|
|
30
|
+
if (options.format !== "rewarded" || !result.requestId || result.status !== "closed")
|
|
31
|
+
return result;
|
|
32
|
+
try {
|
|
33
|
+
const reward = await this.rewardStatus(result.requestId);
|
|
34
|
+
if (generation !== this.generation)
|
|
35
|
+
return this.result("cancelled");
|
|
36
|
+
return { ...result, rewarded: reward.status === "granted", reward,
|
|
37
|
+
...(reward.status === "pending" ? { reason: "REWARD_PENDING" } : {}) };
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
if (generation !== this.generation)
|
|
41
|
+
return this.result("cancelled");
|
|
42
|
+
// Preserve the request ID for recovery. An unavailable query is never reported as a missing reward.
|
|
43
|
+
return { ...result, rewarded: false, reason: "REWARD_STATUS_UNAVAILABLE" };
|
|
44
|
+
}
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
/** Query after a delayed callback, reconnect or reload. Reading a receipt never grants it again. */
|
|
48
|
+
async rewardStatus(requestId) {
|
|
49
|
+
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(requestId))
|
|
50
|
+
throw new Error("INVALID_REWARD_REQUEST");
|
|
51
|
+
const value = await this.queryReward("status", { requestId });
|
|
52
|
+
if (!value || value.requestId !== requestId || !["pending", "granted", "expired"].includes(value.status) ||
|
|
53
|
+
!this.validPlacement(value.rewardKey) || typeof value.rewardName !== "string" ||
|
|
54
|
+
!Number.isInteger(value.amount) || value.amount < 1 || value.amount > 10000 ||
|
|
55
|
+
(value.status === "granted" && (typeof value.grantedAt !== "string" || !Number.isFinite(Date.parse(value.grantedAt))))) {
|
|
56
|
+
throw new Error("INVALID_REWARD_RECEIPT");
|
|
57
|
+
}
|
|
58
|
+
return value;
|
|
59
|
+
}
|
|
60
|
+
/** Durable, work-scoped virtual balances are available on web as well as Android. */
|
|
61
|
+
async rewardBalances() {
|
|
62
|
+
const value = await this.queryReward("balances", {});
|
|
63
|
+
if (!Array.isArray(value) || value.some(item => !item || !this.validPlacement(item.rewardKey) ||
|
|
64
|
+
!Number.isSafeInteger(item.balance) || item.balance < 0))
|
|
65
|
+
throw new Error("INVALID_REWARD_BALANCE");
|
|
66
|
+
return value;
|
|
67
|
+
}
|
|
68
|
+
/** Keep clientId for retries after uncertain network results. Never generate a new ID for a retry. */
|
|
69
|
+
async consumeReward(input) {
|
|
70
|
+
if (!input || !/^[A-Za-z0-9_-]{1,96}$/.test(input.clientId) || !this.validPlacement(input.rewardKey) ||
|
|
71
|
+
!Number.isInteger(input.amount) || input.amount < 1 || input.amount > 10000)
|
|
72
|
+
throw new Error("INVALID_REWARD_CONSUME");
|
|
73
|
+
const value = await this.queryReward("consume", input);
|
|
74
|
+
if (!value || value.clientId !== input.clientId || value.rewardKey !== input.rewardKey || value.amount !== input.amount ||
|
|
75
|
+
!Number.isSafeInteger(value.balanceAfter) || value.balanceAfter < 0)
|
|
76
|
+
throw new Error("INVALID_REWARD_SPEND");
|
|
77
|
+
return value;
|
|
78
|
+
}
|
|
79
|
+
async queryReward(action, input) {
|
|
80
|
+
if (!this.rewardRequest)
|
|
81
|
+
throw new Error("REWARD_API_UNAVAILABLE");
|
|
82
|
+
let timer;
|
|
83
|
+
const generation = this.generation;
|
|
84
|
+
try {
|
|
85
|
+
const result = await Promise.race([this.rewardRequest(action, input), new Promise((_, reject) => {
|
|
86
|
+
timer = this.host.setTimeout(() => reject(new Error("REWARD_QUERY_TIMEOUT")), 8000);
|
|
87
|
+
})]);
|
|
88
|
+
if (generation !== this.generation)
|
|
89
|
+
throw new Error("REWARD_CONTEXT_CHANGED");
|
|
90
|
+
return result;
|
|
91
|
+
}
|
|
92
|
+
finally {
|
|
93
|
+
if (timer !== undefined)
|
|
94
|
+
this.host.clearTimeout(timer);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
mountBanner(container, options) {
|
|
98
|
+
// No DOM mutation, network request, timer or empty placeholder when no source exists.
|
|
99
|
+
if (!this.bridge())
|
|
100
|
+
return this.finished(this.result("unavailable", "NO_AUTHORIZED_SOURCE"));
|
|
101
|
+
if (!container || typeof container.getBoundingClientRect !== "function" || !this.validPlacement(options?.placement)) {
|
|
102
|
+
return this.finished(this.result("error", "INVALID_ARGUMENT"));
|
|
103
|
+
}
|
|
104
|
+
const rect = () => {
|
|
105
|
+
const b = container.getBoundingClientRect();
|
|
106
|
+
const style = this.host.getComputedStyle(container);
|
|
107
|
+
const visible = container.isConnected && this.host.document.visibilityState === "visible" &&
|
|
108
|
+
style.visibility === "visible" && style.display !== "none" && Number(style.opacity) > 0 &&
|
|
109
|
+
b.top >= 0 && b.left >= 0 && b.bottom <= this.host.innerHeight && b.right <= this.host.innerWidth;
|
|
110
|
+
return { x: b.left, y: b.top, width: b.width, height: b.height,
|
|
111
|
+
viewportWidth: this.host.innerWidth, viewportHeight: this.host.innerHeight, visible };
|
|
112
|
+
};
|
|
113
|
+
const first = rect();
|
|
114
|
+
if (!first.visible || first.width < 320 || first.height < 50) {
|
|
115
|
+
return this.finished(this.result("unavailable", "CONTAINER_NOT_VISIBLE"));
|
|
116
|
+
}
|
|
117
|
+
const handle = this.open("show", { format: "banner", placement: options.placement, rect: first });
|
|
118
|
+
const update = () => handle.send("resize", { rect: rect() });
|
|
119
|
+
// Native expires the view if geometry stops arriving (navigation, frozen/hidden document).
|
|
120
|
+
const timer = this.host.setInterval(update, 500);
|
|
121
|
+
this.host.addEventListener("scroll", update, true);
|
|
122
|
+
this.host.addEventListener("resize", update);
|
|
123
|
+
this.host.document.addEventListener("visibilitychange", update);
|
|
124
|
+
void handle.closed.then(() => {
|
|
125
|
+
this.host.clearInterval(timer);
|
|
126
|
+
this.host.removeEventListener("scroll", update, true);
|
|
127
|
+
this.host.removeEventListener("resize", update);
|
|
128
|
+
this.host.document.removeEventListener("visibilitychange", update);
|
|
129
|
+
});
|
|
130
|
+
return handle;
|
|
131
|
+
}
|
|
132
|
+
/** Cancel outstanding requests when a game scene/client is replaced. */
|
|
133
|
+
dispose() { this.generation++; for (const release of [...this.releases])
|
|
134
|
+
release(); }
|
|
135
|
+
validPlacement(value) { return typeof value === "string" && /^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(value); }
|
|
136
|
+
result(status, reason) { return { status, ...(reason ? { reason } : {}), rewarded: false }; }
|
|
137
|
+
finished(value) { return { ready: Promise.resolve(value), closed: Promise.resolve(value), destroy() { }, send(_action, _params) { } }; }
|
|
138
|
+
open(action, params, options) {
|
|
139
|
+
const bridge = this.bridge();
|
|
140
|
+
if (!bridge)
|
|
141
|
+
return this.finished(this.result("unavailable", "NO_AUTHORIZED_SOURCE"));
|
|
142
|
+
const id = `ad-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
|
|
143
|
+
let resolveReady;
|
|
144
|
+
let resolveClosed;
|
|
145
|
+
const ready = new Promise(r => { resolveReady = r; });
|
|
146
|
+
const closed = new Promise(r => { resolveClosed = r; });
|
|
147
|
+
let done = false, paused = false;
|
|
148
|
+
const callback = (fn) => { try {
|
|
149
|
+
fn?.();
|
|
150
|
+
}
|
|
151
|
+
catch { /* game callbacks cannot break cleanup */ } };
|
|
152
|
+
const send = (nextAction, value = {}) => {
|
|
153
|
+
if (!done)
|
|
154
|
+
bridge.postMessage(JSON.stringify({ channel: "wovoon:ads:v1", id, action: nextAction, ...value }));
|
|
155
|
+
};
|
|
156
|
+
const finish = (result) => {
|
|
157
|
+
if (done)
|
|
158
|
+
return;
|
|
159
|
+
done = true;
|
|
160
|
+
this.host.clearTimeout(timer);
|
|
161
|
+
bridge.removeEventListener("message", listener);
|
|
162
|
+
this.releases.delete(destroy);
|
|
163
|
+
this.host.removeEventListener?.("pagehide", destroy);
|
|
164
|
+
resolveReady(result);
|
|
165
|
+
resolveClosed(result);
|
|
166
|
+
if (paused)
|
|
167
|
+
callback(options?.onResume);
|
|
168
|
+
};
|
|
169
|
+
const destroy = () => {
|
|
170
|
+
try {
|
|
171
|
+
send("destroy");
|
|
172
|
+
}
|
|
173
|
+
catch { /* a detached native port is already unavailable */ }
|
|
174
|
+
finally {
|
|
175
|
+
finish(this.result("cancelled"));
|
|
176
|
+
}
|
|
177
|
+
};
|
|
178
|
+
const listener = (event) => {
|
|
179
|
+
let value;
|
|
180
|
+
try {
|
|
181
|
+
value = JSON.parse(event.data);
|
|
182
|
+
}
|
|
183
|
+
catch {
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
if (!value || value.channel !== "wovoon:ads:v1" || value.id !== id || done)
|
|
187
|
+
return;
|
|
188
|
+
if (value.event === "presenting") {
|
|
189
|
+
this.host.clearTimeout(timer);
|
|
190
|
+
if (!paused) {
|
|
191
|
+
paused = true;
|
|
192
|
+
callback(options?.onPause);
|
|
193
|
+
}
|
|
194
|
+
return;
|
|
195
|
+
}
|
|
196
|
+
const result = value.result;
|
|
197
|
+
if (!result || !["shown", "closed", "unavailable", "no_fill", "busy", "frequency_capped", "cancelled", "error"].includes(result.status))
|
|
198
|
+
return;
|
|
199
|
+
// A JS/native callback is never proof of a server-verified reward.
|
|
200
|
+
const safe = { ...result, rewarded: action === "capabilities" && result.rewarded === true };
|
|
201
|
+
delete safe.reward;
|
|
202
|
+
if (value.event === "shown" && action !== "capabilities") {
|
|
203
|
+
resolveReady(safe);
|
|
204
|
+
this.host.clearTimeout(timer);
|
|
205
|
+
}
|
|
206
|
+
else
|
|
207
|
+
finish(safe);
|
|
208
|
+
};
|
|
209
|
+
const timer = this.host.setTimeout(() => {
|
|
210
|
+
try {
|
|
211
|
+
send("destroy");
|
|
212
|
+
}
|
|
213
|
+
finally {
|
|
214
|
+
finish(this.result("unavailable", "HOST_TIMEOUT"));
|
|
215
|
+
}
|
|
216
|
+
}, action === "capabilities" ? 6000 : 30000);
|
|
217
|
+
bridge.addEventListener("message", listener);
|
|
218
|
+
this.releases.add(destroy);
|
|
219
|
+
this.host.addEventListener?.("pagehide", destroy);
|
|
220
|
+
try {
|
|
221
|
+
send(action, params);
|
|
222
|
+
}
|
|
223
|
+
catch {
|
|
224
|
+
finish(this.result("unavailable", "HOST_UNAVAILABLE"));
|
|
225
|
+
}
|
|
226
|
+
return { ready, closed, destroy, send };
|
|
227
|
+
}
|
|
228
|
+
}
|
package/dist/client.d.ts
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* 在作品内通过 <script> 引入平台下发的 /api/cloud/sdk.js(全局 WovoonCloud)即可使用,
|
|
4
4
|
* 本模块提供同一 API 的 TypeScript 实现,供构建型项目以模块方式引入。
|
|
5
5
|
*/
|
|
6
|
+
import { PolarisAds } from "./ads.js";
|
|
6
7
|
export interface PolarisRequestInit {
|
|
7
8
|
/** 覆盖 API 基址(本地模拟器/自建环境用),默认同源。 */
|
|
8
9
|
baseUrl?: string;
|
|
@@ -43,6 +44,7 @@ export interface PolarisQueryOptions {
|
|
|
43
44
|
}
|
|
44
45
|
declare function parseData<T = Record<string, unknown>>(raw: string): T;
|
|
45
46
|
export declare class PolarisClient {
|
|
47
|
+
readonly ads: PolarisAds;
|
|
46
48
|
private readonly baseUrl;
|
|
47
49
|
private sessionPromise;
|
|
48
50
|
private target;
|
package/dist/client.js
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* 在作品内通过 <script> 引入平台下发的 /api/cloud/sdk.js(全局 WovoonCloud)即可使用,
|
|
4
4
|
* 本模块提供同一 API 的 TypeScript 实现,供构建型项目以模块方式引入。
|
|
5
5
|
*/
|
|
6
|
+
import { PolarisAds } from "./ads.js";
|
|
6
7
|
export class PolarisError extends Error {
|
|
7
8
|
constructor(message, code = "WOVOON_CLOUD_ERROR") {
|
|
8
9
|
super(message);
|
|
@@ -24,6 +25,12 @@ export class PolarisClient {
|
|
|
24
25
|
return this.baseUrl || runtime || (typeof location === "undefined" ? "http://localhost" : location.origin);
|
|
25
26
|
}
|
|
26
27
|
constructor(init = {}) {
|
|
28
|
+
this.ads = new PolarisAds(globalThis, (action, body) => {
|
|
29
|
+
const target = this.detectTarget();
|
|
30
|
+
if (!target)
|
|
31
|
+
return Promise.reject(new PolarisError("请从平台运行作品", "WOVOON_TARGET_MISSING"));
|
|
32
|
+
return this.request("POST", `/api/cloud/${encodeURIComponent(target)}/ad-rewards/${action}`, body);
|
|
33
|
+
});
|
|
27
34
|
this.sessionPromise = null;
|
|
28
35
|
this.target = "";
|
|
29
36
|
this.collectionsWatch = { listeners: [], socket: null, pending: false, generation: 0 };
|
|
@@ -33,6 +40,7 @@ export class PolarisClient {
|
|
|
33
40
|
}
|
|
34
41
|
/** 指定作品目标:deploymentId(运行地址自动识别)或 appId。 */
|
|
35
42
|
configure(options) {
|
|
43
|
+
this.ads.dispose();
|
|
36
44
|
for (const room of this.activeRooms.values())
|
|
37
45
|
room.leave();
|
|
38
46
|
this.collectionsWatch.generation++;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
/** Polaris protocol 1: identity, collections, functions and realtime rooms. */
|
|
2
2
|
export { WOVOON_PROTOCOL_VERSION, COLLECTION_NAME_PATTERN, isValidCollectionName, CAPABILITY_PATTERN, isValidCapability, WovoonProtocolError, } from "./protocol.js";
|
|
3
3
|
export { PolarisClient, PolarisError, parseData } from "./client.js";
|
|
4
|
+
export { PolarisAds } from "./ads.js";
|
|
5
|
+
export type { PolarisAdFormat, PolarisAdStatus, PolarisAdResult, PolarisAdCapabilities, PolarisAdOptions, PolarisBanner } from "./ads.js";
|
|
6
|
+
export type { PolarisRewardReceipt, PolarisRewardBalance, PolarisRewardSpend } from "./ads.js";
|
|
4
7
|
export type { WovoonCapability, WovoonCollectionName, WovoonManifest, WovoonSession, WovoonDocument, WovoonQueryOptions, WovoonFunctionEvent, WovoonFunctionResult, WovoonRoomFrame, } from "./protocol.js";
|
|
5
8
|
export type { PolarisRequestInit, PolarisSessionView, PolarisDocumentView, PolarisQueryOptions } from "./client.js";
|
package/dist/index.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
/** Polaris protocol 1: identity, collections, functions and realtime rooms. */
|
|
2
2
|
export { WOVOON_PROTOCOL_VERSION, COLLECTION_NAME_PATTERN, isValidCollectionName, CAPABILITY_PATTERN, isValidCapability, WovoonProtocolError, } from "./protocol.js";
|
|
3
3
|
export { PolarisClient, PolarisError, parseData } from "./client.js";
|
|
4
|
+
export { PolarisAds } from "./ads.js";
|
package/dist/protocol.d.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
/** 协议版本。协议 1 是当前唯一支持的版本。 */
|
|
6
6
|
export declare const WOVOON_PROTOCOL_VERSION: 1;
|
|
7
7
|
/** 协议 1 冻结的能力名。集合能力形如 `collection:${WovoonCollectionName}`。 */
|
|
8
|
-
export type WovoonCapability = "identity" | `collection:${WovoonCollectionName}` | "function" | "room" | "room:competitive" | "gamelogic";
|
|
8
|
+
export type WovoonCapability = "identity" | `collection:${WovoonCollectionName}` | "function" | "room" | "room:competitive" | "ads" | "gamelogic";
|
|
9
9
|
/** 集合名:2-32 位,小写字母开头,仅小写字母/数字/下划线。运行时校验用下方正则。 */
|
|
10
10
|
export type WovoonCollectionName = string;
|
|
11
11
|
export declare const COLLECTION_NAME_PATTERN: RegExp;
|
package/dist/protocol.js
CHANGED
|
@@ -9,7 +9,7 @@ export function isValidCollectionName(name) {
|
|
|
9
9
|
return COLLECTION_NAME_PATTERN.test(name);
|
|
10
10
|
}
|
|
11
11
|
/** manifest 里单个能力名的完整合法形态(与平台 AssetSecurityScanner.parseContract 的校验一致)。 */
|
|
12
|
-
export const CAPABILITY_PATTERN = /^(identity|function|room|room:competitive|gamelogic|collection:[a-z][a-z0-9_]{1,31})$/;
|
|
12
|
+
export const CAPABILITY_PATTERN = /^(identity|function|room|room:competitive|gamelogic|ads|collection:[a-z][a-z0-9_]{1,31})$/;
|
|
13
13
|
export function isValidCapability(value) {
|
|
14
14
|
return CAPABILITY_PATTERN.test(value);
|
|
15
15
|
}
|
package/docs/ads.md
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# 作品广告容器(SDK 0.8.0,协议 1 追加)
|
|
2
|
+
|
|
3
|
+
作品声明 `{"protocol":1,"capabilities":["ads"]}`,通过 `WovoonPolaris.ads`
|
|
4
|
+
(与 `WovoonCloud.ads` 相同)或 `new PolarisClient().ads` 调用。
|
|
5
|
+
单独使用广告不要求声明 `identity` 或调用 `ready()`。
|
|
6
|
+
|
|
7
|
+
同一份作品代码可运行在网页和 Android。网页目前没有已授权广告源:
|
|
8
|
+
SDK 立即返回 `unavailable / NO_AUTHORIZED_SOURCE`,不发广告请求、不创建空白占位、
|
|
9
|
+
不阻塞开始或过关。旧版 App、iOS 和没有原生广告桥的宿主也直接跳过。
|
|
10
|
+
后续网页联盟接入须增加经过授权的网页渲染通道,不能直接在网页运行原生联盟 SDK。
|
|
11
|
+
|
|
12
|
+
## 全屏广告
|
|
13
|
+
|
|
14
|
+
```js
|
|
15
|
+
const result = await WovoonPolaris.ads.show({
|
|
16
|
+
format: "interstitial",
|
|
17
|
+
placement: "level_end",
|
|
18
|
+
onPause: () => { game.pause(); game.mute(); },
|
|
19
|
+
onResume: () => { game.resume(); game.restoreSound(); }
|
|
20
|
+
});
|
|
21
|
+
// 无广告、频控、失败都要继续游戏。只有实际进入展示才调用 onPause。
|
|
22
|
+
goToNextLevel();
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`show` 在广告关闭或跳过后完成。只有关卡结算、菜单等自然停顿时请求插屏,
|
|
26
|
+
不要在操作中途弹出。作品应在回调中暂停/恢复自己的游戏循环和音频;
|
|
27
|
+
SDK 不修改游戏引擎、不暂停云连接、不重新加载游戏。
|
|
28
|
+
|
|
29
|
+
## 横幅容器
|
|
30
|
+
|
|
31
|
+
```html
|
|
32
|
+
<div id="game-ad"></div>
|
|
33
|
+
<script>
|
|
34
|
+
async function mountMenuAd() {
|
|
35
|
+
const ads = WovoonPolaris.ads;
|
|
36
|
+
const caps = await ads.capabilities();
|
|
37
|
+
if (!caps.banner) return; // 网页不留空白区域
|
|
38
|
+
const container = document.querySelector("#game-ad");
|
|
39
|
+
container.style.cssText = "width:320px;min-height:250px;margin:auto";
|
|
40
|
+
const banner = ads.mountBanner(container, { placement: "menu_footer" });
|
|
41
|
+
const result = await banner.ready;
|
|
42
|
+
if (result.status !== "shown") container.style.cssText = "";
|
|
43
|
+
banner.closed.then(() => { container.style.cssText = ""; });
|
|
44
|
+
// 离开当前界面前:banner.destroy()
|
|
45
|
+
}
|
|
46
|
+
</script>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
容器须在主文档内、完全可见、宽至少 320 CSS 像素、高至少 50。
|
|
50
|
+
聚合源可能返回较高的信息流模板,建议预留 250 像素高度;若真实模板大于容器,
|
|
51
|
+
原生宿主会跳过,绝不裁掉广告标识或关闭入口。避免变换、覆盖、透明祖先、
|
|
52
|
+
滚动容器裁切和游戏操作区域重叠。移出屏幕、页面隐藏或销毁会关闭广告;
|
|
53
|
+
重新展示由作品显式请求,SDK 不自动刷新刷曝光。Android 横幅是宿主原生视图,
|
|
54
|
+
不支持把广告当成 Canvas/WebGL 纹理或嵌套 iframe 内容。
|
|
55
|
+
|
|
56
|
+
## 能力与结果
|
|
57
|
+
|
|
58
|
+
- `capabilities()` → `{surface, banner, interstitial, rewarded, reason?}`。可用不代表必有填充。
|
|
59
|
+
- `show({format:"interstitial"|"rewarded", placement, onPause?, onResume?})` → `Promise<AdResult>`。
|
|
60
|
+
- `mountBanner(element,{placement})` → `{ready, closed, destroy()}`。
|
|
61
|
+
- `dispose()` 取消该 SDK 客户端的所有请求;`configure()` 自动清理旧请求。
|
|
62
|
+
- `AdResult.status`:`shown / closed / unavailable / no_fill / busy / frequency_capped / cancelled / error`。
|
|
63
|
+
- `placement` 是作品内稳定的场景名(字母开头,字母/数字/下划线/点/横线,最多 64 字符),不是联盟广告位 ID。
|
|
64
|
+
- `rewarded:true` 只表示服务器已确认到账;缺少 SSV/作品奖励规则时不可用。
|
|
65
|
+
配置、延迟回调恢复和幂等扣减见 [激励广告与作品奖励](rewarded-ads.md)。禁止用关闭、计时器或 `VIDEO_COMPLETE` 发奖。
|
|
66
|
+
- 开屏由 App 启动流程统一管理,不提供给作品反复调用。
|
|
67
|
+
|
|
68
|
+
## 平台与安全
|
|
69
|
+
|
|
70
|
+
Android 主文档通过精确运行域白名单的 WebMessage 桥请求宿主。宿主使用自己保存的
|
|
71
|
+
作品 ID、有效游玩租约向 `/api/public/ads/runtime/authorize` 请求准入;
|
|
72
|
+
平台核对作品公开状态、租约归属和清单 `ads` 能力。作品不能选其他作品、会话、
|
|
73
|
+
广告源 URL、联盟 ID、eCPM 或奖励数值。
|
|
74
|
+
|
|
75
|
+
平台沿用后台 Android 广告频率配置:选择对应格式的 GroMore 聚合位,统一频控,
|
|
76
|
+
真实填充与比价由已接入的聚合 SDK 完成。平台现有网页模拟竞价/自推广素材不会
|
|
77
|
+
作为此接口的填充。SDK 回调仅为展示结果,不是结算收入或服务端奖励凭证。
|
|
78
|
+
当前横幅和插屏与 App 对应格式共用频率额度;任一全屏广告展示时不再启动第二个。
|
package/docs/index.md
CHANGED
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
- 作品运行在 `http://localhost:5179/api/public/static/{id}/`(与生产同路径,SDK 自动识别作品)。
|
|
35
35
|
- 云能力端点与生产逐字一致:`/api/cloud/session`、`/api/cloud/{app}/collections/{name}/docs`。
|
|
36
36
|
- `--player 名字` 模拟登录玩家(可写云数据);不带参数为游客(读公开集合、不可写)。
|
|
37
|
-
-
|
|
37
|
+
- 校验与配额与生产一致(能力门禁、套餐集合额度 / 万文档 / 64KB / limit≤100),报错文案一字不差。
|
|
38
38
|
|
|
39
39
|
用 curl 即可验证(无需浏览器):
|
|
40
40
|
|
package/docs/manifest.md
CHANGED
package/docs/quickstart.md
CHANGED
|
@@ -55,20 +55,29 @@ npx -y @wovoon/cli validate # 生产规则预检,PASS =
|
|
|
55
55
|
| `WORLD` | 人人可见(排行榜/公告) | `OWNER` | 登录玩家写自己的文档 |
|
|
56
56
|
| `PLAYER` | 仅文档主人可见(个人存档) | `SERVER` | **仅云函数可写**(防作弊数据的正解) |
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
配额:每作品集合数按套餐配置(免费/创作/专业默认 8/32/128)、1 万文档/集合、单文档 64KB。
|
|
59
59
|
|
|
60
60
|
### functions/*.js(云函数)
|
|
61
61
|
|
|
62
62
|
```js
|
|
63
|
-
// functions/settle.js ——
|
|
63
|
+
// functions/settle.js —— 教学结算;竞技结果应取自权威房间,不能信任客户端上报战绩
|
|
64
64
|
exports.main = async (event, context) => {
|
|
65
|
-
|
|
66
|
-
const
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
65
|
+
if (!context.player.loggedIn) throw new Error('请先登录');
|
|
66
|
+
const { kills, wave } = event;
|
|
67
|
+
if (![kills, wave].every(n => Number.isSafeInteger(n) && n >= 0 && n <= 10000)) {
|
|
68
|
+
throw new Error('战绩格式无效');
|
|
69
|
+
}
|
|
70
|
+
const score = kills * 10 + wave * 50;
|
|
71
|
+
const col = context.cloud.collection('rankings');
|
|
72
|
+
const playerId = context.player.playerId;
|
|
73
|
+
// SERVER 文档归属平台;玩家身份放在业务字段中,set 只能更新已存在的文档 id。
|
|
74
|
+
const mine = (await col.query({ where: { playerId }, limit: 1 }))[0];
|
|
75
|
+
const data = { playerId, score, at: Date.now() };
|
|
76
|
+
if (mine) await col.set(mine.id, data);
|
|
77
|
+
else await col.add(data);
|
|
78
|
+
const top = await col.query({ orderBy: 'score', order: 'desc', limit: 10 });
|
|
79
|
+
const rank = top.findIndex(d => JSON.parse(d.data).playerId === playerId);
|
|
80
|
+
return { score, rank: rank < 0 ? null : rank + 1 };
|
|
72
81
|
};
|
|
73
82
|
|
|
74
83
|
// 可选元数据(直接在函数文件里声明):
|
|
@@ -77,7 +86,7 @@ exports.main = async (event, context) => {
|
|
|
77
86
|
// exports.timeoutMs = 30000; // 长任务档 1000~60000ms(默认 3000)
|
|
78
87
|
```
|
|
79
88
|
|
|
80
|
-
沙箱:禁出网、64MB 内存、入出参 ≤32KB
|
|
89
|
+
沙箱:禁出网、64MB 内存、入出参 ≤32KB;月调用次数由云服务套餐配置;另有玩家 30 次/分、作品 20 万次/日的安全上限。
|
|
81
90
|
|
|
82
91
|
---
|
|
83
92
|
|
|
@@ -110,8 +119,8 @@ await cloud.call('settle', { kills, wave }); // 调云函数
|
|
|
110
119
|
|
|
111
120
|
const room = cloud.room('arena-1'); // 实时房间(256 人/房)
|
|
112
121
|
room.send({ x, y, hp }); // ≤4KB,300 帧/30s
|
|
113
|
-
room.onMessage((
|
|
114
|
-
room.onPresence((
|
|
122
|
+
room.onMessage(({ from, data }) => {});
|
|
123
|
+
room.onPresence(({ type, playerId, players }) => {});
|
|
115
124
|
```
|
|
116
125
|
|
|
117
126
|
TypeScript 构建期可用 `@wovoon/polaris`(全量类型)。
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# 在 AI 开发会话中接入作品激励广告
|
|
2
|
+
|
|
3
|
+
不需要在创作者中心配置广告。北极星负责作者端配置和作品端调用,Wovoon 云端负责权限、频控、广告准入、回调校验、记账与幂等扣减。作者自由设置入口的位置、样式、场景名和虚拟奖励;不能自行决定广告联盟或把客户端通知当成到账凭证。
|
|
4
|
+
|
|
5
|
+
## 给 AI 的任务
|
|
6
|
+
|
|
7
|
+
把下面的话交给开发或改造作品的 AI:
|
|
8
|
+
|
|
9
|
+
> 在现有作品中接入 Wovoon 北极星激励广告云能力。保留原玩法,把“观看广告复活”按钮放在失败结算界面,样式与作品一致。声明 ads 能力,使用 placement:revive。奖励是 life(复活机会)×1,每人每日最多10次,请求间隔60秒。在项目中建立 wovoon.ads.json,通过 wovoon ads status/plan/apply 配置云端,先指向 dev 测试环境。网页没有原生广告宿主时提示“激励广告仅移动端支持”,游戏其他功能保持可用;Android App 主动点击后才请求广告,展示时暂停游戏和声音,关闭后恢复。只接受服务端 reward.status=granted;使用 rewardBalances 恢复余额,consumeReward 按持久化操作ID幂等扣减。取消、无填充、失败、回调待确认都不能发奖。不要创建创作者中心页面,不把密钥、PAT、联盟位ID写进作品,不自动同步生产。
|
|
10
|
+
|
|
11
|
+
复活、双倍结算、商店领取可以配置不同 placement;同一个 rewardKey 共用当前作品、当前玩家的余额。全屏激励广告的画面由 App 展示,“自定义位置”指作品内触发入口的位置,不是任意裁切或嵌入视频画面。
|
|
12
|
+
|
|
13
|
+
## AI 配置云端奖励
|
|
14
|
+
|
|
15
|
+
CLI 0.15.0 提供以下命令(开发分支安装方式以交付说明为准,不能假定 npm 已发布):
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
wovoon ads status ./my-game
|
|
19
|
+
wovoon ads plan ./my-game
|
|
20
|
+
wovoon ads apply ./my-game
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
先使用常规 `wovoon login` 登录**测试平台**,项目 `wovoon.config.json` 指定 `api: "https://dev.wovanshop.com"` 和已有作品 `appId`。首次作品先 `wovoon deploy` 创建作品,再配置奖励。作者令牌只保存在 CLI 凭据文件,不能放进游戏或广告配置。
|
|
24
|
+
|
|
25
|
+
在项目根创建 `wovoon.ads.json`,api、appId 必须与项目配置完全一致:
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"version": 1,
|
|
30
|
+
"api": "https://dev.wovanshop.com",
|
|
31
|
+
"appId": "替换为你拥有的测试作品ID",
|
|
32
|
+
"placements": [
|
|
33
|
+
{"placement":"revive","rewardKey":"life","rewardName":"复活机会","amount":1,"dailyLimit":10,"intervalSeconds":60,"enabled":true,"revision":0}
|
|
34
|
+
]
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`status` 读取云端当前值,`plan` 只预览新增/修改/保持不变,`apply` 才保存。新增用 revision:0;修改用 status 返回的 revision。apply 返回已保存规则及新 revision,AI 应据此更新本地文件。遇到并发冲突先核对差异,不要只提高 revision 强行覆盖。未列出的规则保持,停用需显式写 enabled:false。
|
|
39
|
+
|
|
40
|
+
应用是逐场景提交;中途失败会报告已确认保存的场景。网络超时可能已在服务器成功,先 status 核对后重试,不盲目重发。此文件不会被 CLI 打包进作品;它也不包含任何秘密。规则按现有作者权限 API 保存,无需广告联盟密钥。
|
|
41
|
+
|
|
42
|
+
## 作品端放置入口
|
|
43
|
+
|
|
44
|
+
在项目 `.wovoon` 声明 `{"protocol":1,"capabilities":["ads"]}`,与已有能力合并。HTML 页面只加载一次 `/api/cloud/sdk.js`;构建型项目也可以用 `new PolarisClient().ads`。
|
|
45
|
+
|
|
46
|
+
```html
|
|
47
|
+
<!-- 位置、按钮样式、文案由作品自己决定。 -->
|
|
48
|
+
<button id="revive" type="button" disabled>观看广告复活</button>
|
|
49
|
+
<p id="ad-status" role="status"></p>
|
|
50
|
+
<script src="/api/cloud/sdk.js"></script>
|
|
51
|
+
<script>
|
|
52
|
+
const button = document.getElementById('revive');
|
|
53
|
+
const status = document.getElementById('ad-status');
|
|
54
|
+
const ads = WovoonPolaris.ads;
|
|
55
|
+
ads.capabilities().then(caps => {
|
|
56
|
+
button.disabled = !caps.rewarded;
|
|
57
|
+
status.textContent = caps.surface === 'web'
|
|
58
|
+
? '激励广告仅移动端支持(当前为 Android App)'
|
|
59
|
+
: caps.rewarded ? '' : '激励广告暂不可用,请稍后再试。';
|
|
60
|
+
}).catch(() => { status.textContent = '激励广告暂不可用。'; });
|
|
61
|
+
button.onclick = async () => {
|
|
62
|
+
if (button.disabled) return;
|
|
63
|
+
button.disabled = true;
|
|
64
|
+
try {
|
|
65
|
+
const result = await ads.show({format:'rewarded', placement:'revive',
|
|
66
|
+
onPause: () => { /* 暂停游戏与声音 */ },
|
|
67
|
+
onResume: () => { /* 恢复游戏与声音 */ }
|
|
68
|
+
});
|
|
69
|
+
if (result.rewarded) {
|
|
70
|
+
const balances = await ads.rewardBalances();
|
|
71
|
+
// 用云端余额刷新你的界面,不能在本地再加1次。
|
|
72
|
+
status.textContent = '奖励已到账:' + JSON.stringify(balances);
|
|
73
|
+
} else if (result.requestId && ['REWARD_PENDING','REWARD_STATUS_UNAVAILABLE'].includes(result.reason)) {
|
|
74
|
+
// 按作品/玩家持久化 requestId,提供“查询到账”按钮。
|
|
75
|
+
// 玩家重试时 await ads.rewardStatus(result.requestId),granted 后刷新余额。
|
|
76
|
+
status.textContent = '奖励确认中,请稍后查询到账。';
|
|
77
|
+
} else status.textContent = '本次未获得奖励,可以继续游戏。';
|
|
78
|
+
} catch { status.textContent = '广告暂不可用,可以继续游戏。'; }
|
|
79
|
+
finally { button.disabled = false; }
|
|
80
|
+
};
|
|
81
|
+
</script>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Canvas、Unity、Godot 的按钮回调同样调用 `ads.show`,不要求使用 HTML 按钮。运行 `wovoon init my-ad-demo --template rewarded` 创建完整可运行的双入口示例;奖励消费与延迟回调的恢复规则见 [激励广告协议](../rewarded-ads.md)。原生 iOS 目前没有广告宿主,能力不可用时展示暂不支持提示。
|
|
85
|
+
|
|
86
|
+
## dev 验收
|
|
87
|
+
|
|
88
|
+
先确认 CLI 目标与原生 App 都是 dev,作品声明 ads 且由你拥有。用 status 验证配置与奖励数量,再在普通网页验证移动端提示,在 Android dev App 验证两个自定义入口、取消/关闭、实际到账、重查不增发和消费重试不重扣。没有真实广告源时记录无填充;不能以假广告或模拟回调冒充通过。通过后再单独决定生产发布。
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# 激励广告与作品奖励(SDK 0.8.0)
|
|
2
|
+
|
|
3
|
+
奖励是每个作品、每个登录玩家独立的虚拟额度,例如复活次数、游戏金币。
|
|
4
|
+
它不会增加 Wovoon 平台积分、现金或创作者收益。没有服务器配置、未登录、没有广告源时跳过。
|
|
5
|
+
网页可以读取和使用已经到账的作品奖励,但目前不能加载激励广告;iOS 尚无此广告宿主。
|
|
6
|
+
|
|
7
|
+
## 创作者配置
|
|
8
|
+
|
|
9
|
+
推荐在 AI 开发/改造会话中使用 CLI 0.15.0 的 `wovoon ads status/plan/apply` 和项目 `wovoon.ads.json` 配置,无需创作者中心广告页面。完整流程与双入口示例见 [AI 配置激励广告](recipes/rewarded-placement.md)。
|
|
10
|
+
|
|
11
|
+
先声明 `.wovoon` 的 `ads` 能力。底层作者管理 API(也支持作者 PAT)为
|
|
12
|
+
`GET /api/cloud/manage/{appId}/ad-rewards` 读取规则,或 `PUT` 同一地址保存:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
{"placement":"revive","rewardKey":"life","rewardName":"复活机会","amount":1,"dailyLimit":10,"intervalSeconds":60,"enabled":true,"revision":0}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
新增用 `revision:0`,修改必须带 GET 返回的当前 revision;只有作品拥有者可修改。
|
|
19
|
+
场景名与 rewardKey 为字母开头、最长 64 字符的字母/数字/下划线/点/横线。
|
|
20
|
+
数量 1–10000,每日请求上限 1–100,最小间隔 30–86400 秒,奖励名称最多 40 字符。
|
|
21
|
+
每日按 UTC 计算,拒绝观看、无填充和失败请求也占已签发次数;不能靠断线绕过频控。
|
|
22
|
+
已签发的 15 分钟请求使用当时的奖励快照。关闭规则阻止新请求,全局开关关闭则停止处理新回调。
|
|
23
|
+
|
|
24
|
+
## 游戏调用
|
|
25
|
+
|
|
26
|
+
```js
|
|
27
|
+
const ads = WovoonPolaris.ads;
|
|
28
|
+
// 必须由玩家主动点击入口;Android 还会显示平台确认框。
|
|
29
|
+
const result = await ads.show({
|
|
30
|
+
format: "rewarded", placement: "revive",
|
|
31
|
+
onPause: () => game.pause(), onResume: () => game.resume()
|
|
32
|
+
});
|
|
33
|
+
// 服务端已完成到账;读取余额刷新 UI,不能每次收到 granted 就在本地再次加金币。
|
|
34
|
+
renderRewardBalances(await ads.rewardBalances());
|
|
35
|
+
if (result.reason === "REWARD_PENDING" && result.requestId) {
|
|
36
|
+
// 延迟回调时稍后主动查询;不要高频轮询。
|
|
37
|
+
const receipt = await ads.rewardStatus(result.requestId);
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`show` 关闭后查询服务端,只有 `reward.status === "granted"` 才返回 `rewarded:true`。
|
|
42
|
+
`pending`、`expired`、网络失败都不能当成已到账;网络失败返回
|
|
43
|
+
`REWARD_STATUS_UNAVAILABLE`,保留 requestId 供重试。查询超时为 8 秒。
|
|
44
|
+
重启或关闭前未取得 requestId 时,可通过 `rewardBalances()` 恢复服务端总余额。
|
|
45
|
+
广告关闭、视频完成、客户端 onRewardArrived/onRewardVerify 都不会修改账本。
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
// 在发请求前持久化本次业务操作 ID;断网重试必须继续用同一个 ID。
|
|
49
|
+
const operation = {clientId: "revive_attempt_42", rewardKey: "life", amount: 1};
|
|
50
|
+
const spent = await ads.consumeReward(operation);
|
|
51
|
+
renderBalance(spent.balanceAfter);
|
|
52
|
+
// 游戏自己的复活/购买流程也必须按 operation.clientId 去重,不能每次重试重复执行。
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`consumeReward` 原子扣减、不允许负余额;同 ID 同参数返回原结果,不重复扣减;
|
|
56
|
+
同 ID 改参数拒绝。API 不向客户端提供加奖接口。余额属于服务器账本,不等同于任意游戏
|
|
57
|
+
存档里的金币;有自建后端的游戏应由业务服务器按操作 ID 处理实际道具,不能信任客户端通知。
|
|
58
|
+
|
|
59
|
+
玩家端 HTTP 为 POST `/api/cloud/{appIdOrDeploymentId}/ad-rewards/status|balances|consume`,
|
|
60
|
+
使用作品运行域 HttpOnly 租约 Cookie 和 Origin 校验。它们沿用云数据每玩家每进程
|
|
61
|
+
120 次/分钟限制;发奖和扣减幂等在 PostgreSQL 中跨进程生效。
|
|
62
|
+
|
|
63
|
+
## 平台开通和验收
|
|
64
|
+
|
|
65
|
+
GroMore 聚合位需开启服务端激励验证,HTTPS GET 回调:
|
|
66
|
+
`/api/public/ads/rewards/gromore`。每个环境应使用独立聚合位和 m-key,避免 dev/prod 回调串线。
|
|
67
|
+
只在后端 Secret 注入 `WOVOON_REWARD_SSV_ENABLED=true`、`WOVOON_REWARD_SSV_ENV=dev|prod`、
|
|
68
|
+
`WOVOON_REWARD_SSV_SLOT`、`WOVOON_REWARD_SSV_KEY`;缺任一配置默认不可用。
|
|
69
|
+
广告格式总开关及 rewarded 格式也必须开启,slot 必须与后端配置一致。
|
|
70
|
+
不得把 m-key 放入作品、APK、SDK、Git 或普通日志。
|
|
71
|
+
|
|
72
|
+
官方签名为 `SHA256(m-key + ":" + trans_id)`;回调还绑定服务器预签的环境、作品、玩家、
|
|
73
|
+
请求和奖励快照,交易 ID 唯一。事务将回执与余额一起写入,重复回调返回成功但不重复发奖。
|
|
74
|
+
本协议依赖 GroMore 的服务端事件语义,不把签名本身描述为完整观看或真人观看证明。
|
|
75
|
+
返回原始 `{"is_verify":true,"reason":0}`,不包裹平台 ApiResponse,并禁止缓存。
|
|
76
|
+
|
|
77
|
+
先在 dev 使用已授权测试作品/账号实际观看,核对 provider 回调、到账、重复回调、关闭/跳过、
|
|
78
|
+
断线恢复及扣减,再启用 prod。模拟签名和单元测试不能代替广告平台真实回调验收。
|
|
79
|
+
控制台修改可能需 15–30 分钟生效。验收前保持生产开关关闭。
|
|
80
|
+
|
|
81
|
+
官方资料:[GroMore 服务端激励验证](https://www.csjplatform.com/supportcenter/26240)、
|
|
82
|
+
[Android 激励广告](https://www.csjplatform.com/supportcenter/28661)。
|
package/docs/sdk.md
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
|
+
SDK 0.8.0 新增 [服务端激励奖励](rewarded-ads.md):校验、账本、回执和幂等扣减。
|
|
2
|
+
|
|
1
3
|
# 云能力 SDK(协议 1)
|
|
2
4
|
|
|
5
|
+
SDK 0.7.0 新增 [作品广告容器](ads.md):`ads.capabilities / show / mountBanner`。
|
|
6
|
+
网页无授权广告源立即跳过;Android 按作品权限和平台聚合配置展示横幅/插屏。
|
|
7
|
+
|
|
3
8
|
两种形态,同一套能力 API:
|
|
4
9
|
|
|
5
10
|
| 形态 | 引入方式 | 适合 |
|
|
@@ -56,7 +61,7 @@ const rows = docs.map(d => parseData(d)); // data 字符串 → 对象
|
|
|
56
61
|
| playerId | "账号 × 作品"稳定(同账号同作品恒定,跨作品不可关联);未登录为游客态 |
|
|
57
62
|
| 游客 | 可读 WORLD 集合;**不可写**(`登录后才能写入云数据`) |
|
|
58
63
|
| 权限 | 读 `WORLD`(默认,任何人)/ `PLAYER`(仅登录);写 `OWNER`(默认,本人文档)/ `SERVER`(云函数,M3) |
|
|
59
|
-
| 配额 |
|
|
64
|
+
| 配额 | 每作品集合数由套餐决定(免费/创作/专业默认 8/32/128,可由后台调整);每集合 10,000 条文档;单文档 64 KB;查询 limit ≤ 100(默认 20) |
|
|
60
65
|
| 排序 | `orderBy` 按文档**数值字段**应用层排序(`order: 'asc'|'desc'`),排行榜场景 |
|
|
61
66
|
| 文档形态 | JSON 对象(不能是数组/标量);`id`/`seq`/`createdAt`/`updatedAt` 平台维护 |
|
|
62
67
|
| 能力门禁 | 每次调用比对 `.wovoon` 声明,未声明即拒绝并附修复指引(见 [errors.md](errors.md#cloud)) |
|
package/llms.txt
CHANGED
|
@@ -20,6 +20,9 @@
|
|
|
20
20
|
本地模拟大后台;生产规则镜像校验;一条命令发布(内置默认图标/视频,非多模态 AI 也可发布;
|
|
21
21
|
每次发版可随时 rollback)。
|
|
22
22
|
- [云能力 SDK](docs/sdk.md): 页面内 `WovoonCloud`(平台同源下发)与 `@wovoon/polaris`(TypeScript 客户端)完整 API。
|
|
23
|
+
- [作品广告容器](docs/ads.md): `ads` 清单能力;网页无授权源立即跳过,Android 原生横幅/插屏;无填充继续游戏,激励视频未配置时不发奖。
|
|
24
|
+
|
|
25
|
+
- [AI 配置激励广告](docs/recipes/rewarded-placement.md): CLI 0.15 的 ads status/plan/apply,作品自定义入口与奖励;网页提示仅移动端支持,Android 真正展示,服务端校验到账。
|
|
23
26
|
|
|
24
27
|
## 改造配方(存量程序 → wovoon)
|
|
25
28
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wovoon/polaris",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.1",
|
|
4
4
|
"description": "wovoon Polaris SDK——wovoon 大后台云能力客户端(身份/数据集合/云函数/房间实时),协议 1",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"LICENSE"
|
|
15
15
|
],
|
|
16
16
|
"scripts": {
|
|
17
|
-
"build": "tsc -p tsconfig.json",
|
|
17
|
+
"build": "tsc -p tsconfig.json && node ../../scripts/sync-ads-browser.mjs",
|
|
18
18
|
"check": "tsc --noEmit",
|
|
19
19
|
"prepack": "node ../../scripts/package-docs.mjs"
|
|
20
20
|
},
|