# 迁移到 Android 的奖励广告单元 API

> 通过初始化 SDK、创建具有广告单元 ID 的奖励广告对象以及实现广告事件的监听器，迁移到 LevelPlay 奖励广告单元 API。

本指南介绍如何从 SDK 9.0.0 版本开始集成 LevelPlay API，使用广告单元 ID 作为瀑布流标识符来加载和显示奖励广告服务。

> **Important:**
>
> 使用本文中介绍的 API，而不是当前使用的集成方法（IronSource init、IronSource 加载奖励、奖励监听器）。您可以在 **API 比较** 部分中找到 API 替换。
>
> [高级设置](/grow/levelplay/sdk/unity/additional-settings.md.md)和[法规设置](/grow/levelplay/sdk/unity/regulation-advanced-settings.md.md)没有更改，在初始化 LevelPlay SDK 之前或之后支持这些设置和设置。

## 在 LevelPlay 平台中找到广告单元 ID

要加载和显示奖励广告服务，需要使用 LevelPlay 聚合平台中的广告单元 ID：

1. 在 LevelPlay 帐户中，导航到 **Setup** > **Ad Units**。
2. 复制奖励的广告单元 ID 并将其集成到代码中。

## 初始化 LevelPlay SDK##initializing-the-levelplay-sdk

要初始化 LevelPlay SDK，请执行以下步骤：

1. 实现初始化成功和失败的回调。
2. 使用 appKey 和用户 ID（如果相关）调用 LevelPlay init API。

1) **Java**

   ```java
   LevelPlayInitRequest initRequest = new LevelPlayInitRequest.Builder(appKey)
     .withUserId("UserID")
     .build();
   LevelPlayInitListener initListener = new LevelPlayInitListener() { }
     @Override
     public void onInitFailed(@NonNull LevelPlayInitError 报错) {
     @Override
     public void onInitSuccess(LevelPlayConfiguration configuration) {
   };
   LevelPlay.init(context, initRequest, initListener);
   ```

2) **Kotlin**

   ```kotlin
   val initRequest = LevelPlayInitRequest.Builder("AppKey")
     .withUserId("UserId")
     .build()
   LevelPlay.init(context, initRequest, object :LevelPlayInitListener {
     覆盖 fun onInitSuccess(configuration:LevelPlayConfiguration) {}
     覆盖 fun onInitFailed（报错：LevelPlayInitError) {
   })
   ```

### LevelPlay 初始化监听器##levelplay-init-listeners

**onInitSuccess**：初始化成功完成时触发。收到此指示后，您可以创建和加载广告。

**onInitFailed**：未成功检索配置，无法加载广告服务。建议稍后尝试并初始化 LevelPlay SDK（当互联网连接可用或故障原因得到解决时）。

| 初始化 | 旧版                       | 广告单元（新）        |
| :-- | :----------------------- | :------------- |
| API | IronSource.init          | LevelPlay.init |
| 回调  | onInitializationComplete | onInitSuccess  |
|     | –                        | onInitFailed   |

## **创建奖励广告对象**##**create-rewarded-ad-object**

必须在收到 **onInitSuccess** 回调后执行奖励广告对象的创建。

该对象是可重用的实例，可以处理多个加载并在整个会话中显示。创建后，应使用 来加载和展示同一广告单元的广告服务。

对于更高级的实现，如有必要，您可以创建多个奖励广告对象。

1. **Java**

   ```java
   // 创建奖励广告
   mRewardedAd = new LevelPlayRewardedAd("adUnitId");
   ```

2. **Kotlin**

   ```kotlin
   // 创建奖励广告
   mRewardedAd = LevelPlayRewardedAd("adUnitId")
   ```

## 注册到奖励事件##register-to-rewarded-events

为创建的奖励广告单元设置奖励监听器，以便了解广告投放情况。

* 建议在加载奖励广告之前设置监听器。
* 每个奖励广告都应有自己的监听器实现。
* 回调在主线程上运行。

1. **Java**

   ```java
   // 创建奖励广告
   mRewardedAd = new LevelPlayRewardedAd("adUnitId");
   // 设置监听器
   mRewardedAd.setListener(this);

   // LevelPlayRewardedAdListener methods
   @Override
   public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdLoadFailed(@NonNull LevelPlayAdError error) {}
   @Override
   public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdDisplayFailed(@NonNull LevelPlayAdError error, @NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {}
   ```

