cocos-rewarded-ads-kit 1.0.0

package/README.md

@@ -0,0 +1,190 @@
+# Cocos Rewarded Ads Kit
+
+一个独立的、面向多个 Cocos Creator 项目的激励视频广告插件仓库。
+
+推荐先看：
+
+- [Quick Start](./docs/getting-started.md)
+- [设计稿](./docs/superpowers/specs/2026-03-29-cocos-rewarded-ads-kit-design.md)
+- [实现计划](./docs/superpowers/plans/2026-03-29-bootstrap-v1.md)
+
+## v1 范围
+
+- 只做激励视频
+- 支持按平台按需接入
+- 重点 provider / platform：
+  - Android AdMob
+  - iOS AdMob
+  - Android MAX
+  - iOS MAX
+  - Android TopOn
+  - iOS TopOn
+  - 微信小游戏
+  - 抖音小游戏
+
+## 当前目录结构
+
+```text
+packages/
+  core/
+  runtime/
+  adapter-wechat-mini-game/
+  adapter-douyin-mini-game/
+  adapter-android-admob/
+  adapter-ios-admob/
+  adapter-android-max/
+  adapter-ios-max/
+  adapter-android-topon/
+  adapter-ios-topon/
+  build-plugin/
+examples/
+  cocos-consumer/
+```
+
+## 业务侧目标用法
+
+```ts
+import { createPreparedRewardedAdsRuntime } from './build/rewarded-ads/generated/bootstrap-runtime.ts';
+
+const rewardedAds = createPreparedRewardedAdsRuntime({
+  platform: 'wechat-mini-game',
+});
+
+await rewardedAds.init();
+await rewardedAds.preload('reward_revive');
+
+const result = await rewardedAds.show('reward_revive');
+if (result.earned) {
+  // 发奖励
+}
+```
+
+## 配置文件
+
+每个接入项目维护一份 `ads.config.json`，按目标平台分别配置：
+
+- 微信小游戏 / 抖音小游戏：`adUnitId`
+- AdMob：`appId + adUnitId`
+- MAX：`sdkKey + adUnitId`
+- TopOn：`appId + appKey + adUnitId`
+
+### v1 provider 约束
+
+- 同一目标平台只允许一个 rewarded provider
+- 同一平台可以有多个 placement
+- 这些 placement 在 v1 中必须共用同一个 provider
+- 如果同平台混用 MAX / TopOn，build-plugin 会直接校验失败
+
+可参考：
+- [consumer example](./examples/cocos-consumer/README.md)
+- [android-admob example](./examples/android-admob/ads.config.json)
+- [ios-admob example](./examples/ios-admob/ads.config.json)
+- [wechat-mini-game example](./examples/wechat-mini-game/ads.config.json)
+- [douyin-mini-game example](./examples/douyin-mini-game/ads.config.json)
+- [android-max example](./examples/android-max/ads.config.json)
+- [ios-max example](./examples/ios-max/ads.config.json)
+- [android-topon example](./examples/android-topon/ads.config.json)
+- [ios-topon example](./examples/ios-topon/ads.config.json)
+
+## 当前实现进度
+
+已完成：
+- 核心类型与配置归一化
+- 运行时 facade 与 generated binding registry
+- provider 包入口与 runtime 工厂签名对齐
+- 微信小游戏 / 抖音小游戏 adapter
+- Android / iOS AdMob / MAX / TopOn native provider bridge 模板
+- build-plugin 平台选择、prepare CLI、Cocos build extension、bootstrap-runtime 生成
+- Android / iOS 宿主工程自动 patch
+- Cocos 项目消费者示例与接入文档
+
+仓库外仍需人工验收：
+- 使用真实 MAX / TopOn 凭据做一次 Android / iOS 最终构建
+- 在真实广告位上确认 preload / show / earned / cancelled 行为
+
+## npm 安装
+
+推荐在接入项目里直接安装发布包：
+
+```bash
+npm i -D cocos-rewarded-ads-kit@1.0.0
+```
+
+## 一键 prepare 命令
+
+安装后可直接用 CLI 生成当前平台广告产物：
+
+```bash
+npx cocos-rewarded-ads prepare --config ./ads.config.json --platform wechatgame --output ./build/rewarded-ads
+```
+
+可选参数：
+- `--extension-name`
+
+当前支持的平台参数：
+- `android`
+- `ios`
+- `wechatgame`
+- `bytedance-mini-game`
+
+## prepare 输出内容
+
+执行 `prepare:ads` 后，当前版本会生成这几类产物：
+
+- `generated/`
+  - `active-adapter.ts`
+  - `generated-rewarded-config.ts`
+  - `install-generated-bindings.ts`
+  - `bootstrap-runtime.ts`
+- `cocos-extension/`
+  - `package.json`
+  - `dist/main.js`
+  - `dist/builder.js`
+  - `dist/hooks.js`
+- `native/`（仅 Android / iOS）
+  - provider bridge 模板
+  - `RewardedAdsInstaller`
+  - provider config JSON
+  - 依赖片段
+  - AppActivity / AppDelegate 接入 snippet
+
+## 当前 native 输出说明
+
+Android / iOS 当前已经能生成：
+
+- provider bridge 模板
+- 统一 installer 入口
+- provider 配置文件
+- Gradle / Pod 依赖片段
+- 原生接入 snippet
+- 原生宿主工程 patch plan
+
+并且当前版本已经会在检测到宿主工程文件存在时，自动 patch：
+
+- Android
+  - `native/engine/android/app/build.gradle`
+  - `native/engine/android/app/src/**/AppActivity.java|kt`
+- iOS
+  - `native/engine/ios/Podfile.in`
+  - `native/engine/ios/CMakeLists.txt`
+  - `native/engine/ios/AppDelegate.mm`
+
+这意味着：
+
+- 微信小游戏 / 抖音小游戏已经接近可直接接入状态
+- Android / iOS 已经具备“生成 + 自动 patch”的基础闭环
+- provider SDK 的最终真机构建验收仍需要接入项目用真实凭据完成
+
+## 推荐接入姿势
+
+如果你是把这套能力接进一个新的 Cocos 项目，当前最稳的方式是：
+
+1. 在项目根目录维护 `ads.config.json`
+2. build 前执行 `cocos-rewarded-ads prepare`
+3. 在业务代码里只引入 `generated/bootstrap-runtime.ts`
+4. 用 placement 调用统一 runtime
+
+参考：
+
+- [Quick Start](./docs/getting-started.md)
+- [Cocos 项目接入示例](./examples/cocos-consumer/README.md)

