@wovoon/polaris 0.6.4 → 0.10.0
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 +15 -2
- package/dist/ads.d.ts +77 -0
- package/dist/ads.js +228 -0
- package/dist/client.d.ts +12 -1
- package/dist/client.js +53 -31
- package/dist/commerce.d.ts +59 -0
- package/dist/commerce.js +174 -0
- package/dist/game-sync.d.ts +31 -0
- package/dist/game-sync.js +90 -0
- package/dist/game.d.ts +76 -0
- package/dist/game.js +178 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +4 -0
- package/dist/match.d.ts +10 -0
- package/dist/match.js +55 -0
- package/dist/protocol.d.ts +1 -1
- package/dist/protocol.js +1 -1
- package/docs/ads.md +78 -0
- package/docs/manifest.md +8 -1
- package/docs/recipes/game-commerce.md +63 -0
- package/docs/recipes/platform-game-mode.md +130 -0
- package/docs/recipes/rewarded-placement.md +103 -0
- package/docs/rewarded-ads.md +88 -0
- package/docs/sdk.md +5 -0
- package/llms.txt +9 -2
- package/package.json +2 -2
package/docs/ads.md
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# 作品广告容器(SDK 0.9.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/manifest.md
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
# `.wovoon` 清单规范(协议 1)
|
|
2
2
|
|
|
3
|
+
可选能力 `ads` 用于 [作品广告容器](ads.md),无需同时声明 `identity`。
|
|
4
|
+
无已授权广告源时作品必须继续游戏;声明本能力不保证广告填充。
|
|
5
|
+
|
|
3
6
|
`.wovoon` 是 wovoon 作品包的平台契约标识文件,放在**包根目录**。它同时承担两个职责:
|
|
4
7
|
|
|
5
8
|
1. 标识"这是一个 wovoon 应用"(没有它,作品包会被拒绝上传);
|
|
@@ -33,6 +36,10 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
|
|
|
33
36
|
| `collection:<名称>` | 数据集合:文档 CRUD、查询排序、权限 | 可用 |
|
|
34
37
|
| `function` | 云函数:受限 Node 沙箱(限时/限内存/禁出网)内运行服务端逻辑 | 可用 |
|
|
35
38
|
| `room` | 房间实时通道:WebSocket 房间中继(快节奏多人) | 可用 |
|
|
39
|
+
| `room:competitive` | 竞技速率档,和 room 配合使用 | 可用 |
|
|
40
|
+
| `gamelogic` | 常驻权威玩法,和 room 配合使用 | 可用 |
|
|
41
|
+
| `ads` | 平台广告展示与经验证的奖励 | 已授权源可用 |
|
|
42
|
+
| `commerce` | 平台购买、权益查询与权威消费 | 需 SDK 0.10 和对应平台运行时 |
|
|
36
43
|
|
|
37
44
|
- 集合名称:**2-32 位,小写字母开头,仅小写字母/数字/下划线**,如 `collection:scores`、`collection:player_profiles`。
|
|
38
45
|
- 只声明会用到的集合;改名集合时同步改 manifest。
|
|
@@ -48,7 +55,7 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
|
|
|
48
55
|
4. 只允许 `protocol`、`capabilities`、`entry` 与 `backend` 字段;
|
|
49
56
|
5. `protocol` 存在时必须是整数 `1`;
|
|
50
57
|
6. `backend` 存在时只支持 `platform` 或 `external`;
|
|
51
|
-
7. `capabilities` 存在时必须是字符串数组,且每项匹配 `^(identity|function|room|collection:[a-z][a-z0-9_]{1,31})$`。
|
|
58
|
+
7. `capabilities` 存在时必须是字符串数组,且每项匹配 `^(identity|function|room|room:competitive|gamelogic|ads|commerce|collection:[a-z][a-z0-9_]{1,31})$`。
|
|
52
59
|
|
|
53
60
|
本地预检:`wovoon validate`(规则镜像,报错文案与线上一字不差)。
|
|
54
61
|
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# 平台购买与游戏权益
|
|
2
|
+
|
|
3
|
+
SDK 0.10 / CLI 0.17 新增能力;需目标平台部署对应运行时。在 `.wovoon` 声明 `commerce`,多人权威玩法同时声明 `room`、`gamelogic` 和所需 SERVER 集合。支付密钥留在平台,不放进作品、AI 提示词或扩展。
|
|
4
|
+
|
|
5
|
+
## AI 配置商品
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
wovoon products init .
|
|
9
|
+
wovoon products validate .
|
|
10
|
+
wovoon products status .
|
|
11
|
+
wovoon products apply . --activate
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
编辑根目录 `products.json`:`version:1`,`products` 最多 100 项,每项指定 `productCode/name/description/productType/priceCents/currency/status`。价格单位是整数分,币种 CNY;`ONE_TIME` 为永久权益,`CONSUMABLE` 每单增加一个可消费单位。当前不支持订阅或自动续费。编码与类型保持稳定,改变权益含义须创建新编码。状态为 DRAFT、ACTIVE 或 ARCHIVED;含 ACTIVE 的同步需明确 `--activate`。同步只更新列出的商品,不自动删除遗漏项;重复 apply 可恢复中断的逐项同步。新价格只影响新订单。
|
|
15
|
+
|
|
16
|
+
## 购买和恢复
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
const {products, providers} = await WovoonCloud.commerce.catalog();
|
|
20
|
+
// 在明确的玩家购买操作中执行;下单前持久保存请求号。
|
|
21
|
+
const key = localStorage.getItem('pending:potion') || crypto.randomUUID();
|
|
22
|
+
localStorage.setItem('pending:potion', key);
|
|
23
|
+
const order = await WovoonCloud.commerce.checkout('potion', {
|
|
24
|
+
provider: 'ALIPAY', idempotencyKey: key
|
|
25
|
+
});
|
|
26
|
+
localStorage.setItem('pendingOrder:potion', order.orderId);
|
|
27
|
+
const result = await WovoonCloud.commerce.present(order);
|
|
28
|
+
// 关闭窗口、跳转回来及前端按钮均不是到账依据。
|
|
29
|
+
if (result.status === 'FULFILLED') {
|
|
30
|
+
const rights = await WovoonCloud.commerce.entitlements();
|
|
31
|
+
// 更新展示;权威玩法仍独立核验。
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
使用 catalog 返回的可用渠道。网络失败时使用同一请求号重试,不能自动生成新号。重进作品后按保存的 orderId 调用 `commerce.order(orderId)`,并用 `commerce.entitlements()` 恢复权益。只有上一单确认终止、玩家再次主动购买时才使用新请求号。支付页支持支付宝官方 HTTPS 页面及二维码、微信二维码。
|
|
36
|
+
|
|
37
|
+
新版手机容器提供 `WovoonNativeCommerce` 时,`commerce.present` 自动使用宿主支付通道。作品只发送订单编号;宿主用自己的当前作品及游玩租约重新读取平台订单,展示金额确认,再打开官方支付宝页面。作品不能指定收款地址。宿主返回 `opened/finished` 仅表示页面操作完成,必须继续查询平台订单。离开 App 后游玩会话可能结束,重新进入作品按已保存订单恢复;不要因页面重新加载再次下单。旧手机容器可能禁止新窗口,可用页面二维码跨设备支付;SDK 不会放宽容器导航限制。
|
|
38
|
+
|
|
39
|
+
过期后到账、超出支付额度或缺少商品快照的订单进入 PAID_REVIEW:平台记录收款并等待退款复核,不发放权益。退款审核后权益冻结;渠道确认成功后撤销权益、冲回开发者收益。处理结果未知时仍使用原退款单号重试。玩家可凭订单号联系平台处理退款,开发者不能自行伪造支付或退款回执。
|
|
40
|
+
|
|
41
|
+
## 权威玩法读取与消费
|
|
42
|
+
|
|
43
|
+
`ctx.readEntitlements(requestId,playerId)` 异步排队,结果交给同步回调 `exports.onEntitlements(state,receipt)`。检查 `ctx.features.entitlementQuery===1`;回执的 COMPLETED / entitlements 来自平台校验过的当前房间登录租约。不要信任客户端传入的账号、购买数量或 premium 标记。进入房间和购买完成后重新查询,不把 checkpoint 内的权益缓存当永久授权。
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
exports.onPlayerJoin = (state, id) => {
|
|
47
|
+
ctx.readEntitlements('join:' + id, id);
|
|
48
|
+
};
|
|
49
|
+
exports.onEntitlements = (state, receipt) => {
|
|
50
|
+
if (receipt.status !== 'COMPLETED') return;
|
|
51
|
+
state.players[receipt.playerId].premium = receipt.entitlements.some(
|
|
52
|
+
row => row.productCode === 'premium' && row.productType === 'ONE_TIME' && row.quantity > 0);
|
|
53
|
+
};
|
|
54
|
+
// 由服务端校验复活资格后,使用死亡事件对应的稳定业务号。
|
|
55
|
+
if (ctx.features.purchaseSettlement !== 1) throw Error('运行时未升级');
|
|
56
|
+
ctx.settle(`revive:${roundId}:${playerId}:${deathId}`, [
|
|
57
|
+
{op:'add',collection:'inventory',doc:{playerId,kind:'revive',roundId,deathId}}
|
|
58
|
+
], undefined, {playerId,productCode:'potion',amount:1});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
消费只支持 CONSUMABLE。费用与整批 SERVER 文档、COMPLETED 回执一起提交;重复业务号不重复扣减,同号不同内容拒绝,余额不足不在未来充值后自动执行。`onSettlement` 按原业务号处理:`result` 是 JSON 字符串,内含 `documents` 和 `purchase:{operationId,productCode,amount,balanceAfter}`。即时游戏效果也须针对事件去重,不能仅靠可能落后的房间快照。
|
|
62
|
+
|
|
63
|
+
本地测试:把 `[ {"playerId":"Alice","productCode":"potion","productType":"CONSUMABLE","quantity":3} ]` 保存到作品目录之外的测试文件,运行 `wovoon dev . --player Alice --commerce-fixture <文件>`。测试余额不是付款记录;本地 checkout/order 不调用真实支付渠道。`wovoon data` 快照会同时保存权益、消费和结算记录,避免只恢复道具而重复消费。
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# 单机玩法接入 Wovoon 游戏后台
|
|
2
|
+
|
|
3
|
+
此协议是协议 1 的新增可选能力。需要支持 `WovoonCloud.game` 的平台运行时;旧房间继续使用原接口。发布前必须验证目标环境,不把本地存在的方法当成生产已部署。
|
|
4
|
+
|
|
5
|
+
## AI 改造顺序
|
|
6
|
+
|
|
7
|
+
1. 保留现有画面、资源、输入方式和单机规则;识别权威状态、输入意图、随机数及胜负条件。
|
|
8
|
+
2. 用 `wovoon init --template mode` 生成参照(以 CLI help 的参数为准)。玩法放在 `roomservers/<mode>.js`,声明 `room`、`gamelogic`;高频模式同时声明 `room:competitive`。
|
|
9
|
+
3. 将判定移到常驻玩法回调。客户端不能决定玩家身份、坐标、命中结果、金币或“已经付款”。服务器校验每种输入的类型、范围和业务含义。
|
|
10
|
+
4. 客户端使用 `cloud.game(mode,{roomId})`。先等待 `ready`,再提交输入、渲染快照;身份、状态序号、心跳、重连由 SDK 处理。
|
|
11
|
+
5. 将可存档状态设计为 JSON。`view(state,playerId)` 只返回该玩家有权看到的状态;隐藏牌、背包和未发现的敌人不能放进公共快照。
|
|
12
|
+
6. 远端角色使用插值;需要即时响应的本地角色使用与服务器一致的确定性模拟函数和 `GamePrediction`。真实物理回滚、命中回溯、非确定性引擎需要针对游戏适配,不能只加一行 SDK 就宣称完成。
|
|
13
|
+
7. 先搜索通用扩展,优先复用;没有适合的扩展时创建作品私有版本。通过测试且作者明确愿意共享,再申请公共审核。
|
|
14
|
+
8. 验证双人、重连、慢连接、重复输入、私有状态、服务器重启及结算。实际发布前验收服务器隔离与平台租约。
|
|
15
|
+
|
|
16
|
+
## 常驻玩法契约
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
exports.gameProtocol = 1;
|
|
20
|
+
exports.tickRate = 60; // 10–60 Hz,可选;按玩法和压测选择
|
|
21
|
+
exports.snapshotMs = 50; // 20 Hz 状态,画面可独立按设备帧率渲染
|
|
22
|
+
exports.createState = () => ({players: {}});
|
|
23
|
+
exports.onPlayerJoin = (state, id) => { state.players[id] = {score: 0}; };
|
|
24
|
+
exports.onInput = (state, id, input) => {
|
|
25
|
+
// 校验输入并执行玩法,id 来自平台鉴权。
|
|
26
|
+
};
|
|
27
|
+
exports.update = (state, dtMs) => {};
|
|
28
|
+
exports.view = (state, id) => ({you: state.players[id]});
|
|
29
|
+
exports.onPlayerDisconnect = (state, id) => {}; // 停止持续移动等输入
|
|
30
|
+
exports.onPlayerLeave = (state, id) => { delete state.players[id]; };
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
回调同步执行,不能阻塞等待网络或数据库。`tickRate` 优先于 `tickMs`;省略时保留 50 ms。调度使用单调时钟并限制落后后的补跑,过载会记录 missedTicks。不能用提高 tick 率弥补超预算玩法。
|
|
34
|
+
|
|
35
|
+
新协议的完整快照包含 `instanceId/sequence/tick/serverTime/you/state/acknowledgements`。发送积压只替换尚未发送的完整快照;普通事件、交易回执保持顺序。旧协议不自动丢弃其消息。
|
|
36
|
+
|
|
37
|
+
新玩法输入采用每玩家共享令牌桶:120 条/秒、瞬时 30 条,覆盖多连接;SDK 建议最多 60 Hz。心跳、恢复请求占相同预算。每条仍受房间 8 KiB 竞技/普通大小限制,服务器对玩法业务另作校验。旧房间仍使用原来的 30 秒限额。输入没有收到快照确认时不能推断已执行。
|
|
38
|
+
|
|
39
|
+
`game.submit(input)` 返回本次已送入客户端传输的序号,失败返回 `null`;这不是服务器执行确认。`input` 是布尔简写。断线不自动重发旧操作,以免重复开火、购买或消费;幂等业务应使用业务请求号和服务端账本。
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
const prediction = new GamePrediction(initial, simulate);
|
|
43
|
+
const game = cloud.game<State>('arena', {
|
|
44
|
+
roomId,
|
|
45
|
+
interpolation: {delayMs: 100, interpolate},
|
|
46
|
+
onState(state, frame) {
|
|
47
|
+
prediction.reconcile(state.self, frame.acknowledgements[game.clientId] ?? 0, frame.instanceId);
|
|
48
|
+
},
|
|
49
|
+
onStatus(status) { if (status === 'reconnecting') prediction.reset(lastAuthoritativeSelf); }
|
|
50
|
+
});
|
|
51
|
+
await game.ready;
|
|
52
|
+
const sequence = game.submit(command);
|
|
53
|
+
if (sequence !== null) prediction.predict(sequence, command);
|
|
54
|
+
// 渲染:本地角色 prediction.state;远端角色 game.sample(performance.now())。
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
插值缓冲会引入配置的视觉延迟。预测仅重放本地未确认输入,不重发网络命令。模拟器必须具有相同的步长、碰撞和速度规则;客户端传入的 dt 不可直接信任。网络暂停时停止无限外推。换实例、切换房间及退出应清理缓存和预测。
|
|
58
|
+
|
|
59
|
+
## 恢复边界
|
|
60
|
+
|
|
61
|
+
新玩法每约 5 秒生成恢复快照,最大 512 KiB;只有服务端目录和持久化启用才保存。恢复绑定模式源码及扩展哈希,代码变化后不加载旧状态。进程故障可能丢失最后一个保存周期,不能用于保证付款或奖励不丢失。恢复后的实例 ID 改变,客户端必须重新校正。
|
|
62
|
+
|
|
63
|
+
重连玩家保留约 30 秒;离线回调应停止移动。持久存档、购买和重要结算必须使用平台事务及幂等接口,不能只放在房间 checkpoint。旧 `setup/onMessage` 闭包状态没有自动恢复承诺。
|
|
64
|
+
|
|
65
|
+
## 持久化结算
|
|
66
|
+
|
|
67
|
+
玩法用 `ctx.settle(operationId, writes)` 排队提交成绩或存档,当前 tick 不等待数据库。`operationId` 是作品和房间范围内稳定的业务编号,长度 1–128,只使用字母、数字、下划线、点、冒号和短横线。结算内容由权威玩法计算,不能直接转发客户端提供的分数。示例:
|
|
68
|
+
|
|
69
|
+
```js
|
|
70
|
+
// collections.json 声明 scores 的 write 为 SERVER,清单声明 collection:scores。
|
|
71
|
+
ctx.settle('round:' + state.roundId + ':result', [
|
|
72
|
+
{op: 'add', collection: 'scores', doc: {playerId, score: computedScore}}
|
|
73
|
+
]);
|
|
74
|
+
exports.onSettlement = (state, receipt) => {
|
|
75
|
+
if (receipt.status === 'COMPLETED') state.lastSettled = receipt.operationId;
|
|
76
|
+
// PENDING 尚未完成;REJECTED / FAILED 需要显示失败并保留业务编号。
|
|
77
|
+
};
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
每批 1–64 个 `add` / `set`,总请求最多 48 KiB;`set` 须提供目标文档 UUID。只允许本作品已声明、写权限为 SERVER 的集合。整批写入与完成回执在同一事务提交;其中一步失败整批回滚。同编号、同源码版本、同内容重复提交返回同一操作;不同内容会被拒绝,不能通过重试修改已接受的结算。
|
|
81
|
+
|
|
82
|
+
平台持久保存已接受的请求,房间退出后仍可完成。临时失败自动退避重试,最多 10 次,之后保留 FAILED 供管理员处理。每作品最多 1000 个未完成请求,每房间与普通文档写入合计每分钟 60 次。过期节点不能提交新的请求,已接受的请求继续执行。回执可能重复送达,`onSettlement` 必须幂等。故障恢复后应使用存档中的相同业务编号和原始内容查询式重试;不要生成新编号来猜测旧操作是否成功。
|
|
83
|
+
|
|
84
|
+
本地 `wovoon dev` 使用 SQLite 原子事务并保留去重记录,通常直接收到 COMPLETED;关闭本地持久化时此接口返回 REJECTED。生产先收到 PENDING,再异步收到完成结果。它处理作品集合的成绩和存档,不代表付款确认、平台积分或充值发货;这些仍须使用各自的可信平台账本。
|
|
85
|
+
|
|
86
|
+
## 奖励消费与游戏结算
|
|
87
|
+
|
|
88
|
+
激励广告的观看、原生展示和 SSV 验证沿用平台广告服务,成功回调才增加作品奖励账本。作品声明 `ads`,由作者/AI 用 `wovoon ads init/status/plan/apply` 配置奖励;玩法只消费已经到账的余额。
|
|
89
|
+
|
|
90
|
+
```js
|
|
91
|
+
// 在 onInput 中先检查玩家死亡状态、当前局次和复活资格。
|
|
92
|
+
// id 来自平台回调;deathId 由权威状态生成,不能直接接受客户端自报。
|
|
93
|
+
if (ctx.features?.rewardSettlement !== 1) throw Error('当前运行时不支持奖励事务');
|
|
94
|
+
ctx.settle(`revive:${state.roundId}:${id}:${player.deathId}`, [
|
|
95
|
+
{op:'add', collection:'entitlements', doc:{playerId:id, kind:'revive', round:state.roundId, death:player.deathId}}
|
|
96
|
+
], {playerId:id, rewardKey:'life', amount:1});
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`entitlements` 须声明为 SERVER 写入集合。平台从房间有效登录租约解析账号,并验证 ads 能力;不接受作品指定账号或游客消费。消费与整批 SERVER 写入及 COMPLETED 回执在同一数据库事务提交。任一写入失败,消费也回滚;重试不重复扣款。同编号改金额、玩家或文档会被拒绝。余额不足直接 FAILED,不会在未来看广告到账后偷偷执行旧请求;玩家再次确认业务后使用新的事件编号。
|
|
100
|
+
|
|
101
|
+
带奖励的 COMPLETED 回执,其 `result` 是 JSON 字符串,结构为 `{documents:[文档ID],reward:{clientId,rewardKey,amount,balanceAfter}}`;普通结算仍返回文档 ID 数组。`onSettlement` 按 operationId 幂等处理。房间 checkpoint 可能落后于账本,重启后按相同编号重提原内容并恢复结果,不能仅凭 checkpoint 未记录成功而生成新编号。持久化道具以 SERVER 文档为准;即时复活必须针对死亡事件去重。
|
|
102
|
+
|
|
103
|
+
这不是平台积分、现金、充值或开发者广告收入结算。新运行时专用能力必须检查上述 feature 标记,旧服务不支持时停止消费流程,不能忽略费用参数继续发道具。单机作品已有 `ads.consumeReward` 接口保留;需要权威道具时优先使用事务接口。完整广告接入和本地余额夹具见 [激励配置配方](rewarded-placement.md)。
|
|
104
|
+
|
|
105
|
+
## 通用扩展
|
|
106
|
+
|
|
107
|
+
```text
|
|
108
|
+
wovoon extensions search --query inventory
|
|
109
|
+
wovoon extensions init ./inventory --name inventory
|
|
110
|
+
wovoon extensions publish ./inventory
|
|
111
|
+
wovoon extensions install . --id <不可变版本UUID> --alias inventory
|
|
112
|
+
wovoon extensions status .
|
|
113
|
+
wovoon extensions submit ./inventory --id <版本UUID> --license MIT
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
执行前以 `wovoon help` 核对参数位置。发布默认私有,名字和版本在作者命名空间内唯一;重复相同上传幂等,不同内容须增版本。`wovoon.extensions.json` 锁定版本和 SHA-256,私有代码缓存不应加入公开作品包。平台安装绑定以服务端为准,`status` 可复核;请求结果未知时先读取状态。
|
|
117
|
+
|
|
118
|
+
玩法通过 `ctx.extension('inventory')` 取得同步模块。模块只在所属房间的 OS 沙箱内运行,不接触主站密钥、数据库连接或其他作品状态。每作品最多 16 个扩展;新安装只影响新房间,已有房间继续原版本。平台不会因为名字相似自动替换作品依赖。
|
|
119
|
+
|
|
120
|
+
`extension.json` 包含 `name/version/summary/entry/contract`。CLI 0.17 默认生成 `apiVersion:2`,`exports` 的每个方法声明 `args:[schema]` 和 `returns:schema`,运行时校验参数数量、类型、边界和返回值,禁止异步返回。schema 支持 string/number/integer/boolean/null/array/object,支持 minimum/maximum/maxLength/maxItems/items/properties/required/additionalProperties(false 或 schema);不支持引用和任意关键字。默认字符串上限4096字符、数组1024项、对象64项、深度8、每次输入和输出各64KiB。契约与源码一起锁定;接口语义改变应增加版本。`apiVersion:1` 仍是描述式契约,不追加类型校验。
|
|
121
|
+
|
|
122
|
+
这类校验不能证明业务算法正确,业务测试仍须随审核提供。公开共享需要明确许可和平台审核,支付、奖励、账号权限不能由不可信扩展自我批准。作者可执行 `wovoon extensions revoke <目录> --id <版本UUID> --reason <原因>` 撤销有问题的版本;代码和审计保留,停止下载、安装和新启动,平台定期检查并关闭已使用该版本的房间。已提交的业务事务不会自动撤销。开发者通过 status 查看原因,审核后安装新的不可变版本。
|
|
123
|
+
|
|
124
|
+
## 匹配与容量
|
|
125
|
+
|
|
126
|
+
新节点调度先预留可用容量再发送匹配结果,满载时继续排队。节点每3秒发布容量,失联超过12秒不接新房间;匹配名额等待首次入房最多60秒。现有房间按租约续期,旧实例不能继续写持久化数据。SDK `match(mode,{signal})` 可用 AbortSignal 取消本次等待;断线漏收通知时,每1.5秒查询平台保存的分配结果。这个恢复机制不等于无限保留房间,客户端应及时入房,并显示排队、重连和容量不足状态。
|
|
127
|
+
|
|
128
|
+
## 性能验收
|
|
129
|
+
|
|
130
|
+
分别记录输入确认延迟、服务器 tick 耗时/落后、发送队列、状态间隔、网络 RTT 和客户端帧时间。不能把 50 ms 发包间隔称为 50 ms 公网延迟。状态只发送需要的实体和字段,合理量化数值;大量实体需按玩家视野过滤。用相同场景和负载进行前后对照,再决定 tick、快照频率和容量。
|
|
@@ -0,0 +1,103 @@
|
|
|
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.16.0 提供以下命令(开发分支安装方式以交付说明为准,不能假定 npm 已发布):
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
wovoon ads init ./my-game
|
|
19
|
+
wovoon ads status ./my-game
|
|
20
|
+
wovoon ads plan ./my-game
|
|
21
|
+
wovoon ads apply ./my-game
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
先使用常规 `wovoon login` 登录**测试平台**,项目 `wovoon.config.json` 指定 `api: "https://dev.wovanshop.com"` 和已有作品 `appId`。首次作品先 `wovoon deploy` 创建作品,再配置奖励。作者令牌只保存在 CLI 凭据文件,不能放进游戏或广告配置。
|
|
25
|
+
|
|
26
|
+
在项目根创建 `wovoon.ads.json`,api、appId 必须与项目配置完全一致:
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"version": 1,
|
|
31
|
+
"api": "https://dev.wovanshop.com",
|
|
32
|
+
"appId": "替换为你拥有的测试作品ID",
|
|
33
|
+
"placements": [
|
|
34
|
+
{"placement":"revive","rewardKey":"life","rewardName":"复活机会","amount":1,"dailyLimit":10,"intervalSeconds":60,"enabled":true,"revision":0}
|
|
35
|
+
]
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`init` 根据已绑定的项目生成默认停用的 revive/life 规则,不访问网络,不覆盖现有文件。编辑成需要的奖励并启用后,`status` 读取云端当前值,`plan` 只预览新增/修改/保持不变,`apply` 才保存。新增用 revision:0;修改用 status 返回的 revision。apply 全部成功且本地文件未被并发编辑时,自动写回已确认的新 revision;部分成功或作者并发修改时保留原文件并提示核对。遇到并发冲突先核对差异,不要只提高 revision 强行覆盖。未列出的规则保持,停用需显式写 enabled:false。
|
|
40
|
+
|
|
41
|
+
应用是逐场景提交;中途失败会报告已确认保存的场景。网络超时可能已在服务器成功,先 status 核对后重试,不盲目重发。此文件不会被 CLI 打包进作品;它也不包含任何秘密。规则按现有作者权限 API 保存,无需广告联盟密钥。
|
|
42
|
+
|
|
43
|
+
## 作品端放置入口
|
|
44
|
+
|
|
45
|
+
在项目 `.wovoon` 声明 `{"protocol":1,"capabilities":["ads"]}`,与已有能力合并。HTML 页面只加载一次 `/api/cloud/sdk.js`;构建型项目也可以用 `new PolarisClient().ads`。
|
|
46
|
+
|
|
47
|
+
```html
|
|
48
|
+
<!-- 位置、按钮样式、文案由作品自己决定。 -->
|
|
49
|
+
<button id="revive" type="button" disabled>观看广告复活</button>
|
|
50
|
+
<p id="ad-status" role="status"></p>
|
|
51
|
+
<script src="/api/cloud/sdk.js"></script>
|
|
52
|
+
<script>
|
|
53
|
+
const button = document.getElementById('revive');
|
|
54
|
+
const status = document.getElementById('ad-status');
|
|
55
|
+
const ads = WovoonPolaris.ads;
|
|
56
|
+
ads.capabilities().then(caps => {
|
|
57
|
+
button.disabled = !caps.rewarded;
|
|
58
|
+
status.textContent = caps.surface === 'web'
|
|
59
|
+
? '激励广告仅移动端支持(当前为 Android App)'
|
|
60
|
+
: caps.rewarded ? '' : '激励广告暂不可用,请稍后再试。';
|
|
61
|
+
}).catch(() => { status.textContent = '激励广告暂不可用。'; });
|
|
62
|
+
button.onclick = async () => {
|
|
63
|
+
if (button.disabled) return;
|
|
64
|
+
button.disabled = true;
|
|
65
|
+
try {
|
|
66
|
+
const result = await ads.show({format:'rewarded', placement:'revive',
|
|
67
|
+
onPause: () => { /* 暂停游戏与声音 */ },
|
|
68
|
+
onResume: () => { /* 恢复游戏与声音 */ }
|
|
69
|
+
});
|
|
70
|
+
if (result.rewarded) {
|
|
71
|
+
const balances = await ads.rewardBalances();
|
|
72
|
+
// 用云端余额刷新你的界面,不能在本地再加1次。
|
|
73
|
+
status.textContent = '奖励已到账:' + JSON.stringify(balances);
|
|
74
|
+
} else if (result.requestId && ['REWARD_PENDING','REWARD_STATUS_UNAVAILABLE'].includes(result.reason)) {
|
|
75
|
+
// 按作品/玩家持久化 requestId,提供“查询到账”按钮。
|
|
76
|
+
// 玩家重试时 await ads.rewardStatus(result.requestId),granted 后刷新余额。
|
|
77
|
+
status.textContent = '奖励确认中,请稍后查询到账。';
|
|
78
|
+
} else status.textContent = '本次未获得奖励,可以继续游戏。';
|
|
79
|
+
} catch { status.textContent = '广告暂不可用,可以继续游戏。'; }
|
|
80
|
+
finally { button.disabled = false; }
|
|
81
|
+
};
|
|
82
|
+
</script>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Canvas、Unity、Godot 的按钮回调同样调用 `ads.show`,不要求使用 HTML 按钮。运行 `wovoon init my-ad-demo --template rewarded` 创建完整可运行的双入口示例;奖励消费与延迟回调的恢复规则见 [激励广告协议](../rewarded-ads.md)。原生 iOS 目前没有广告宿主,能力不可用时展示暂不支持提示。
|
|
86
|
+
|
|
87
|
+
## dev 验收
|
|
88
|
+
|
|
89
|
+
权威联机游戏把消费交给 `roomservers/<mode>.js`:收到玩家的购买/复活意图后校验玩法条件,再调用 `ctx.settle` 的 `rewardCost` 参数。不要将客户端 `rewarded:true`、余额截图、账号 ID 或自报消费金额当作权限。操作编号应绑定服务器生成的局次、玩家和本次业务事件,断线重试保持相同编号及内容。只有 COMPLETED 才生效;回执可能重复,玩法也须去重。见 [平台玩法配方](platform-game-mode.md#奖励消费与游戏结算)。
|
|
90
|
+
|
|
91
|
+
本地可以验证余额和事务,但不会模拟广告展示或伪造广告回调。把以下测试文件放在作品目录之外:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
[{"player":"Alice","rewardKey":"life","balance":7}]
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
wovoon dev ./my-game --player Alice --reward-fixture /absolute/outside-project/rewards.json
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
作品必须声明 ads,并启用默认持久化。种子只在该玩家/奖励首次出现时写入,重启不会补满;不能给 guest 注入余额。用两名玩家验证隔离、重复消费、余额不足、文档失败回滚及重启恢复。测试文件不会发布;真实 SSV 验收仍按下述流程执行。
|
|
102
|
+
|
|
103
|
+
先确认 CLI 目标与原生 App 都是 dev,作品声明 ads 且由你拥有。用 status 验证配置与奖励数量,再在普通网页验证移动端提示,在 Android dev App 验证两个自定义入口、取消/关闭、实际到账、重查不增发和消费重试不重扣。没有真实广告源时记录无填充;不能以假广告或模拟回调冒充通过。通过后再单独决定生产发布。
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# 激励广告与作品奖励(SDK 0.9.0)
|
|
2
|
+
|
|
3
|
+
奖励是每个作品、每个登录玩家独立的虚拟额度,例如复活次数、游戏金币。
|
|
4
|
+
它不会增加 Wovoon 平台积分、现金或创作者收益。没有服务器配置、未登录、没有广告源时跳过。
|
|
5
|
+
网页可以读取和使用已经到账的作品奖励,但目前不能加载激励广告;iOS 尚无此广告宿主。
|
|
6
|
+
|
|
7
|
+
## 创作者配置
|
|
8
|
+
|
|
9
|
+
推荐在 AI 开发/改造会话中使用 CLI 0.16.0 的 `wovoon ads init/status/plan/apply` 和项目 `wovoon.ads.json` 配置,无需创作者中心广告页面。`init` 生成默认停用的规则;`apply` 全部成功后自动保存确认的 revision,检测到作者并发修改时保留作者文件。完整流程与双入口示例见 [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,最小间隔 0–86400 秒(0 表示不限制间隔),奖励名称最多 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
|
+
在平台权威玩法中,用 `ctx.settle(operationId, writes, {playerId,rewardKey,amount})` 将奖励消费与 SERVER 存档/道具写入放入同一事务;不要先在客户端扣余额,再请求服务器发道具。玩家身份来自当前房间的有效登录租约,作品不能指定账号。新玩法先检查 `ctx.features?.rewardSettlement === 1`,旧运行时不支持时停止该操作,禁止退化成免费发放。完整示例见 [奖励消费与游戏结算](recipes/platform-game-mode.md#奖励消费与游戏结算)。
|
|
60
|
+
|
|
61
|
+
玩家端 `consumeReward` 的 `clientId` 不得使用平台保留的 `game_` 前缀。
|
|
62
|
+
|
|
63
|
+
玩家端 HTTP 为 POST `/api/cloud/{appIdOrDeploymentId}/ad-rewards/status|balances|consume`,
|
|
64
|
+
使用作品运行域 HttpOnly 租约 Cookie 和 Origin 校验。它们沿用云数据每玩家每进程
|
|
65
|
+
120 次/分钟限制;发奖和扣减幂等在 PostgreSQL 中跨进程生效。
|
|
66
|
+
|
|
67
|
+
## 平台开通和验收
|
|
68
|
+
|
|
69
|
+
GroMore 聚合位需开启服务端激励验证,HTTPS GET 回调:
|
|
70
|
+
`/api/public/ads/rewards/gromore`。每个环境应使用独立聚合位和 m-key,避免 dev/prod 回调串线。
|
|
71
|
+
只在后端 Secret 注入 `WOVOON_REWARD_SSV_ENABLED=true`、`WOVOON_REWARD_SSV_ENV=dev|prod`、
|
|
72
|
+
`WOVOON_REWARD_SSV_SLOT`、`WOVOON_REWARD_SSV_KEY`;缺任一配置默认不可用。
|
|
73
|
+
广告格式总开关及 rewarded 格式也必须开启,slot 必须与后端配置一致。
|
|
74
|
+
不得把 m-key 放入作品、APK、SDK、Git 或普通日志。
|
|
75
|
+
|
|
76
|
+
官方签名为 `SHA256(m-key + ":" + trans_id)`;回调还绑定服务器预签的环境、作品、玩家、
|
|
77
|
+
请求和奖励快照,交易 ID 唯一。事务将回执与余额一起写入,重复回调返回成功但不重复发奖。
|
|
78
|
+
本协议依赖 GroMore 的服务端事件语义,不把签名本身描述为完整观看或真人观看证明。
|
|
79
|
+
返回原始 `{"is_verify":true,"reason":0}`,不包裹平台 ApiResponse,并禁止缓存。
|
|
80
|
+
|
|
81
|
+
先在 dev 使用已授权测试作品/账号实际观看,核对 provider 回调、到账、重复回调、关闭/跳过、
|
|
82
|
+
断线恢复及扣减,再启用 prod。模拟签名和单元测试不能代替广告平台真实回调验收。
|
|
83
|
+
新广告联盟或新环境应独立完成验收;不能将已有联盟的通过结果泛化。已验收并启用的生产链路不因开发文档示例而关闭。
|
|
84
|
+
|
|
85
|
+
官方资料:[GroMore 服务端激励验证](https://www.csjplatform.com/supportcenter/26240)、
|
|
86
|
+
[Android 激励广告](https://www.csjplatform.com/supportcenter/28661)。
|
|
87
|
+
|
|
88
|
+
零间隔还需 Android 宿主支持,并将平台激励格式 minIntervalSeconds 配置为 0。旧版 App 最小值为 30 秒,应先升级宿主再启用;每日上限与同一时刻只展示一条广告不受影响。
|
package/docs/sdk.md
CHANGED
package/llms.txt
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# wovoon Polaris
|
|
2
2
|
|
|
3
|
-
> wovoon
|
|
3
|
+
> wovoon 提供统一游戏后台:身份、常驻权威玩法、实时同步、云存档和广告奖励;静态前端承载各个游戏模式。
|
|
4
4
|
> 本站文档面向 AI coding 工具与人类开发者,机器可执行、报错自带修复指引。
|
|
5
|
-
> 协议版本 1
|
|
5
|
+
> 协议版本 1。单机作品可先托管;多人玩法还需把权威状态和规则迁到常驻服务端模式,通过 SDK 发送输入、接收状态。上传本身不会自动让单机游戏变为多人游戏。
|
|
6
6
|
|
|
7
7
|
## 必读(按顺序)
|
|
8
8
|
|
|
@@ -20,9 +20,16 @@
|
|
|
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.16 的 ads init/status/plan/apply,作品自定义入口与奖励;网页提示仅移动端支持,Android 展示,服务端校验到账;权威玩法使用奖励消费与存档原子事务。
|
|
23
26
|
|
|
24
27
|
## 改造配方(存量程序 → wovoon)
|
|
25
28
|
|
|
29
|
+
- [统一购买与游戏权益](docs/recipes/game-commerce.md): CLI 配置商品、SDK 支付展示、到账恢复、权威权益核验、道具消费与存档事务;需要 SDK 0.10 / CLI 0.17 及对应平台运行时。
|
|
30
|
+
|
|
31
|
+
- [单机玩法 → Wovoon 游戏后台](docs/recipes/platform-game-mode.md): 常驻权威循环、60 Hz 可选节拍、插值/预测、恢复契约及私有/公共扩展;AI 先复用通用能力,再提炼缺少的模块。需要新版平台运行时。
|
|
32
|
+
|
|
26
33
|
- [静态网站加 manifest](docs/recipes/static-site-add-manifest.md): 零改造上架;声明能力即启用云能力。
|
|
27
34
|
- [localStorage → 云存档](docs/recipes/localstorage-to-cloud.md): 本地存档换成跨设备云集合,附逐行对照。
|
|
28
35
|
- [Express 后端 → wovoon 云能力](docs/recipes/express-to-cloud.md): 路由 → 集合/云函数 的映射策略(云函数为 M3 能力)。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wovoon/polaris",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
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 && node ../../scripts/sync-game-browser.mjs && node ../../scripts/sync-commerce-browser.mjs && node ../../scripts/sync-match-browser.mjs",
|
|
18
18
|
"check": "tsc --noEmit",
|
|
19
19
|
"prepack": "node ../../scripts/package-docs.mjs"
|
|
20
20
|
},
|