---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/android/compose/adaptive-sticky-banner.md
  - https://ads.yandex.com/helpcenter/ru/dev/android/compose/adaptive-sticky-banner.md
  - https://ads.yandex.com/helpcenter/zh/dev/android/compose/adaptive-sticky-banner.md
  - href: zh/dev/android/compose/adaptive-sticky-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-sticky-banner.md -->
自适应固定横幅广告是一种小型广告，会自动更新，并显示在应用屏幕的顶部或底部。它不会遮挡主要内容，常用于游戏应用中。
<!-- endsource: zh/dev/_includes/adaptive-sticky-banner.md -->

<!-- source: zh/dev/_includes/adaptive-sticky-banner.md -->
自适应固定横幅广告会针对每台设备优化广告尺寸，从而实现最佳效果。借助这种广告类型，开发者可设置广告允许的最大宽度，系统将自动确定最佳广告尺寸。
<!-- endsource: zh/dev/_includes/adaptive-sticky-banner.md -->

{% cut "外观" %}

<img src="https://yastatic.net/s3/doc-binary/src/docs/support/mobile-ads/zh/monetization/_images/banner-sticky-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.Sticky` 尺寸。
2. 可选择传递 `BannerEvents` 以跟踪广告事件。

## 自适应粘性横幅集成说明 {#features}

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

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

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

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

5. 如果启用了聚合，则建议先等待初始化完成，然后再计算粘性横幅尺寸。 在初始化之前，只能使用初步尺寸，在接收实际设置后可能会发生变化。

6. 对于同一设备，粘性横幅尺寸保持不变。 在特定设备上测试应用布局后，您可以确定广告尺寸将保持不变。

7. 自适应粘性横幅高度不会超过屏幕高度的 15%，并且至少为 50 dp。

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

## 加载并展示广告 {#load}

要展示粘性横幅，请通过 `rememberBannerAdState()` 创建状态，并指定 `BannerSize.Sticky` 尺寸，然后将此状态传递到 `Banner` 可组合项。 通过显式调用 `loadAd()` 触发加载。

要加载广告，您需要从 Yandex Advertising Network 界面获取广告单元 ID。

您可以通过 `AdRequest.Builder()` 传递用户兴趣数据、页面上下文数据、位置或其他附加数据来扩展广告请求参数。 请求中的附加上下文数据可以显著提高广告质量。 有关更多信息，请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/android/target.md)。

### 自适应固定横幅广告示例

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

```kotlin
@Composable
fun MyScreen() {
    val bannerState = rememberBannerAdState(
        adSize = BannerSize.Sticky(width = 320.dp),
    )

    LaunchedEffect(Unit) {
        bannerState.loadAd(AdRequest.Builder("your-ad-unit-id").build())
    }

    Banner(
        state = bannerState,
        modifier = Modifier.fillMaxWidth(),
    )
}
```

要跟踪广告事件，请在创建状态时传递 `BannerEvents`：

```kotlin
@Composable
fun MyScreen() {
    val bannerState = rememberBannerAdState(
        adSize = BannerSize.Sticky(width = 320.dp),
        events = BannerEvents(
            onAdLoaded = { Log.d("YandexAds", "Баннер загружен") },
            onAdFailedToLoad = { error -> Log.e("YandexAds", error.description) },
            onAdClicked = { Log.d("YandexAds", "Клик по баннеру") },
            onImpression = { data -> Log.d("YandexAds", "Показ: ${data?.rawData}") },
        ),
    )

    LaunchedEffect(Unit) {
        bannerState.loadAd(AdRequest.Builder("your-ad-unit-id").build())
    }

    Banner(
        state = bannerState,
        modifier = Modifier.fillMaxWidth(),
    )
}
```

<!-- 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-sticky-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-sticky-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 -->