Cocos Rewarded Ads Kit

一个独立的、面向多个 Cocos Creator 项目的激励视频广告插件仓库。

推荐先看：

• Quick Start
• 设计稿
• 实现计划

v1 范围

• 只做激励视频
• 支持按平台按需接入
• 重点 provider / platform：
  • Android AdMob
  • iOS AdMob
  • Android MAX
  • iOS MAX
  • Android TopOn
  • iOS TopOn
  • 微信小游戏
  • 抖音小游戏

当前目录结构

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/

业务侧目标用法

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
• android-admob example
• ios-admob example
• wechat-mini-game example
• douyin-mini-game example
• android-max example
• ios-max example
• android-topon example
• ios-topon example

当前实现进度

已完成：

• 核心类型与配置归一化
• 运行时 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 安装

推荐在接入项目里直接安装发布包：

npm i -D [email protected]

一键 prepare 命令

安装后可直接用 CLI 生成当前平台广告产物：

npx cocos-rewarded-ads prepare --config ./ads.config.json --platform wechatgame --output ./build/rewarded-ads

可选参数：

• --extension-name：指定生成的 Cocos 扩展插件名。

  注意（多项目场景）：如果你同时在同一个 Cocos Creator 实例中打开多个接入了本组件的项目， 每个项目必须使用不同的 --extension-name，否则扩展名冲突会导致其中一个项目的 hooks 不生效。 例如：

  npx cocos-rewarded-ads prepare --config ./ads.config.json --platform android \
    --output ./build/android --extension-name my-game-rewarded-ads-build

当前支持的平台参数：

• 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
• Cocos 项目接入示例

已知限制与注意事项

Android：自定义 Activity 包名

本组件在自动 patch AppActivity 时，默认假定 Cocos 生成的 Activity 位于标准路径：

native/engine/android/app/src/com/cocos/game/AppActivity.java|kt

如果你修改过 Android 项目的包名（不再使用 com.cocos.game），自动注入会被跳过，并在构建日志中输出警告。此时需要手动在你的 AppActivity 中添加：

// onCreate
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    RewardedAdsInstaller.install(this)   // ← 添加这行
}

// onDestroy
override fun onDestroy() {
    super.onDestroy()
    RewardedAdsInstaller.reset()         // ← 添加这行
}

import com.tinivo.rewardedads.RewardedAdsInstaller 也需要一并引入。

非 macOS 环境（Windows / Linux CI）：引擎路径

在 macOS 上，build-plugin 会自动从 /Applications/Cocos/Creator/ 推断引擎路径。

在 Windows 上，它会尝试从 %LOCALAPPDATA%\cocos\Creator\ 推断。

如果自动推断失败（引擎安装在非标准路径，或在 Linux CI 上），请显式设置环境变量：

export COCOS_ENGINE_PATH=/path/to/CocosCreator/resources/3d/engine/native
npx cocos-rewarded-ads prepare ...

或者将路径写入构建输出目录的 proj/gradle.properties：

COCOS_ENGINE_PATH=/path/to/engine/native