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

> 通过初始化广告单元、设置委托和处理广告事件，在 iOS app 中实现奖励视频广告单元。

本指南介绍如何从 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。

1) **Objective-C**

   ```objective-c
   // 使用 app 密钥创建请求构建器。添加 User ID（如果有）
   LPMInitRequestBuilder *requestBuilder = [[LPMInitRequestBuilder alloc] initWithAppKey:@"appKey"];
   [requestBuilder withUserId:@"UserId"];
   // 构建初始请求
   LPMInitRequest *initRequest = [requestBuilder 构建];
   // 使用准备好的请求初始化 LevelPlay
   [LevelPlay initWithRequest:initRequest 完成：^(LPMConfiguration *_Nullable 配置，NSError *_Nullable 报错){
       报错 {
           // 初始化时报错。采取必要的操作或重试
       } else {
           // 初始化成功。现在可以加载横幅广告或执行其他任务
       }
   }];
   ```

2) **Swift**

   ```swift
   // 使用 app 密钥创建请求构建器。添加 User ID（如果有）
   let requestBuilder = LPMInitRequestBuilder(appKey："appKey")
           .withUserId("UserId")
   // 构建初始请求
   let initRequest = requestBuilder.build()
   // 使用准备好的请求初始化 LevelPlay 
   LevelPlay.initWith(initRequest) 
   { config，报错
       if let error = error {
           // 初始化时报错。采取必要的操作或重试
       } else {
           // 初始化成功。现在可以加载广告或执行其他任务
       }
   }
   ```

### 初始化结果##initialization-result

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

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

| 组件    | 旧版                        | 广告单元（新）                   |
| ----- | ------------------------- | ------------------------- |
| API   | IronSource.initWithAppKey | LevelPlay.initWithRequest |
| 初始化结果 | onInitializationComplete  | 完成                        |
|       | –                         | error                     |

## 创建奖励广告##create-rewarded-ad

必须在收到**完成**结果后才能创建奖励广告对象。

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

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

1. **Objective-C**

   ```objective-c
   // 创建奖励广告
   self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"];
   ```

2. **Swift**

   ```swift
   // 创建奖励广告
   self.rewardedAd = LPMRewardedAd(adUnitId: "adUnitId")
   ```

## 实现奖励委托##implement-rewarded-delegate

为创建的奖励广告单元实现 **LPMRewardedAdDelegate**，从而了解广告投放情况。

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

1. **Objective-C**

   ```objective-c
   // 创建奖励广告
   self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"]; 
   // 实现委托
   self.rewardedAd.delegate = self;
   #pragma mark - LPMRewardedAdDelegate 方法
   - (void)didLoadAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didFailToLoadAdWithAdUnitId:(NSString *)adUnitId error:(NSError *)error {}
   - (void)didChangeAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didDisplayAdWithAdInfo:(LPMAdInfo *)adInfo {
   - (void)didFailToDisplayAdWithAdInfo：(LPMAdInfo *)adInfo 报错：(NSError *)报错 {
   - (void)didClickAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didCloseAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didRewardAdWithAdInfo：(LPMAdInfo *)adInfo 奖励：(LPMReward *)奖励{
   ```

2. **Swift**

   ```swift
   // 创建奖励广告
   self.rewardedAd = LPMRewardedAd(adUnitId: "adUnitId")
   // 实现委托 
   self.rewardedAd.setDelegate(self)
   // 标记：LPMRewardedAdDelegate 方法
   func didLoadAd（包含 adInfo：LPMAdInfo) {
   func didFailToLoadAd(withAdUnitId adUnitId：字符串，报错：报错) {
   func didChangeAdInfo(_ adInfo：LPMAdInfo) {
   func didDisplayAd（包含 adInfo：LPMAdInfo) {
   func didFailToDisplayAd（包含 adInfo：LPMAdInfo，报错：报错) {
   func didClickAd（包含 adInfo：LPMAdInfo) {
   func didCloseAd（包含 adInfo：LPMAdInfo) {
   func didRewardAd（包含 adInfo：LPMAdInfo，奖励：LPMReward) {
   ```

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

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

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

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

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

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

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

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

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

| 组件 | 旧版                          | 广告单元（新）               |
| -- | --------------------------- | --------------------- |
| 委托 | LevelPlayRewardedAdDelegate | LPMRewardedAdDelegate |
| 事件 | onAdReady                   | didLoadAd             |
|    | onAdLoadFailed              | didFailToLoadAd       |
|    | onAdOpened                  | didDisplayAd          |
|    | onAdClosed                  | didCloseAd            |
|    | onAdShowFailed              | didFailToDisplayAd    |
|    | onAdRewarded                | didRewardAd           |
|    | onAdClicked                 | didClickAd            |
|    | onAdShowSucceeded           | –（已弃用）                |
|    | –                           | didChangeAdInfo       |

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

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

1. **Objective-C**

   ```objective-c
   // 加载或重新加载广告
   [self.rewardedAd loadAd];
   ```

2. **Swift**

   ```swift
   // 加载或重新加载广告
   self.rewardedAd.loadAd()
   ```

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

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