package/ads.config.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["version", "placements"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "defaults": {
+      "type": "object",
+      "properties": {
+        "preloadOnInit": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "placements": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "android": {
+            "type": "object"
+          },
+          "ios": {
+            "type": "object"
+          },
+          "wechat-mini-game": {
+            "type": "object"
+          },
+          "douyin-mini-game": {
+            "type": "object"
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/bin/cocos-rewarded-ads.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+let main;
+
+try {
+  ({ main } = await import('../dist/packages/build-plugin/src/cli.js'));
+} catch {
+  ({ main } = await import('../packages/build-plugin/src/cli.ts'));
+}
+
+await main(process.argv.slice(2));

package/dist/packages/adapter-android-admob/src/index.d.ts

@@ -0,0 +1,2 @@
+import type { NativeRewardedRuntimeAdapterOptions } from '../../core/src/native-bridge.ts';
+export declare function createAdapter(options: NativeRewardedRuntimeAdapterOptions): import("../../core/src/types.ts").RewardedAdapter;

package/dist/packages/adapter-android-admob/src/index.js

@@ -0,0 +1,13 @@
+import { createNativeRewardedAdapter, createUnsupportedNativeRewardedAdapter, resolveNativeBridgeWrapper, } from "../../core/src/native-bridge.js";
+export function createAdapter(options) {
+    const wrapper = resolveNativeBridgeWrapper(options.wrapper);
+    if (!wrapper) {
+        return createUnsupportedNativeRewardedAdapter('android jsbBridgeWrapper is unavailable');
+    }
+    return createNativeRewardedAdapter({
+        provider: 'admob',
+        wrapper,
+        placements: options.config.placements,
+        timeoutMs: options.timeoutMs,
+    });
+}

package/dist/packages/adapter-android-max/src/index.d.ts

@@ -0,0 +1,2 @@
+import type { NativeRewardedRuntimeAdapterOptions } from '../../core/src/native-bridge.ts';
+export declare function createAdapter(options: NativeRewardedRuntimeAdapterOptions): import("../../core/src/types.ts").RewardedAdapter;

package/dist/packages/adapter-android-max/src/index.js

@@ -0,0 +1,13 @@
+import { createNativeRewardedAdapter, createUnsupportedNativeRewardedAdapter, resolveNativeBridgeWrapper, } from "../../core/src/native-bridge.js";
+export function createAdapter(options) {
+    const wrapper = resolveNativeBridgeWrapper(options.wrapper);
+    if (!wrapper) {
+        return createUnsupportedNativeRewardedAdapter('android jsbBridgeWrapper is unavailable');
+    }
+    return createNativeRewardedAdapter({
+        provider: 'max',
+        wrapper,
+        placements: options.config.placements,
+        timeoutMs: options.timeoutMs,
+    });
+}

package/dist/packages/adapter-android-topon/src/index.d.ts

@@ -0,0 +1,2 @@
+import type { NativeRewardedRuntimeAdapterOptions } from '../../core/src/native-bridge.ts';
+export declare function createAdapter(options: NativeRewardedRuntimeAdapterOptions): import("../../core/src/types.ts").RewardedAdapter;

package/dist/packages/adapter-android-topon/src/index.js

@@ -0,0 +1,13 @@
+import { createNativeRewardedAdapter, createUnsupportedNativeRewardedAdapter, resolveNativeBridgeWrapper, } from "../../core/src/native-bridge.js";
+export function createAdapter(options) {
+    const wrapper = resolveNativeBridgeWrapper(options.wrapper);
+    if (!wrapper) {
+        return createUnsupportedNativeRewardedAdapter('android jsbBridgeWrapper is unavailable');
+    }
+    return createNativeRewardedAdapter({
+        provider: 'topon',
+        wrapper,
+        placements: options.config.placements,
+        timeoutMs: options.timeoutMs,
+    });
+}

package/dist/packages/adapter-douyin-mini-game/src/index.d.ts

@@ -0,0 +1,15 @@
+import type { DouyinMiniGameApiLike, NormalizedRewardedAdsConfig, NormalizedPlatformPlacementConfig, RewardedAdapter, RewardedAdapterFactory } from '../../core/src/types.ts';
+interface DouyinAdapterOptions {
+    ttApi?: DouyinMiniGameApiLike | null;
+    placements: Record<string, NormalizedPlatformPlacementConfig>;
+    showTimeoutMs?: number;
+}
+export declare function createDouyinMiniGameRewardedAdapter(options: DouyinAdapterOptions): RewardedAdapter;
+export declare const createRuntimeAdapter: RewardedAdapterFactory;
+export declare function createAdapter(options: DouyinAdapterOptions | {
+    platform: NormalizedRewardedAdsConfig['platform'];
+    config: NormalizedRewardedAdsConfig;
+    ttApi?: DouyinMiniGameApiLike | null;
+    showTimeoutMs?: number;
+}): RewardedAdapter;
+export {};

package/dist/packages/adapter-douyin-mini-game/src/index.js

@@ -0,0 +1,134 @@
+function createError(code, message, cause) {
+    return { code, message, cause };
+}
+function createErrorResult(error) {
+    return {
+        completed: false,
+        cancelled: false,
+        earned: false,
+        error,
+    };
+}
+function toResult(result) {
+    if (!result || typeof result.isEnded !== 'boolean') {
+        return {
+            completed: true,
+            cancelled: false,
+            earned: true,
+        };
+    }
+    return {
+        completed: true,
+        cancelled: !result.isEnded,
+        earned: !!result.isEnded,
+    };
+}
+export function createDouyinMiniGameRewardedAdapter(options) {
+    const showTimeoutMs = Math.max(1, options.showTimeoutMs ?? 15000);
+    const ads = new Map();
+    const states = new Map();
+    const getAd = (placement) => {
+        const placementConfig = options.placements[placement];
+        if (!placementConfig) {
+            return { ad: null, error: createError('configInvalid', `${placement} config is unavailable`) };
+        }
+        if (!options.ttApi) {
+            return { ad: null, error: createError('unsupported', `${placement} tt api is unavailable`) };
+        }
+        const cached = ads.get(placement);
+        if (cached) {
+            return { ad: cached, error: null };
+        }
+        const ad = options.ttApi.createRewardedVideoAd({ adUnitId: placementConfig.adUnitId });
+        ads.set(placement, ad);
+        return { ad, error: null };
+    };
+    return {
+        async init() {
+            return undefined;
+        },
+        async preload(placement) {
+            const { ad, error } = getAd(placement);
+            if (!ad) {
+                states.set(placement, 'unsupported');
+                throw error;
+            }
+            states.set(placement, 'loading');
+            if (typeof ad.load === 'function') {
+                await ad.load();
+            }
+            states.set(placement, 'ready');
+        },
+        async show(placement) {
+            const { ad, error } = getAd(placement);
+            if (!ad) {
+                states.set(placement, 'unsupported');
+                return createErrorResult(error);
+            }
+            states.set(placement, 'showing');
+            return await new Promise((resolve) => {
+                let settled = false;
+                const settle = (result) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    clearTimeout(timer);
+                    states.set(placement, 'idle');
+                    if (typeof ad.offClose === 'function') {
+                        ad.offClose(handleClose);
+                    }
+                    if (typeof ad.offError === 'function') {
+                        ad.offError(handleError);
+                    }
+                    resolve(result);
+                };
+                const handleClose = (result) => settle(toResult(result));
+                const handleError = (cause) => settle(createErrorResult(createError('showFailed', `${placement} show failed`, cause)));
+                const timer = setTimeout(() => settle(createErrorResult(createError('timeout', `${placement} show timed out`))), showTimeoutMs);
+                if (typeof ad.onClose === 'function') {
+                    ad.onClose(handleClose);
+                }
+                if (typeof ad.onError === 'function') {
+                    ad.onError(handleError);
+                }
+                Promise.resolve(typeof ad.show === 'function' ? ad.show() : undefined)
+                    .catch((cause) => settle(createErrorResult(createError('showFailed', `${placement} show failed`, cause))));
+            });
+        },
+        isReady(placement) {
+            return states.get(placement) === 'ready';
+        },
+        getState(placement) {
+            return states.get(placement) ?? 'idle';
+        },
+        reset(placement) {
+            if (placement) {
+                ads.delete(placement);
+                states.delete(placement);
+                return;
+            }
+            ads.clear();
+            states.clear();
+        },
+    };
+}
+function resolveDouyinApi(override) {
+    if (override) {
+        return override;
+    }
+    return globalThis.tt ?? null;
+}
+export const createRuntimeAdapter = (options) => {
+    return createDouyinMiniGameRewardedAdapter({
+        ttApi: resolveDouyinApi(options.ttApi),
+        placements: options.config.placements,
+        showTimeoutMs: options.showTimeoutMs,
+    });
+};
+export function createAdapter(options) {
+    if ('placements' in options) {
+        return createDouyinMiniGameRewardedAdapter(options);
+    }
+    return createRuntimeAdapter(options);
+}

package/dist/packages/adapter-ios-admob/src/index.d.ts

@@ -0,0 +1,2 @@
+import type { NativeRewardedRuntimeAdapterOptions } from '../../core/src/native-bridge.ts';
+export declare function createAdapter(options: NativeRewardedRuntimeAdapterOptions): import("../../core/src/types.ts").RewardedAdapter;

package/dist/packages/adapter-ios-admob/src/index.js

@@ -0,0 +1,13 @@
+import { createNativeRewardedAdapter, createUnsupportedNativeRewardedAdapter, resolveNativeBridgeWrapper, } from "../../core/src/native-bridge.js";
+export function createAdapter(options) {
+    const wrapper = resolveNativeBridgeWrapper(options.wrapper);
+    if (!wrapper) {
+        return createUnsupportedNativeRewardedAdapter('ios jsbBridgeWrapper is unavailable');
+    }
+    return createNativeRewardedAdapter({
+        provider: 'admob',
+        wrapper,
+        placements: options.config.placements,
+        timeoutMs: options.timeoutMs,
+    });
+}

package/dist/packages/adapter-ios-max/src/index.d.ts

@@ -0,0 +1,2 @@
+import type { NativeRewardedRuntimeAdapterOptions } from '../../core/src/native-bridge.ts';
+export declare function createAdapter(options: NativeRewardedRuntimeAdapterOptions): import("../../core/src/types.ts").RewardedAdapter;

package/dist/packages/adapter-ios-max/src/index.js

@@ -0,0 +1,13 @@
+import { createNativeRewardedAdapter, createUnsupportedNativeRewardedAdapter, resolveNativeBridgeWrapper, } from "../../core/src/native-bridge.js";
+export function createAdapter(options) {
+    const wrapper = resolveNativeBridgeWrapper(options.wrapper);
+    if (!wrapper) {
+        return createUnsupportedNativeRewardedAdapter('ios jsbBridgeWrapper is unavailable');
+    }
+    return createNativeRewardedAdapter({
+        provider: 'max',
+        wrapper,
+        placements: options.config.placements,
+        timeoutMs: options.timeoutMs,
+    });
+}

package/dist/packages/adapter-ios-topon/src/index.d.ts

@@ -0,0 +1,2 @@
+import type { NativeRewardedRuntimeAdapterOptions } from '../../core/src/native-bridge.ts';
+export declare function createAdapter(options: NativeRewardedRuntimeAdapterOptions): import("../../core/src/types.ts").RewardedAdapter;

package/dist/packages/adapter-ios-topon/src/index.js

@@ -0,0 +1,13 @@
+import { createNativeRewardedAdapter, createUnsupportedNativeRewardedAdapter, resolveNativeBridgeWrapper, } from "../../core/src/native-bridge.js";
+export function createAdapter(options) {
+    const wrapper = resolveNativeBridgeWrapper(options.wrapper);
+    if (!wrapper) {
+        return createUnsupportedNativeRewardedAdapter('ios jsbBridgeWrapper is unavailable');
+    }
+    return createNativeRewardedAdapter({
+        provider: 'topon',
+        wrapper,
+        placements: options.config.placements,
+        timeoutMs: options.timeoutMs,
+    });
+}

package/dist/packages/adapter-wechat-mini-game/src/index.d.ts

@@ -0,0 +1,15 @@
+import type { NormalizedRewardedAdsConfig, NormalizedPlatformPlacementConfig, RewardedAdapter, RewardedAdapterFactory, WeChatMiniGameApiLike } from '../../core/src/types.ts';
+interface WeChatAdapterOptions {
+    wxApi?: WeChatMiniGameApiLike | null;
+    placements: Record<string, NormalizedPlatformPlacementConfig>;
+    showTimeoutMs?: number;
+}
+export declare function createWeChatMiniGameRewardedAdapter(options: WeChatAdapterOptions): RewardedAdapter;
+export declare const createRuntimeAdapter: RewardedAdapterFactory;
+export declare function createAdapter(options: WeChatAdapterOptions | {
+    platform: NormalizedRewardedAdsConfig['platform'];
+    config: NormalizedRewardedAdsConfig;
+    wxApi?: WeChatMiniGameApiLike | null;
+    showTimeoutMs?: number;
+}): RewardedAdapter;
+export {};

package/dist/packages/adapter-wechat-mini-game/src/index.js

@@ -0,0 +1,134 @@
+function createError(code, message, cause) {
+    return { code, message, cause };
+}
+function createErrorResult(error) {
+    return {
+        completed: false,
+        cancelled: false,
+        earned: false,
+        error,
+    };
+}
+function toResult(result) {
+    if (!result || typeof result.isEnded !== 'boolean') {
+        return {
+            completed: true,
+            cancelled: false,
+            earned: true,
+        };
+    }
+    return {
+        completed: true,
+        cancelled: !result.isEnded,
+        earned: !!result.isEnded,
+    };
+}
+export function createWeChatMiniGameRewardedAdapter(options) {
+    const showTimeoutMs = Math.max(1, options.showTimeoutMs ?? 15000);
+    const ads = new Map();
+    const states = new Map();
+    const getAd = (placement) => {
+        const placementConfig = options.placements[placement];
+        if (!placementConfig) {
+            return { ad: null, error: createError('configInvalid', `${placement} config is unavailable`) };
+        }
+        if (!options.wxApi) {
+            return { ad: null, error: createError('unsupported', `${placement} wx api is unavailable`) };
+        }
+        const cached = ads.get(placement);
+        if (cached) {
+            return { ad: cached, error: null };
+        }
+        const ad = options.wxApi.createRewardedVideoAd({ adUnitId: placementConfig.adUnitId });
+        ads.set(placement, ad);
+        return { ad, error: null };
+    };
+    return {
+        async init() {
+            return undefined;
+        },
+        async preload(placement) {
+            const { ad, error } = getAd(placement);
+            if (!ad) {
+                states.set(placement, 'unsupported');
+                throw error;
+            }
+            states.set(placement, 'loading');
+            if (typeof ad.load === 'function') {
+                await ad.load();
+            }
+            states.set(placement, 'ready');
+        },
+        async show(placement) {
+            const { ad, error } = getAd(placement);
+            if (!ad) {
+                states.set(placement, 'unsupported');
+                return createErrorResult(error);
+            }
+            states.set(placement, 'showing');
+            return await new Promise((resolve) => {
+                let settled = false;
+                const settle = (result) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    clearTimeout(timer);
+                    states.set(placement, 'idle');
+                    if (typeof ad.offClose === 'function') {
+                        ad.offClose(handleClose);
+                    }
+                    if (typeof ad.offError === 'function') {
+                        ad.offError(handleError);
+                    }
+                    resolve(result);
+                };
+                const handleClose = (result) => settle(toResult(result));
+                const handleError = (cause) => settle(createErrorResult(createError('showFailed', `${placement} show failed`, cause)));
+                const timer = setTimeout(() => settle(createErrorResult(createError('timeout', `${placement} show timed out`))), showTimeoutMs);
+                if (typeof ad.onClose === 'function') {
+                    ad.onClose(handleClose);
+                }
+                if (typeof ad.onError === 'function') {
+                    ad.onError(handleError);
+                }
+                Promise.resolve(typeof ad.show === 'function' ? ad.show() : undefined)
+                    .catch((cause) => settle(createErrorResult(createError('showFailed', `${placement} show failed`, cause))));
+            });
+        },
+        isReady(placement) {
+            return states.get(placement) === 'ready';
+        },
+        getState(placement) {
+            return states.get(placement) ?? 'idle';
+        },
+        reset(placement) {
+            if (placement) {
+                ads.delete(placement);
+                states.delete(placement);
+                return;
+            }
+            ads.clear();
+            states.clear();
+        },
+    };
+}
+function resolveWeChatApi(override) {
+    if (override) {
+        return override;
+    }
+    return globalThis.wx ?? null;
+}
+export const createRuntimeAdapter = (options) => {
+    return createWeChatMiniGameRewardedAdapter({
+        wxApi: resolveWeChatApi(options.wxApi),
+        placements: options.config.placements,
+        showTimeoutMs: options.showTimeoutMs,
+    });
+};
+export function createAdapter(options) {
+    if ('placements' in options) {
+        return createWeChatMiniGameRewardedAdapter(options);
+    }
+    return createRuntimeAdapter(options);
+}