2. **Kotlin**

   ```kotlin
   // 创建奖励广告
   mRewardedAd = LevelPlayRewardedAd("adUnitId") 
   // 设置监听器
   mRewardedAd.setListener(this)
   // LevelPlayRewardedAdListener 方法
   覆盖 fun onAdLoaded(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdLoadFailed（报错：LevelPlayAdError) {}
   覆盖 fun onAdInfoChanged(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdDisplayed(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdDisplayFailed（报错：LevelPlayAdError、adInfo：LevelPlayAdInfo) {}
   覆盖 fun onAdClicked(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdClosed(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdRewarded(奖励：LevelPlayReward、adInfo：LevelPlayAdInfo) {}
   ```

### LevelPlay 奖励广告回调##levelplay-rewarded-ad-callbacks

**onAdLoaded**：成功加载广告时提供。

**onAdLoadFailed**：在广告加载失败时提供。包含广告单元信息。

**onAdDisplayed**：在显示广告时提供。这相当于展示。

**onAdDisplayFailed**：广告无法显示时提供。

**onAdRewarded**：在广告获得奖励时提供。其中包含广告单元信息和奖励信息。

**onAdClicked**（可选）：在用户点击广告时提供。

**onAdClosed**：在广告关闭时提供。

**onAdInfoChanged**（可选）：在更新广告信息时提供。加载另一个广告后可用，并且包含更高的 CPM/速率。

| 组件  | 旧版                            | 广告单元（新）             |
| --- | ----------------------------- | ------------------- |
| 监听器 | IronSourceRewardedVideoEvents | LevelPlayRewardedAd |
| 回调  | onAdReady                     | onAdLoaded          |
|     | onAdLoadFailed                | onAdLoadFailed      |
|     | onAdOpened                    | onAdDisplayed       |
|     | onAdClosed                    | onAdClosed          |
|     | onAdShowFailed                | onAdDisplayFailed   |
|     | onAdRewarded                  | onAdRewarded        |
|     | onAdClicked                   | onAdClicked         |
|     | onAdShowSucceeded             | n/a（已弃用）            |
|     | n/a                           | onAdInfoChanged     |

## 加载奖励广告##load-rewarded-ad

收到 **onInitSuccess** 回调后，即可加载奖励广告。应使用 方法执行此操作：

1. **Java**

   ```java
   // 加载或重新加载广告
   mRewardedAd.loadAd();
   ```

2. **Kotlin**

   ```kotlin
   // 加载或重新加载广告
   mRewardedAd.loadAd()
   ```

## **显示奖励广告**##**show-rewarded-ad**

您可以在收到 **onAdLoaded** 回调后使用 **showAd** API 展示奖励广告。
如果使用[广告位](/grow/levelplay/platform/settings/placements.md)，请将广告位名称作为 API 的一部分共享，如下所示。

1. **Java**

   ```java
   // 显示广告而不放置/位置 
   mRewardedAd.showAd(this);
   // 显示带有放置/位置的广告 
   mRewardedAd.showAd(this, placementName);
   ```

2. **Kotlin**

   ```kotlin
   // 显示广告而不放置/位置 
   mRewardedAd.showAd(this)
   // 显示带有放置/位置的广告 
   mRewardedAd.showAd(this, placementName)
   ```

### 检查 Ad is Ready##check-ad-is-ready

为了避免展示失败，并确保广告可以正确展示，建议在调用 **showAd** API 之前使用以下 API。

**isAdReady** – 如果广告已成功加载且广告单元未设置上限，则返回 true，否则返回 false。

**isPlacementCapped** – 有效放置/位置被限制时返回 true。如果放置/位置无效或未设置上限，此 API 将返回 false。

1. **Java**

   ```java
   // 检查广告是否已准备就绪并且放置/位置未设置上限 
   if(mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {
       mRewardedAd.showAd(this, placementName);
   }
   ```

2. **Kotlin**

   ```kotlin
   // 检查广告是否已准备就绪并且放置/位置未设置上限 
   if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {
       mRewardedAd.showAd(this, placementName)
   }
   ```

