# 迁移到 Unity 的奖励广告单元 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. 定义要在会话中初始化的广告格式列表。这应包括要使用非多个广告单元 API 的所有广告格式。
3. 使用 appKey、广告格式和用户 ID（如果相关）调用 LevelPlay init API。

```cs
using Unity.Services.LevelPlay;
// Init the SDK when implementing the Multiple Ad Units API for Interstitial, Banner, and Rewarded
LevelPlay.OnInitSuccess += SdkInitializationCompletedEvent;
LevelPlay.OnInitFailed += SdkInitializationFailedEvent;
LevelPlay.Init(appKey);
```

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

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

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

| 组件  | 旧版                       | 广告单元（新）        |
| --- | ------------------------ | -------------- |
| API | IronSource.init          | LevelPlay.Init |
| 事件  | onInitializationComplete | OnInitSuccess  |
| 不适用 | 不适用                      | OnInitFailed   |

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

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

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

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

```cs
私有变量 LevelPlayRewardedAd rewardAd;
// Create rewarded Ad
rewardedAd = new LevelPlayRewardedAd(adUnitId);
```

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

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

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

```cs
私有变量 LevelPlayRewardedAd rewardAd;
// Create rewarded Ad
rewardedAd = new LevelPlayRewardedAd(adUnitId);
// Register to events
rewardAd.OnAdLoaded += OnAdLoaded;
rewardAd.OnAdLoadFailed += OnAdLoadFailed;
rewardAd.OnAdDisplayed += OnAdDisplayed;
rewardAd.OnAdDisplayFailed += OnAdDisplayFailed;
rewardAd.OnAdRewarded += OnAdRewarded;
rewardAd.OnAdClosed += OnAdClosed;
// Optional
rewardAd.OnAdClicked += OnAdClicked;
rewardAd.OnAdInfoChanged += OnAdInfoChanged;
```

### LevelPlay 奖励广告事件##levelplay-rewarded-ad-events

**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** 事件后，即可加载奖励广告。应使用 方法执行此操作：

```cs
// Load or reload the ad
rewardedAd.LoadAd();
```

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

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

```cs
// Show ad without placement 
rewardedAd.ShowAd();
// Show ad with placement 
rewardedAd.ShowAd(placementName);
```

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

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

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

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

```cs
// Check that ad is ready and that the placement is not capped
if (rewardedAd.IsAdReady() && !LevelPlayRewardedAd.IsPlacementCapped(placementName))
{
    rewardedAd.ShowAd(placementName);
}
```

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

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

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

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

```cs
// Subscribe to the OnAdRewarded event
ad.OnAdRewarded += (adInfo, reward) => 
{
    // Grant the reward to the user
    Debug.Log($"Ad Completed: {adInfo.PlacementName}, Reward: {reward.Name} - {reward.Amount}");
    GrantReward(reward.Name, reward.Amount);
};
// Example method to process the reward
私有变量 void GrantReward(字符串 rewardName, int rewardAmount)
{
    // TODO:实现向用户授予奖励的逻辑
    Debug.Log($"Granting reward: {rewardName} with amount: {rewardAmount}");
}
```

## 多个广告单元奖励 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

```cs
public class LevelPlaySample : MonoBehaviour
{
    私有变量 LevelPlayRewardedAd rewardAd;
    void CreateRewardedAd(string adUnitId)
    {
        rewardedAd = new LevelPlayRewardedAd(adUnitId);
        rewardAd.OnAdLoaded += OnAdLoaded;
        rewardAd.OnAdLoadFailed += OnAdLoadFailed;
        rewardAd.OnAdDisplayed += OnAdDisplayed;
        rewardAd.OnAdDisplayFailed += OnAdDisplayFailed;
        rewardAd.OnAdRewarded += OnAdRewarded;
        rewardAd.OnAdClicked += OnAdClicked;
        rewardAd.OnAdClosed += OnAdClosed;
        rewardAd.OnAdInfoChanged += OnAdInfoChanged;
    }
    void LoadRewardedAd()
    {
        rewardedAd.LoadAd();
    }
    void ShowRewardedAd(string placementName = null)
    {
        if (rewardedAd.IsAdReady() &&!LevelPlayRewardedAd.IsPlacementCapped(placementName))
        {
            rewardedAd.ShowAd(placementName);
        }
    }
    bool CheckIfRewardedAdIsReady()
    {
        return rewardedAd.IsAdReady();
    }
    bool CheckIfPlacementIsCapped(字符串 placementName)
    {
        return LevelPlayRewardedAd.IsPlacementCapped(placementName);
    }
    void OnAdLoaded(LevelPlayAdInfo adInfo)
    {
        Debug.Log($"Rewarded ad loaded with ad info {adInfo}");
    }
    void OnAdLoadFailed(LevelPlayAdError adError)
    {
        Debug.Log($"Rewarded ad failed to load with ad error {adError}");
    }
   
    void OnAdDisplayed(LevelPlayAdInfo adInfo)
    {
        Debug.Log($"Rewarded ad displayed with ad info {adInfo}");
    }
       
    void OnAdDisplayFailed(LevelPlayAdInfo adInfo, LevelPlayAdError error)
    {
        Debug.Log($"Rewarded ad failed to display with ad info: {adInfo} and error: {error}");
    }
    
    void OnAdRewarded(LevelPlayAdInfo adInfo, LevelPlayReward adReward)
    {
        Debug.Log($"Rewarded ad gained reward with adInfo {adInfo} and reward {adReward}");
    }
    void OnAdClicked(LevelPlayAdInfo adInfo)
    {
        Debug.Log($"Rewarded ad clicked with ad info {adInfo}");
    }
    
    void OnAdClosed(LevelPlayAdInfo adInfo)
    {
        Debug.Log($"Rewarded ad closed with ad info {adInfo}");
    }
    
    void OnAdInfoChanged(LevelPlayAdInfo adInfo)
    {
        Debug.Log($"Rewarded ad info changed with ad info {adInfo}");
    }    
}
```