# 迁移到适用于 iOS 的插页式广告单元 API

> 通过使用广告单元 ID 加载和显示插页式广告服务，过过渡 LevelPlay 插页式 API。

本指南介绍如何从当前实现过过渡 LevelPlay 插页式 API（使用广告单元 ID），以加载和显示插页式广告服务。

## 先决条件##prerequisites

* 支持的最小 SDK 为 8.6.0。您可以在[此处](/grow/levelplay/sdk/ios/sdk-integration.md)下载最新的 SDK。
* 确保使用 LevelPlay Initialization API 初始化 SDK。
* 在 LevelPlay 后台中找到 AdUnitID。

## 创建插页式广告对象##create-interstitial-ad-object

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

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

对于更高级的实现，如果需要，可以创建多个插页式广告对象。

1. **Objective-C**

   ```objective-c
   self.interstitialAd = [[LPMInterstitialAd alloc] initWithAdUnitId:@"adUnitId"];
   ```

2. **Swift**

   ```swift
   self.interstitialAd = LPMInterstitialAd(adUnitId: "adUnitId")
   ```

## 实现委托##implement-delegates

在代码中实现 **LPMInterstitialAdDelegate** 而不是 **LevelPlayInterstitialDelegate**，从而了解广告投放情况。 

* 建议在加载插页式广告之前设置委托。
* 每个插页式广告都应有自己的委托实现。
* 委托方法在主线程上运行。

1. **Objective-C**

   ```objective-c
   self.interstitialAd = [[LPMInterstitialAd alloc] initWithAdUnitId:@"adUnitId"];
   self.interstitialAd.delegate = self;
   #pragma mark - LPMInterstitialAdDelegate 方法
   - (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 {}
   ```

2. **Swift**

   ```swift
   self.interstitialAd = LPMInterstitialAd(adUnitId: "adUnitId")
   self.interstitialAd.setDelegate(self)

   // MARK: LPMInterstitialAdDelegate 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) {
   ```

|     | 旧版                            | 广告单元（新）                      |
| --- | ----------------------------- | ---------------------------- |
| 委托  | LevelPlayInterstitialDelegate | LPMInterstitialAdDelegate    |
| 事件  | didLoadWithAdInfo             | didLoadAdWithAdInfo          |
|     | didFailToLoadWithError        | didFailToLoadAdWithAdUnitId  |
|     | didOpenWithAdInfo             | didDisplayAdWithAdInfo       |
|     | didCloseWithAdInfo            | didCloseAdWithAdInfo         |
|     | didFailToShowWithError        | didFailToDisplayAdWithAdInfo |
|     | didClickWithAdInfo            | didClickAdWithAdInfo         |
|     | didShowWithAdInfo             | -（已弃用）                       |
|     | -                             | didChangeAdInfo              |

### LevelPlay 广告信息##levelplay-ad-info

间隙监听器回调返回的 **ISAdInfo** 类已被 **LPMAdInfo** 替换。

## 加载 Interstitial Ad##load-interstitial-ad

要加载插页式广告，请使用 **loadAd** 而不是 **loadInterstitial**。

1. **Objective-C**

   ```objective-c
   [self.interstitialAd loadAd];
   ```

2. **Swift**

   ```swift
   self.interstitialAd.loadAd()
   ```

## 显示插页式广告##show-interstitial-ad

在收到 **didLoadWithAdInfo** 回调后显示插页式广告，使用 \*\*LPMInterstitialAdDelegate，\*\*而不是 **LevelPlayInterstitialDelegate**。使用 **showAdWithViewController** 而不是 **showInterstitialWithViewController**。

* 需要共享 **ViewController**。 
* 如果使用放置，请在 **showAd** API 中通道放置/位置名称，如下文 Placements 部分所示。
* 广告成功展示给用户后，可以通过重复加载步骤加载另一个广告。

1. **Objective-C**

   ```objective-c
   - (void)showInterstitialAd {
       // 检查广告是否已准备就绪
       if ([self.interstitialAd isAdReady]) {
           // 显示而不放置/位置
           [self.interstitialAd showAdWithViewController:self placementName:nil];
       }
   }
   ```