当广告成功展示给玩家时，您可以加载另一个广告，重复加载奖励广告步骤。一时间加载单个广告时，无需创建新的广告实体。

## 奖励用户##reward-the-user

LevelPlay SDK 将在用户每次成功完成视频时触发 **onAdRewarded**。

**onAdRewarded** 和 **onAdClosed** 是异步的。确保设置监听器以提供奖励，即使 **onAdRewarded** 在 **onAdClosed** 之后被触发也是如此。

1. **Java**

   ```java
   @Override
   public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) { }
     // 实现向用户授予奖励的逻辑
     字符串 name = reward.getName();
     int amount = reward.getAmount();
   }
   ```

2. **Kotlin**

   ```kotlin
   覆盖 fun onAdRewarded(奖励：LevelPlayReward、adInfo：LevelPlayAdInfo) {
     // 实现向用户授予奖励的逻辑
     值名称：字符串 = reward.name
     val amount：Int = reward.amount
   }
   ```

## 多个广告单元奖励 API##multiple-ad-unit-rewarded-apis

| 组件  | 旧版                             | 广告单元（新）             |
| --- | ------------------------------ | ------------------- |
| 类   | IronSource                     | LevelPlayRewardedAd |
| API | loadRewardedVideo              | loadAd              |
|     | showRewardedVideo              | showAd              |
|     | isRewardedVideoPlacementCapped | isPlacementCapped   |
|     | isRewardedVideoAvailable       | isAdReady           |
|     | placement.getRewardName        | reward.name         |
|     | placement.getRewardAmount      | reward.amount       |

## 奖励广告的完整实现示例##full-implementation-example-of-rewarded-ad

1. **Java**

   ```java
   public 类 RewardedAdActivity extends 活动实现 LevelPlayRewardedAdListener {
     私有变量 LevelPlayRewardedAd mRewardedAd;
     void createRewardedAd() {
       mRewardedAd = new LevelPlayRewardedAd("adUnitId");
       mRewardedAd.setListener(this);
     }
     void loadRewardedAd() {
       // 加载或重新加载广告
       mRewardedAd.loadAd();
     }
     void showRewardedAd() {
       if (mRewardedAd.isAdReady()) {
         mRewardedAd.showAd(this);
       }
     }
     void showRewardedAd(@NonNull 字符串 placementName) {
       // 检查广告是否已准备就绪并且放置/位置未设置上限
       if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {
         mRewardedAd.showAd(this, placementName);
       }
     }
     // LevelPlayRewardedAdListener 方法
     @Override
     public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {}
     @Override
     public void onAdLoadFailed(@NonNull LevelPlayAdError 报错) {
     @Override
     public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {}
     @Override
     public void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {
     @Override
     public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {
     @Override
     public void onAdDisplayFailed(@NonNull LevelPlayAdError 报错, @NonNull LevelPlayAdInfo adInfo) {
     @Override
     public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {
     @Override
     public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {
   }
   ```

2. **Kotlin**

   ```kotlin
   类 RewardedAdActivity：Activity(), LevelPlayRewardedAdListener {
   私有变量 lateinit var mRewardedAd：LevelPlayRewardedAd
   fun createRewardedAd() {
       mRewardedAd = LevelPlayRewardedAd("adUnitId")
       mRewardedAd.setListener(this)
   }
   fun loadRewardedAd() {
       mRewardedAd.loadAd()
   }
   fun showRewardedAd() {
       if (mRewardedAd.isAdReady()) {
           mRewardedAd.showAd(this)
       }
   }
   fun showRewardedAd(placementName:字符串) {
       // 检查广告是否已准备就绪并且放置/位置未设置上限 
       if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {
           mRewardedAd.showAd(this, placementName)
       }
   }
   // LevelPlayRewardedAdListener 方法
   覆盖 fun onAdLoaded(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdLoadFailed（报错：LevelPlayAdError) {}
   覆盖 fun onAdInfoChanged(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdDisplayed(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdDisplayFailed（报错：LevelPlayAdError、adInfo：LevelPlayAdInfo) {}
   覆盖 fun onAdClicked(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdClosed(adInfo:LevelPlayAdInfo) {}
   覆盖 fun onAdRewarded(奖励：LevelPlayReward、adInfo：LevelPlayAdInfo) {}
   }
   ```