# 迁移到 Unity 横幅广告单元 API

> 通过初始化 SDK、定义广告格式以及使用广告单元 ID 加载和显示横幅广告服务，过过渡 LevelPlay 横幅广告单位 API。

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

## 先决条件##prerequisites

* 支持的最小 SDK 为 8.6.0。您可以在[此处](/grow/levelplay/sdk/unity/package-integration.md)下载最新的 SDK。
* 确保使用 LevelPlay Initialization API 初始化 SDK。
* 在 LevelPlay 后台中找到 AdUnitID。在[此处](/grow/levelplay/platform/get-started/ad-units.md)了解更多信息。

## **创建横幅广告对象\*\*\*\*并设置大小**##**create-banner-ad-object\*\*\*\*and-set-size**

横幅广告对象的创建应在接收 **OnInitSuccess** 回调后完成。

bannerAd = new LevelPlayBannerAd(bannerAdUnitId);

```csharp
// Create the banner object and set the ad unit id
bannerAd = new LevelPlayBannerAd(bannerAdUnitId);
```

### 横幅大小##banner-sizes

| **旧版**           | **Ad Unit（广告单元）（新）** | **dp 中的尺寸**               |
| ---------------- | -------------------- | ------------------------- |
| **ISBannerSize** | **LevelPlayAdSize**  | **（Width X Height）**      |
| BANNER           | BANNER               | 320 x 50                  |
| 大型               | 大型                   | 320 x 90                  |
| 矩形               | 中矩形                  | 300 x 250                 |
| SMART            | 替换为自适应广告大小（见下文）      | 自动渲染广告服务以调整移动端和平板电脑的大小和方向 |

要创建广告大小，请遵循以下选项之一： 

**适应屏幕宽度的自适应广告大小（推荐）：**
此选项根据设备类型返回 BANNER 或 LEADERBOARD。支持自适应功能的网络（Google、Yandex）将根据其优化逻辑返回高度。

```csharp
LevelPlayAdSize adSize = LevelPlayAdSize.CreateAdaptiveAdSize();
```

**指定的横幅大小：**
此选项允许您专门设置横幅大小：横幅、大型、中等矩形。

```csharp
LevelPlayAdSize adSize = LevelPlayAdSize.BANNER;
```

### 广告位##placements

我们支持在横幅广告中[放置](/grow/levelplay/platform/settings/placements.md)仅用于举报。应在 **LoadAd** 之前设置它们以影响所有重新加载的广告服务。

```csharp
// Set the placement name
LevelPlayBannerAd bannerAd = new LevelPlayBannerAd("bannerAdUnitId", LevelPlayAdSize.BANNER, placementName:"placementName");
```

## 实现横幅事件##implement-banner-events

监听代码中的 **LevelPlayBannerAd** 事件。SDK 将通知下面列出的所有可能事件。

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

```csharp
// Register to the events
bannerAd.OnAdLoaded += BannerOnAdLoadedEvent;
bannerAd.OnAdLoadFailed += BannerOnAdLoadFailedEvent;
bannerAd.OnAdDisplayed += BannerOnAdDisplayedEvent;
bannerAd.OnAdDisplayFailed += BannerOnAdDisplayFailedEvent;
bannerAd.OnAdClicked += BannerOnAdClickedEvent;
bannerAd.OnAdCollapsed += BannerOnAdCollapsedEvent;
bannerAd.OnAdLeftApplication += BannerOnAdLeftApplicationEvent;
bannerAd.OnAdExpanded += BannerOnAdExpandedEvent;

// Implement the events
void BannerOnAdLoadedEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdLoadFailedEvent(LevelPlayAdError error) {}
void BannerOnAdClickedEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdDisplayedEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error) {}
void BannerOnAdCollapsedEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdLeftApplicationEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdExpandedEvent(LevelPlayAdInfo adInfo) {}
```

|     | 旧版                      | 广告单元（新）             |
| --- | ----------------------- | ------------------- |
| 监听器 | LevelPlayBannerListener | LevelPlayBannerAd   |
| 回调  | onAdLoaded              | onAdLoaded          |
|     | onAdLoadFailed          | onAdLoadFailed      |
|     | onAdClicked             | onAdClicked         |
|     | onAdScreenPresented     | onAdExpanded        |
|     | onAdScreenDismissed     | onAdCollapsed       |
|     | onAdLeftApplication     | onAdLeftApplication |
|     |                         | onAdDisplayed       |
|     |                         | onAdDisplayFailed   |

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

> **Note:**
>
> **LevelPlayAdInfo** 参数包含有关加载的广告的信息。在[此处](/grow/levelplay/sdk/unity/levelplay-listener-adinfo-integration.md)了解更多信息。

## 加载横幅广告##load-banner-ad

要加载横幅广告，请使用 **LoadAd** 而不是 **IronSource.loadBanner**。

```csharp
bannerAd.LoadAd();
```

## 暂停和恢复横幅刷新##pause-and-resume-banner-refresh

如果在平台中定义了刷新值，则可以在代码中暂停横幅刷新。使用以下方法可停止横幅广告的自动刷新，或在暂停后重新启用。 