2. **Swift**

   ```swift
   func showInterstitialAd() {
       // 检查广告是否已准备就绪
       if self.interstitialAd.isAdReady() {
           // 显示而不放置/位置
           self.interstitialAd.showAd(viewController: self, placementName: nil)
       }
   }
   ```

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

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

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

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

1. **Objective-C**

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

2. **Swift**

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

### 广告位##placements

我们支持在 LevelPlay 控制面板上设置插页的[广告位](/grow/levelplay/platform/settings/placements.md)节奏和上限。 

如果为插页式广告服务设置了位置，请调用 **showAd** 方法为指定的放置/位置提供广告。

1. **Objective-C**

   ```objective-c
   // 检查广告是否已准备就绪并且放置/位置未设置上限
   if ([self.interstitialAd isAdReady] && ![LPMInterstitialAd isPlacementCapped:placementName]) {
       // 显示带有放置/位置的广告
       [self.interstitialAd showAdWithViewController:self placementName:@"PlacementName"];
   }
   ```

2. **Swift**

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

## 多个广告单元插页 API##multiple-ad-unit-interstitial-apis

|     | 旧版                                 | 广告单元（新）                  |
| --- | ---------------------------------- | ------------------------ |
| API | loadInterstitial                   | loadAd                   |
|     | showInterstitialWithViewController | showAdWithViewController |
|     | hasInterstitial                    | isAdReady                |
|     | isInterstitialCappedForPlacement   | isPlacementCapped        |

## Ad Unit API 的完整实现示例##full-implementation-example-of-ad-unit-api

1. **Objective-C**

   ```objective-c
   NS_ASSUME_NONNULL_BEGIN
   @interface InterstitialAdViewController () <LPMInterstitialAdDelegate>
   @property(nonatomic, strong) LPMInterstitialAd *interstitialAd;
   @end
   @implementation InterstitialAdViewController
   - (void)createInterstitialAd {
       self.interstitialAd = [[LPMInterstitialAd alloc] initWithAdUnitId:@"adUnitId"];
       self.interstitialAd.delegate = self;
   }
   - (void)loadInterstitialAd {
       // 用于加载或重新加载广告
       [self.interstitialAd loadAd];
   }
   - (void)showInterstitialAd {
       if ([self.interstitialAd isAdReady]) {
           [self.interstitialAd showAdWithViewController:self placementName:nil];
       }
   }
   - (void)showInterstitialAdWithPlacementName:(NSString *)placementName { }
       // 检查广告是否已准备就绪并且放置/位置未设置上限
       if ([self.interstitialAd isAdReady] &amp;&amp; ![LPMInterstitialAd isPlacementCapped:placementName]) {
           [self.interstitialAd showAdWithViewController:self placementName:placementName];
       }
   }
   #pragma mark - LPMInterstitialAdDelegate 方法
   - (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 {}
   @end
   NS_ASSUME_NONNULL_END
   ```

2. **Swift**

   ```swift
   类 InterstitialAdViewController：UIViewController、LPMInterstitialAdDelegate {
       var interstitialAd：LPMInterstitialAd!

       func createInterstitialAd() {
           self.interstitialAd = LPMInterstitialAd(adUnitId: "adUnitId")
           self.interstitialAd.setDelegate(self)
       }

       func loadInterstitialAd() {
           // Used to load or reload the ad
           self.interstitialAd.loadAd()
       }

       func showInterstitialAd() {
           if self.interstitialAd.isAdReady() {
               self.interstitialAd.showAd(viewController: self, placementName: nil)
           }
       }

       func showInterstitialAd(withPlacementName placementName:字符串) {
           // Check that ad is ready and that the placement is not capped
           if self.interstitialAd.isAdReady(), !LPMInterstitialAd.isPlacementCapped(placementName) {
               self.interstitialAd.showAd(viewController: self, placementName: placementName)
           }
       }

       // MARK:LPMInterstitialAdDelegate 方法
       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) {
   }
   ```

## LevelPlay Mediation 演示应用程序##levelplay-mediation-demo-app

Integration Demo 应用程序演示了如何在 app 中集成插页式广告单元 API。

[下载 iOS demo 应用程序](https://github.com/ironsource-mobile/Mediation-Demo-Apps)