# Unity 横幅集成

> 通过初始化 SDK、在初始化后创建横幅广告对象以及设置适当的广告大小和位置，在 Unity 中集成横幅广告服务。

横幅是由系统启动的矩形广告服务，可以是静态广告，也可以是动画广告，并在实时 app 内容周围的指定区域提供。

> **Note:**
>
> 本文档与 SDK 8.4.0+（测试版 API）相关。

## 先决条件##prerequisites

* 确保已将 LevelPlay SDK 正确集成到应用程序中。[此处](/grow/levelplay/sdk/unity/package-integration.md)概述了集成。
* 确保使用 LevelPlay Initialization API 初始化 SDK。
* 在 LevelPlay 后台中找到 AdUnitID。在[此处](/grow/levelplay/platform/get-started/ad-units.md)了解更多信息。

## 创建横幅广告对象，设置大小和位置##create-banner-ad-object-set-size-and-position

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

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

注意：`LevelPlayBannerAd` 构造函数还支持可选的 `Config` 参数：

```csharp
// Use optional Config parameter
LevelPlayBannerAd(字符串 adUnitId, Config config = null)
```

如果不需要特殊设置，可以省略 `Config` 参数，仅通道 `adUnitId`。将使默认性创建横幅：

| 属性              | 默认值               |
| --------------- | ----------------- |
| 大小              | 横幅广告              |
| 位置              | BottomCenter      |
| displayOnLoad   | true              |
| respectSafeArea | false（仅限 Android） |

要自定义横幅参数，请使用`Config`构建器：

```csharp
var configBuilder = new LevelPlayBannerAd.Config.Builder();
configBuilder.SetSize(LevelPlayAdSize.LARGE);
configBuilder.SetPosition(LevelPlayBannerPosition.TopCenter);
configBuilder.SetDisplayOnLoad(true);
configBuilder.SetRespectSafeArea(true); // 仅适用于 Android
configBuilder.SetPlacementName("bannerPlacement");
configBuilder.SetBidFloor(1.0); // 最低出价（美元）
var bannerConfig = configBuilder.Build();

bannerAd = new LevelPlayBannerAd(bannerAdUnitId, bannerConfig);
```

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

| LevelPlayAdSize | 描述                        | Dimensions in dp（Width X Height） |
| --------------- | ------------------------- | -------------------------------- |
| BANNER          | 标准横幅                      | 320 x 50                         |
| 大型              | 大型横幅                      | 320 x 90                         |
| 中矩形             | 中等矩形 (MREC)               | 300 x 250                        |
| 自适应             | 自动渲染广告服务以调整移动端和平板电脑的大小和方向 | 设备宽度 X 建议高度                      |

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

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

* 对于 LevelPlay SDK 8.8.0+，可使用以下方法确定在加载横幅之前将返回的自适应横幅的宽度和高度：

```csharp
LevelPlayAdSize adSize = LevelPlayAdSize.CreateAdaptiveAdSize();
int width = adSize.Width;
int height = adSize.Height;
```

* 对于 8.8.0 以下的 LevelPlay SDK：

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

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

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

### 横幅位置##banner-positions

在屏幕上显示横幅的默认位置是 **BottomCenter**。以下是所有受支持位置的完整列表：

* TopLeft
* TopCenter
* TopRight
* CenterLeft
* 中心
* CenterRight
* BottomLeft
* BottomCenter
* 右下角

```csharp
LevelPlayBannerAd bannerAd = new LevelPlayBannerAd(adUnitId, LevelPlayAdSize.BANNER, LevelPlayBannerPosition.TopLeft);
```

还可以通过创建 `LevelPlayBannerPosition` 对象将横幅定位在屏幕上指定的 (x, y) 坐标处，并在 dp 中定义 x 和 y 值。

```csharp
LevelPlayBannerPosition position = new LevelPlayBannerPosition(new Vector2(x, y));
LevelPlayBannerAd bannerAd = new LevelPlayBannerAd(adUnitId, adSize, position, placementName, displayOnLoad, respectSafeArea);
```

### 广告位##placements

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

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

## 实现横幅事件##implement-the-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 ironSourceError) {}
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) {}
```

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

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

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

要加载横幅广告，请使用 `LoadAd`。

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

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

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

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

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

bannerAd.HideAd();

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

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

> **Note:**
>
> 隐藏广告服务后，只要打开自动刷新，广告就会继续在背景刷新。

```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 镂空，请使用 `Config` 创建一个横幅对象，并将 respectSafeArea 值设置为 true（默认值为 false）。

```csharp
var configBuilder = new LevelPlayBannerAd.Config.Builder();
configBuilder.SetRespectSafeArea(true); // 仅适用于 Android
var bannerConfig = configBuilder.Build();

bannerAd = new LevelPlayBannerAd(bannerAdUnitId, bannerConfig);
```

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

要销毁横幅，请调用 `DestroyAd` 方法。

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

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

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

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

```csharp
public class BannerAdSample {
  私有变量 LevelPlayBannerAd bannerAd;
  void CreateBannerAd() {
    // Create ad configuration - optional
    var adConfig = new LevelPlayBannerAd.Config.Builder()
      .SetSize(LevelPlayAdSize.BANNER)
      .SetPlacementName("placementName")
      .SetPosition(LevelPlayBannerPosition.BottomCenter)
      .SetDisplayOnLoad(true)
      .SetRespectSafeArea(true)
      .Build();
        
    // Create banner instance
    bannerAd = new LevelPlayBannerAd("bannerAdUnitId", adConfig);
    // 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;
  }
  public void LoadBannerAd() {
    //Load the banner ad 
    bannerAd.LoadAd();
  }
  public 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();
  }
  public void HideBannerAd() {
    //Hide banner
    bannerAd.HideAd();
  }
  public void DestroyBannerAd() {
    //Destroy banner
    bannerAd.DestroyAd();
  }
  //Implement BannerAd Events
  public void BannerOnAdLoadedEvent(LevelPlayAdInfo adInfo) {}
  public void BannerOnAdLoadFailedEvent(LevelPlayAdError ironSourceError) {}
  public void BannerOnAdClickedEvent(LevelPlayAdInfo adInfo) {}
  public void BannerOnAdDisplayedEvent(LevelPlayAdInfo adInfo) {}
  public void BannerOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error){}
  public void BannerOnAdCollapsedEvent(LevelPlayAdInfo adInfo) {}
  public void BannerOnAdLeftApplicationEvent(LevelPlayAdInfo adInfo) {}
  public void BannerOnAdExpandedEvent(LevelPlayAdInfo adInfo) {}
}
```

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

Integration Demo 应用程序演示如何在 app 中集成横幅广告单元 API。

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

现在，您已全部设置为在应用程序中提供横幅广告。验证您与我们的[集成测试套件](/grow/levelplay/sdk/unity/integration-test-suite.md)的集成。

可以在编辑器中测试您的集成。要了解如何在 Unity 编辑器中预览模拟广告服务，请参阅[预览模拟广告服务指南](/grow/levelplay/sdk/unity/preview-mock-ads-in-editor.md)。

下一步是什么？
请遵循我们的集成指南来集成其他横幅广告网络或配置其他广告格式：

* [添加聚合网络](/grow/levelplay/sdk/unity/mediation-networks.md)
* [奖励广告服务](/grow/levelplay/sdk/unity/rewarded-ad-integration-package.md)
* [插页式广告服务](/grow/levelplay/sdk/unity/interstitial-integration.md)