---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/android/compose/adaptive-inline-banner.md
  - https://ads.yandex.com/helpcenter/ru/dev/android/compose/adaptive-inline-banner.md
  - https://ads.yandex.com/helpcenter/zh/dev/android/compose/adaptive-inline-banner.md
  - href: zh/dev/android/compose/adaptive-inline-banner.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt

# 自适应内联横幅

<!-- source: zh/dev/_includes/adaptive-inline-banner.md -->
自适应内嵌横幅广告是一种灵活的横幅广告格式，通过针对每台设备优化广告尺寸，确保投放效果达到最优。
<!-- endsource: zh/dev/_includes/adaptive-inline-banner.md -->

<!-- source: zh/dev/_includes/adaptive-inline-banner.md -->
借助这种广告类型，开发者可设置广告允许的最大宽度和高度，系统将自动确定最佳广告尺寸。为了选择最佳广告尺寸，自适应内嵌横幅广告采用最大高度而非固定高度，这有助于提升广告表现。
<!-- endsource: zh/dev/_includes/adaptive-inline-banner.md -->

此格式通常用于基于信息流的应用，或可接受主要关注广告的场景。

{% cut "外观" %}

<img src="https://yastatic.net/s3/doc-binary/src/docs/support/mobile-ads/zh/monetization/_images/banner-inline-zh-ex.png" width="200">

{% endcut %}

本指南展示了如何使用 Jetpack Compose 扩展将自适应内联横幅集成到 Android 应用中。
除了代码示例和说明之外，它还提供使用此广告格式的建议和其他资源的链接。

## 前提条件 {#pre}

