# 适用于 Android 的横幅集成

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

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

> **Note:**
>
> 本文档与 SDK 8.9.0+ 相关。

## 先决条件##prerequisites

* 确保已将 LevelPlay SDK 正确集成到应用程序中。[此处](/grow/levelplay/sdk/android/integration-checklists.md)概述了集成。
* 确保使用 LevelPlay Initialization API 初始化 SDK。
* 在 LevelPlay 后台中找到 AdUnitID。

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

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

1. **Java**

   ```java
   // 创建广告配置 - 可选
   LevelPlayAdSize adSize = LevelPlayAdSize.BANNER;
   LevelPlayBannerAdView.Config adConfig = new LevelPlayBannerAdView.Config.Builder()
      .setAdSize(adSize)
      .setPlacementName("placementName")
      .build();
   // 创建横幅视图并设置广告单元 ID
   LevelPlayBannerAdView levelPlayBanner = new LevelPlayBannerAdView(context, "adUnitId", adConfig);
   ```

2. **Kotlin**

   ```kotlin
   // 创建广告配置 - 可选
   val adSize = LevelPlayAdSize.BANNER
   val adConfig = LevelPlayBannerAdView.Config.Builder()
   .setAdSize(adSize)
   .setPlacementName("placementName")
   .build()
   // 创建横幅视图并设置广告单元 ID
   val levelPlayBanner = LevelPlayBannerAdView(context, "adUnitId", adConfig)
   ```

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

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

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

### 适应屏幕宽度的自适应广告大小（推荐）##adaptive-ad-size-that-adjusts-to-the-screen-width-(recommended)

此选项根据设备类型返回 BANNER 或 LEADERBOARD。支持自适应功能的网络（Google、Yandex）将根据其优化逻辑返回高度。

1. **Java**

   ```java
    LevelPlayAdSize adSize = LevelPlayAdSize.createAdaptiveAdSize(context);
   ```

2. **Kotlin**

   ```kotlin
   val adSize = createAdaptiveAdSize(context)
   ```

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

1. **Java**

   ```java
   levelPlayBanner.setAdSize(LevelPlayAdSize.MEDIUM_RECTANGLE);
   ```

2. **Kotlin**

   ```kotlin
   levelPlayBanner.setAdSize(LevelPlayAdSize.MEDIUM_RECTANGLE) 
   ```

### 广告位##placements

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

1. **Java**

   ```java
   // 设置放置/位置名称
   levelPlayBanner.setPlacementName("placementName");
   ```

2. **Kotlin**

   ```kotlin
   // 设置放置/位置名称
   levelPlayBanner.setPlacementName("placementName")	 
   ```

## 设置横幅监听器##set-banner-listener

在代码中实现 **LevelPlayBannerAdViewListener** 以获取广告投放信息。

* 建议在加载横幅广告之前设置监听器。
* 每个横幅广告都应有自己的监听器实现。
* 回调在主线程上运行。
* 当并非所有网络都支持回调时，它们会被标记为可选。

1. **Java**

   ```java
   levelPlayBanner.setBannerListener(new LevelPlayBannerAdViewListener() {
   @Override
   public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) { }
   // 广告已成功加载 
   }
   @Override
   public void onAdLoadFailed(@NonNull LevelPlayAdError 报错) {
   // 广告加载失败
   }
   @Override
   public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) { }
   // 广告已显示并在屏幕上可见
   }
   @Override
   public void onAdDisplayFailed(@NonNull LevelPlayAdInfo adInfo, @NonNull LevelPlayAdError 报错) {
   // 可选。广告无法在屏幕上显示 
   }
   @Override
   public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) { }
   // 广告被点击
   }
   @Override
   public void onAdExpanded(@NonNull LevelPlayAdInfo adInfo) { }
   // 可选。广告以全屏打开 
   }
   @Override
   public void onAdCollapsed(@NonNull LevelPlayAdInfo adInfo) { }
   // 可选。广告恢复为其原始大小 
   }
   @Override
   public void onAdLeftApplication(@NonNull LevelPlayAdInfo adInfo) 
   // 可选。用户按下广告并被导航出 app 
   }
   ); 
   ```

2. **Kotlin**

   ```kotlin
   levelPlayBanner.setBannerListener(object:LevelPlayBannerAdViewListener {
   覆盖 fun onAdLoaded(adInfo:LevelPlayAdInfo) {
   // 广告已成功加载 
   }
   覆盖 fun onAdLoadFailed（报错：LevelPlayAdError) {
   // 广告加载失败
   }
   覆盖 fun onAdDisplayed(adInfo:LevelPlayAdInfo) {
   // 广告已显示并在屏幕上可见
   }
   覆盖 fun onAdDisplayFailed(adInfo:LevelPlayAdInfo，报错：LevelPlayAdError) {
   // 可选。广告无法在屏幕上显示 
   }
   覆盖 fun onAdClicked(adInfo:LevelPlayAdInfo) {
   // 广告被点击
   }
   覆盖 fun onAdExpanded(adInfo:LevelPlayAdInfo) {
   // 可选。广告以全屏打开
   }
   覆盖 fun onAdCollapsed(adInfo:LevelPlayAdInfo) {
   // 可选。广告恢复为其原始大小 
   }
   覆盖 fun onAdLeftApplication(adInfo:LevelPlayAdInfo) {
   // 可选。用户按下广告并被导航出 app 
   }
   })	 
   ```

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

