# Cocos Rewarded Ads Kit 接入指南

这份文档只说明一件事：怎样把 `cocos-rewarded-ads-kit` 接进一个新的 Cocos Creator 项目。

## 1. 安装

在 Cocos 项目根目录执行：

```bash
npm i -D cocos-rewarded-ads-kit@1.0.1
```

## 2. 新建 `ads.config.json`

在项目根目录放一份 `ads.config.json`。

按你实际要接的 provider 选一种配置方式。

### 微信小游戏 / 抖音小游戏示例

```json
{
  "version": 1,
  "defaults": {
    "preloadOnInit": ["reward_revive"]
  },
  "placements": {
    "reward_revive": {
      "wechat-mini-game": {
        "provider": "wechat",
        "adUnitId": "YOUR_WECHAT_REWARDED_ID"
      },
      "douyin-mini-game": {
        "provider": "douyin",
        "adUnitId": "YOUR_DOUYIN_REWARDED_ID"
      }
    }
  }
}
```

### AdMob 示例

```json
{
  "version": 1,
  "defaults": {
    "preloadOnInit": ["reward_revive"]
  },
  "placements": {
    "reward_revive": {
      "android": {
        "provider": "admob",
        "appId": "YOUR_ANDROID_ADMOB_APP_ID",
        "adUnitId": "YOUR_ANDROID_REWARDED_ID"
      },
      "ios": {
        "provider": "admob",
        "appId": "YOUR_IOS_ADMOB_APP_ID",
        "adUnitId": "YOUR_IOS_REWARDED_ID"
      }
    }
  }
}
```

### MAX 示例

```json
{
  "version": 1,
  "defaults": {
    "preloadOnInit": ["reward_revive"]
  },
  "placements": {
    "reward_revive": {
      "android": {
        "provider": "max",
        "sdkKey": "YOUR_MAX_SDK_KEY",
        "adUnitId": "YOUR_ANDROID_MAX_REWARDED_ID"
      },
      "ios": {
        "provider": "max",
        "sdkKey": "YOUR_MAX_SDK_KEY",
        "adUnitId": "YOUR_IOS_MAX_REWARDED_ID"
      }
    }
  }
}
```

### TopOn 示例

```json
{
  "version": 1,
  "defaults": {
    "preloadOnInit": ["reward_revive"]
  },
  "placements": {
    "reward_revive": {
      "android": {
        "provider": "topon",
        "appId": "YOUR_ANDROID_TOPON_APP_ID",
        "appKey": "YOUR_ANDROID_TOPON_APP_KEY",
        "adUnitId": "YOUR_ANDROID_TOPON_REWARDED_ID"
      },
      "ios": {
        "provider": "topon",
        "appId": "YOUR_IOS_TOPON_APP_ID",
        "appKey": "YOUR_IOS_TOPON_APP_KEY",
        "adUnitId": "YOUR_IOS_TOPON_REWARDED_ID"
      }
    }
  }
}
```

字段要求：

- AdMob：`appId` + `adUnitId`
- MAX：`sdkKey` + `adUnitId`
- TopOn：`appId` + `appKey` + `adUnitId`
- 微信小游戏 / 抖音小游戏：`adUnitId`

## 3. 生成当前平台接入产物

默认方式是手动执行：

```bash
npx cocos-rewarded-ads prepare --config ./ads.config.json --platform android --output ./build/rewarded-ads
```

如果项目里已经接入了 `cocos-rewarded-ads-build` 这类 Cocos Creator build extension，那么点击 Creator 的 `Build` 时会自动执行这一步，不需要再手动跑命令。

支持的平台参数：

- `android`
- `ios`
- `wechatgame`
- `bytedance-mini-game`

## 4. 在业务代码里接 runtime

在游戏代码里引入生成后的 runtime：

```ts
import { createPreparedRewardedAdsRuntime } from './build/rewarded-ads/generated/bootstrap-runtime.ts';

const rewardedAds = createPreparedRewardedAdsRuntime({
  platform: 'android',
});

await rewardedAds.init();
await rewardedAds.preload('reward_revive');

const result = await rewardedAds.show('reward_revive');
if (result.earned) {
  // 发奖励
}
```

运行时 `platform` 可用值：

- `android`
- `ios`
- `wechat-mini-game`
- `douyin-mini-game`

## 5. placement 命名建议

placement 直接按业务奖励场景命名：

- `reward_revive`
- `reward_extra_ball`
- `reward_daily_bonus`

不要把 provider 名写进 placement。

## 6. 两条必须知道的规则

- 同一个目标平台下，所有 placement 必须共用同一个 rewarded provider
- Android / iOS 执行 `prepare` 后，会同时生成并补齐原生接入文件；导出宿主工程后重新编译即可