<!-- source: zh/dev/_includes/pre-android.md -->
1. 按照[快速入门](https://ads.yandex.com/helpcenter/zh/dev/android/quick-start.md) 中描述的 SDK 集成步骤进行操作。
2. 首先，您需要[初始化](https://ads.yandex.com/helpcenter/zh/dev/android/quick-start.md#init) 广告 SDK。
3. 确保您使用的是[最新Yandex Mobile Ads SDK 版本](https://ads.yandex.com/helpcenter/zh/dev/android/changelog-android.md)。如果您使用的是广告中介服务，请更新至最新的[单一构建版本](https://ads.yandex.com/helpcenter/zh/dev/android/changelog-android.md)。
<!-- endsource: zh/dev/_includes/pre-android.md -->

<!-- source: zh/dev/_includes/pre-jetpack-compose.md -->
要使用 Compose 扩展，请在 `build.gradle.kts` 中添加依赖：

```kotlin
dependencies {
    implementation("com.yandex.android:mobileads:8.2.0")
    implementation("com.yandex.android:mobileads-compose:8.2.0")

    // Compose BOM (最低版本 2024.01.00)
    implementation(platform("androidx.compose:compose-bom:2025.03.00"))
}
```
<!-- endsource: zh/dev/_includes/pre-jetpack-compose.md -->

## 实施 {#implement}

集成自适应内联横幅的关键步骤：

1. 使用 `Banner` 可组合项，并指定 `BannerSize.Inline` 尺寸。
2. 可选择传递 `BannerEvents` 以跟踪广告事件。

## 自适应内联横幅集成说明 {#features}

1. 所有 Yandex Mobile Ads SDK 方法调用都必须在主线程中进行。

2. 为了使视频广告在您的应用中正确渲染，请启用 [硬件加速](https://developer.android.com/guide/topics/large-screens/support-different-screen-sizes)。 默认情况下启用硬件加速，但某些应用会将其禁用。 如果您的应用禁用了硬件加速，建议为展示广告的活动启用硬件加速。

3. 如果您在 `onAdFailedToLoad()` 回调中收到错误，请不要尝试立即加载新广告。 如果必须重试，请限制重新加载尝试次数，以避免在条件受限的情况下请求持续失败并出现连接问题。

4. 为确保自适应内联横幅正常运行，请[将您的应用布局设置为自适应](https://developer.android.com/guide/topics/large-screens/support-different-screen-sizes)。 如果不这样做，可能会导致广告渲染错误。

5. 自适应内联横幅在充分利用可用宽度时效果最佳。 在大多数情况下，这将是设备的屏幕全宽。 确保考虑应用自身的内边距及显示安全区域。

6. 自适应内联横幅适合在可滚动内容中展示。 横幅高度可以与设备屏幕高度相当，也可以被限制为最大高度，具体取决于 API。

7. 广告尺寸通过 `BannerSize.Inline(width, maxHeight)` 设置，其中宽度和最大高度以 `Dp` 为单位进行传递（如 `320.dp`）。 计算所需的上下文会在可组合项内部自动解析。

8. 横幅状态通过 `rememberBannerAdState()` 创建，加载则是通过调用 `loadAd()` 显式触发。 如果 `adSize` 发生变化，`BannerAdView` 将自动重新创建。

## 全屏内联横幅渲染规则 {#banner-assets}

<!-- source: zh/dev/_includes/banner-assets.md -->
1. 顶部不可点击安全区域的高度为 80 dp。该区域内的控件可以点击。

1. 视觉元素（素材）的尺寸必须至少为 32×32 dp，包括关闭按钮及其他所有图标。

1. 素材周围的可点击区域必须至少为 64×64 dp。例如，如果素材的尺寸为 32×32 dp，则其四周需有足够的内边距，以确保总可点击区域达到 64×64 dp。

1. 如果控件有延迟出现，必须显示一个计时器或进度条，直到元素加载完成。

{% cut "示例" %}

![](../../../_images/common/banner-assets.png)

{% endcut %}
<!-- endsource: zh/dev/_includes/banner-assets.md -->

## 广告的加载与渲染 {#load}

要显示内嵌横幅广告，请使用尺寸为 `BannerSize.Inline` 的 `Banner` 可组合函数。请以 dp 为单位指定宽度和最大高度。

该可组合函数会自动处理尺寸计算、广告加载和展示次数。您无需手动管理 `BannerAdView` 的生命周期。

要加载广告，您需要通过 Yandex Advertising Network 接口获取的广告版位 ID。

您可以使用 `AdRequest.Builder()` 扩展广告请求参数。为此，请在请求中传递有关用户兴趣、页面上下文、位置以及其他附加数据的信息。上下文信息可显著提升广告质量。如需详细了解，请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/android/target.md)。

### 自适应内嵌横幅示例

加载完成后，横幅广告将自动显示：

```kotlin
import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.Banner
import com.yandex.mobile.ads.compose.BannerSize

@Composable
fun MyScreen() {
    Banner(
        adRequest = AdRequest.Builder("your-ad-unit-id").build(),
        adSize = BannerSize.Inline(width = 320, maxHeight = 400),
        modifier = Modifier.fillMaxWidth(),
    )
}
```

要追踪广告事件，请传递 `BannerEvents`：

```kotlin
import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.Banner
import com.yandex.mobile.ads.compose.BannerEvents
import com.yandex.mobile.ads.compose.BannerSize

@Composable
fun MyScreen() {
    Banner(
        adRequest = AdRequest.Builder("your-ad-unit-id").build(),
        adSize = BannerSize.Inline(width = 320, maxHeight = 400),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(
            onAdLoaded = { Log.d("YandexAds", "Banner loaded") },
            onAdFailedToLoad = { error -> Log.e("YandexAds", error.description) },
            onAdClicked = { Log.d("YandexAds", "Banner click") },
            onImpression = { data -> Log.d("YandexAds", "Impression: ${data?.rawData}") },
        )
    )
}
```

<!-- source: zh/dev/_includes/ad-attributes.md -->
如果您通过 Adfox 投放广告，则在横幅广告响应后，可以使用 `AdAttributes` 类型的 `adAttributes` 属性从 `BannerAdView` 对象访问 `campaignId`、`bannerId` 和 `placeId` 数据。
<!-- endsource: zh/dev/_includes/ad-attributes.md -->

## 测试自适应内联横幅集成 {#test}

<!-- source: zh/dev/_includes/test-android-inline-banner.md -->
### 使用演示广告单元进行广告测试 {#demo-blocks}

使用测试广告来检查您的自适应内嵌横幅广告集成和应用本身。为了确保每次广告请求都能返回测试广告，您可以使用一个特殊的演示广告版位 ID。

演示广告单元 ID：`demo-banner-yandex`.

{% note warning %}

在应用商店发布应用前，请务必将演示广告版位 ID 替换为您在 Yandex Advertising Network 接口中获取的真实 ID。

{% endnote %}

有关所有可用演示广告版位 ID 的列表，请参阅[用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/android/demo-blocks.md)。

### 测试广告集成 {#test-int}

您可以使用 SDK 的内置分析工具检查自适应内嵌横幅广告是否已正确集成。日志中将显示包含测试结果的详细报告。

要查看报告，请在 Android 应用调试工具 [Logcat](https://developer.android.com/studio/command-line/logcat) 中搜索关键词“YandexAds”。

```bash
adb logcat -v brief '*:S YandexAds'
```

如果集成成功，将返回以下消息：
```bash
adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type banner was integrated successfully
```

如果存在任何横幅广告集成问题，您将收到详细的问题报告和故障排除建议。
<!-- endsource: zh/dev/_includes/test-android-inline-banner.md -->

## 其他资源 {#resources}

* <!-- source: zh/dev/_includes/github-pubdev-links.md -->
  [GitHub](https://github.com/yandexmobile/yandex-ads-sdk-android) 链接。
  <!-- endsource: zh/dev/_includes/github-pubdev-links.md -->