**LevelPlayAdInfo** 参数包含有关加载的广告的信息。

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

要加载横幅广告，请使用 **loadAd**。

1. **Java**

   ```java
   // 加载横幅广告
   levelPlayBanner.loadAd();
   ```

2. **Kotlin**

   ```kotlin
   // 加载横幅广告
   levelPlayBanner.loadAd()
   ```

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

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

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

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

1. **Java**

   ```java
   // 暂停新
   levelPlayBanner.pauseAutoRefresh();
   // 继续刷新
   levelPlayBanner.resumeAutoRefresh();
   ```

2. **Kotlin**

   ```kotlin
   // 暂停新
   levelPlayBanner.pauseAutoRefresh()
   // 继续刷新
   levelPlayBanner.resumeAutoRefresh()
   ```

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

要销毁横幅，请调用 **destroy** 方法。

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

1. **Java**

   ```java
   levelPlayBanner.destroy()
   ```

2. **Kotlin**

   ```kotlin
   levelPlayBanner.destroy();
   ```

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

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

1. **Java**

   ```java
   public void createAndLoadBanner() {
   // 创建广告配置 - 可选
   LevelPlayAdSize adSize = LevelPlayAdSize.BANNER;
   LevelPlayBannerAdView.Config adConfig = new LevelPlayBannerAdView.Config.Builder()
      .setAdSize(adSize)
      .setPlacementName("placementName")
      .build();

   // Create the banner view and set the ad unit id
   LevelPlayBannerAdView levelPlayBanner = new LevelPlayBannerAdView(context, "adUnitId", adConfig);

   // Add the banner view to the container
   ViewGroup adContainer = findViewById(android.R.id.adContainer);
   adContainer.addView(levelPlayBanner);
   levelPlayBanner.setBannerListener(new LevelPlayBannerAdViewListener() {
      @Override
      public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {
          // Ad was loaded successfully 
      }
      @Override
      public void onAdLoadFailed(@NonNull LevelPlayAdError error) {
          // Ad load failed
      }
      @Override
      public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {
          // Ad was displayed and visible on screen
      }
      @Override
      public void onAdDisplayFailed(@NonNull LevelPlayAdInfo adInfo, @NonNull LevelPlayAdError error) {
          // Ad failed to be displayed on screen
      }
      @Override
      public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {
          // Ad was clicked
      }
      @Override
      public void onAdExpanded(@NonNull LevelPlayAdInfo adInfo) {
          // Ad is opened on full screen
      }
      @Override
      public void onAdCollapsed(@NonNull LevelPlayAdInfo adInfo) {
          // Ad is restored to its original size
      }
      @Override
      public void onAdLeftApplication(@NonNull LevelPlayAdInfo adInfo) {
          // User pressed on the ad and was navigated out of the app 
      }
   });

   // Load the banner ad
   levelPlayBanner.loadAd();

   // To get actual banner layout size (either custom/standard size or adaptive)
   int height = adSize.getHeight();
   int width = adSize.getWidth();
   }
   ```

2. **Kotlin**

   ```kotlin
   public fun createAndLoadBanner() {
   // 创建广告配置 - 可选
   val adSize = LevelPlayAdSize.BANNER
   val adConfig = LevelPlayBannerAdView.Config.Builder()
   .setAdSize(adSize)
   .setPlacementName("placementName")
   .build()
   // 创建横幅视图并设置广告单元 ID
   val levelPlayBanner = LevelPlayBannerAdView(context, "adUnitId", adConfig)

   // Add the banner view to the container
   val adContainer = findViewById<ViewGroup>(R.id.adContainer)
   adContainer.addView(levelPlayBanner)
   levelPlayBanner.setBannerListener(object:LevelPlayBannerAdViewListener {
   覆盖 fun onAdLoaded(adInfo:LevelPlayAdInfo) {
      // Ad was loaded successfully 
   }
   覆盖 fun onAdLoadFailed（报错：LevelPlayAdError) {
      // Ad load failed
   }
   覆盖 fun onAdDisplayed(adInfo:LevelPlayAdInfo) {
      // Ad was displayed and visible on screen
   }
   覆盖 fun onAdDisplayFailed(adInfo:LevelPlayAdInfo，报错：LevelPlayAdError) {
      // Ad failed to be displayed on screen
   }
   覆盖 fun onAdClicked(adInfo:LevelPlayAdInfo) {
      // Ad was clicked
   }
   覆盖 fun onAdExpanded(adInfo:LevelPlayAdInfo) {
      // Ad is opened on full screen
   }
   覆盖 fun onAdCollapsed(adInfo:LevelPlayAdInfo) {
      // Ad is restored to its original size
   }
   覆盖 fun onAdLeftApplication(adInfo:LevelPlayAdInfo) {
      // User pressed on the ad and was navigated out of the app 
   }
   })

   // Load the banner ad
   levelPlayBanner.loadAd()

   // Get width and height for the container
   val width = adSize.getWidth()
   val height = adSize.getHeight()
   }
   ```

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

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

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

验证您与我们的[集成测试套件](/grow/levelplay/sdk/android/integration-test-suite.md)的集成。

## 后续步骤##next-steps

请遵循我们的集成指南来集成其他横幅广告网络或配置其他广告格式：

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