> **Note:**
>
> 再次显示横幅时，它将完成从暂停时间到刷新的时间。 

* **pauseAutoRefresh** - 暂停横幅广告的自动刷新。
* **resumeAutoRefresh** - 暂停横幅广告后恢复自动刷新。

```csharp
// Pause refresh
bannerAd.PauseAutoRefresh();
// Resume refresh
bannerAd.ResumeAutoRefresh();
```

## **隐藏和显示横幅**##**hide-and-show-banners**

作为横幅构造函数函数的一部分，您可以在背景加载横幅，并仅当相关时才在屏幕上共享。要控制加载后的广告可见性，可使用以下 API： 

* **ShowAd –** 横幅将显示在屏幕上 
* **HideAd –** 横幅将被隐藏

bannerAd.ShowAd();
bannerAd.HideAd();

```csharp
// Show ad
bannerAd.ShowAd();
// Hide ad
bannerAd.HideAd();
```

## **显示镂空（仅限 Android）**##**display-cutouts-(android-only)**

Android 设备中的显示切口是为摄像机、传感器或扬声器等重要组件保留的指定区域，通常用于智能手机和具有边缘到边缘显示屏的设备。镂空可能会限制游戏视图，从而影响横幅在屏幕上的放置/位置。为避免横幅广告和显示的镂空重叠，请创建 **LevelPlayBannerAd** 并将 \*\* respectSafeArea\*\* 设置为 true。

您可以在[此处](https://developer.android.com/guide/topics/display-cutout)了解有关 Google 显示镂空解决方案的更多信息。

要支持 Android 镂空，请创建一个 **respectSafeArea** 值为 true（默认值为 false）的 **LevelPlayBannerAd** 对象。

```csharp
bannerAd = new LevelPlayBannerAd(bannerAdUnitId, respectSafeArea:true);
```

## **销毁横幅广告**##**destroy-banner-ad**

要销毁横幅，请调用 **DestroyAd** 方法而不是 **IronSource.destroyBanner**。

已销毁的横幅无法再次显示。要显示更多广告服务，请创建一个新的 **LevelPlayBannerAd** 对象。 

```csharp
bannerAd.DestroyAd();
```

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

|     | 旧版            | 广告单元（新）                |
| --- | ------------- | ---------------------- |
| 类   | IronSource    | LevelPlayBannerAd      |
| API | loadBanner    | LoadAd                 |
|     | destroyBanner | DestroyAd              |
|     |               | LevelPlayAdSize.Width  |
|     | -             | LevelPlayAdSize.Height |
|     | -             | PauseAutoRefresh       |
|     | -             | ResumeAutoRefresh      |
|     | -             | ShowAd                 |
|     | -             | HideAd                 |

## 横幅广告服务的完整实现示例##full-implementation-example-of-banner-ads

以下是使用自适应横幅大小创建和加载横幅广告的示例。

```csharp
public class BannerAdSample {
  私有变量 LevelPlayBannerAd bannerAd;
  void CreateBannerAd() {
    // Create banner instance
    bannerAd = new LevelPlayBannerAd("bannerAdUnitId");
    // Subscribe BannerAd events
    bannerAd.OnAdLoaded += BannerOnAdLoadedEvent;
    bannerAd.OnAdLoadFailed += BannerOnAdLoadFailedEvent;
    bannerAd.OnAdDisplayed += BannerOnAdDisplayedEvent;
    bannerAd.OnAdDisplayFailed += BannerOnAdDisplayFailedEvent;
    bannerAd.OnAdClicked += BannerOnAdClickedEvent;
    bannerAd.OnAdCollapsed += BannerOnAdCollapsedEvent;
    bannerAd.OnAdLeftApplication += BannerOnAdLeftApplicationEvent;
    bannerAd.OnAdExpanded += BannerOnAdExpandedEvent;
  }
  void LoadBannerAd() {
    // Load the banner ad
    bannerAd.LoadAd();
  }
  void ShowBannerAd() {
    // Show the banner ad, call this method only if you turned off the auto show when you created this banner instance.
    bannerAd.ShowAd();
  }
  void HideBannerAd() {
    // Hide banner
    bannerAd.HideAd();
  }
  void DestroyBannerAd() {
    // Destroy banner
    bannerAd.DestroyAd();
  }
  // Implement BannerAd Events
  void BannerOnAdLoadedEvent(LevelPlayAdInfo adInfo) {}
  void BannerOnAdLoadFailedEvent(LevelPlayAdError error) {}
  void BannerOnAdClickedEvent(LevelPlayAdInfo adInfo) {}
  void BannerOnAdDisplayedEvent(LevelPlayAdInfo adInfo) {}
  void BannerOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error) {}
  void BannerOnAdCollapsedEvent(LevelPlayAdInfo adInfo) {}
  void BannerOnAdLeftApplicationEvent(LevelPlayAdInfo adInfo) {}
  void BannerOnAdExpandedEvent(LevelPlayAdInfo adInfo) {}
}
```

## **完成！**##**done!**

现在，您已全部设置为使用我们新的多个广告单元 API 在应用程序中提供横幅广告服务。