1. **Objective-C**

   ```objective-c
   // 显示而不放置/位置 
   [self.rewardedAd showAdWithViewController:self placementName:nil];
   // 显示与放置/位置 
   [self.rewardedAd showAdWithViewController:self placementName:placementName];
   ```

2. **Swift**

   ```swift
   // 显示而不放置/位置 
   self.rewardedAd.showAd(viewController: self, placementName: nil)
   // 显示与放置/位置 
   self.rewardedAd.showAd(viewController: self, placementName: placementName)
   ```

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

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

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

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

1. **Objective-C**

   ```objective-c
   // 检查广告是否已准备就绪并且放置/位置未设置上限 
   if ([self.rewardedAd isAdReady] && ![LPMRewardedAd isPlacementCapped:placementName]) {
       [self.rewardedAd showAdWithViewController:self placementName:placementName];
   }
   ```

2. **Swift**

   ```swift
   // 检查广告是否已准备就绪并且放置/位置未设置上限 
   if self.rewardedAd.isAdReady(), !LPMRewardedAd.isPlacementCapped(placementName) {
       self.rewardedAd.showAd(viewController: self, placementName: placementName)
   }
   ```

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

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

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

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

1. **Objective-C**

   ```objective-c
   - (void)didRewardAdWithAdInfo:(LPMAdInfo *)adInfo 奖励：(LPMReward *)奖励 {
       // 实现向用户授予奖励的逻辑
       NSString *name = reward.name; 
       NSInteger *amount = reward.amount;
   }
   ```

2. **Swift**

   ```swift
   func didRewardAd（包含 adInfo：LPMAdInfo，奖励：LPMReward) {
   // 实现向用户授予奖励的逻辑
   字母名称：字符串 = reward.name 
   信件金额：Int = reward.amount
   }
   ```

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

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

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

1. **Objective-C**

   ```objective-c
   NS_ASSUME_NONNULL_BEGIN
   @interface RewardedAdViewController () <LPMRewardedAdDelegate>
   @property(nonatomic, strong) LPMRewardedAd *rewardedAd;
   @end
   @implementation RewardedAdViewController
   - (void)createRewardedAd {
       self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"];
       self.rewardedAd.delegate = self;
   }
   - (void)loadRewardedAd {
       // 加载或重新加载广告
       [self.rewardedAd loadAd];
   }
   - (void)showRewardedAd {
     if ([self.rewardedAd isAdReady]) {
       [self.rewardedAd showAdWithViewController:self placementName:NULL];
     }
   }
   - (void)showRewardedAdWithPlacementName:(NSString *)placementName { }
       // 检查广告是否已准备就绪并且放置/位置未设置上限 
       if ([self.rewardedAd isAdReady] &amp;&amp; ![LPMRewardedAd isPlacementCapped:placementName]) {
           [self.rewardedAd showAdWithViewController:self 
           placementName:placementName];
     }
   }
   #pragma mark - LPMRewardedAdDelegate 方法
   - (void)didLoadAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didFailToLoadAdWithAdUnitId:(NSString *)adUnitId error:(NSError *)error {}
   - (void)didChangeAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didDisplayAdWithAdInfo:(LPMAdInfo *)adInfo {
   - (void)didFailToDisplayAdWithAdInfo：(LPMAdInfo *)adInfo 报错：(NSError *)报错 {
   - (void)didClickAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didCloseAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didRewardAdWithAdInfo：(LPMAdInfo *)adInfo 奖励：(LPMReward *)奖励{
   @end
   NS_ASSUME_NONNULL_END
   ```

2. **Swift**

   ```swift
   类 RewardedAdViewController：UIViewController、LPMRewardedAdDelegate {
   var rewardAd：LPMRewardedAd!
   func createRewardedAd() {
       self.rewardedAd = LPMRewardedAd(adUnitId: "adUnitId")
       self.rewardedAd.setDelegate(self)
   }
   func loadRewardedAd() {
       // 加载或重新加载广告
       self.rewardedAd.loadAd()
   }
   func showRewardedAd() {
       if self.rewardedAd.isAdReady() {
           self.rewardedAd.showAd(viewController: self, placementName: nil)
       }
   }
   func showRewardedAd(withPlacementName placementName:字符串) {
       // 检查广告是否已准备就绪并且放置/位置未设置上限 
       if self.rewardedAd.isAdReady(), !LPMRewardedAd.isPlacementCapped(placementName) {
           self.rewardedAd.showAd(viewController: self, placementName: placementName)
       }
   }

   // MARK: LPMRewardedAdDelegate methods
   func didLoadAd（包含 adInfo：LPMAdInfo) {
   func didFailToLoadAd(withAdUnitId adUnitId：字符串，报错：报错) {
   func didChangeAdInfo(_ adInfo：LPMAdInfo) {
   func didDisplayAd（包含 adInfo：LPMAdInfo) {
   func didFailToDisplayAd（包含 adInfo：LPMAdInfo，报错：报错) {
   func didClickAd（包含 adInfo：LPMAdInfo) {
   func didCloseAd（包含 adInfo：LPMAdInfo) {
   func didRewardAd（包含 adInfo：LPMAdInfo，奖励：LPMReward) {
   }
   ```