自适应内嵌横幅

自适应内联横幅是一种灵活的横幅广告格式，通过优化每个设备上的广告尺寸，实现最大效率。

这种广告类型允许开发者设置广告的最大允许宽度和高度，但最佳广告尺寸仍然是自动确定的。为了选择最佳广告尺寸，内置自适应横幅使用最大高度而不是固定高度。这为提高广告效果提供了空间。

该格式常见于信息流类应用，或当主要注意力可放在广告上的场景。

外观

本指南说明如何借助 Jetpack Compose 扩展在 Android 应用中集成自适应内嵌横幅。除代码示例与操作步骤外，还包含该广告格式的使用建议及相关资源链接。

前置条件

按照快速入门中描述的 SDK 集成步骤进行操作。
提前初始化您的广告 SDK。
确保您运行的是最新的 Yandex Mobile Ads SDK 版本。如果您使用聚合，请同时确保您运行的是最新版本的统一构建。

要使用 Compose 扩展，请在 build.gradle.kts 中添加依赖：

dependencies {
    implementation("com.yandex.android:mobileads:8.0.0")
    implementation("com.yandex.android:mobileads-compose:8.0.0")

    // Compose BOM（最低 2024.01.00）
    implementation(platform("androidx.compose:compose-bom:2025.03.00"))
}

实现

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

使用 BannerSize.Inline 尺寸的 Banner Composable。
可选传入 BannerEvents 以跟踪广告事件。

自适应内嵌横幅集成注意事项

所有对 Yandex Mobile Ads SDK 的方法调用均须在主线程执行。
若要在应用中正确渲染视频广告，请启用硬件加速。硬件加速默认开启，但部分应用会将其关闭。若您的应用关闭了硬件加速，建议在为展示广告的 Activity 上重新启用。
若在 onAdFailedToLoad() 回调中收到错误，请勿立即尝试加载新广告。若必须重试，请限制重试次数，以免在受限网络环境下出现连续失败请求与连接问题。
为使自适应内嵌横幅正常工作，请使应用布局具备自适应能力。否则可能导致广告渲染异常。
自适应内嵌横幅在占满可用宽度时效果最佳；多数情况下应使用设备整屏宽度。请计入应用内边距与安全显示区域。
自适应内嵌横幅适用于可滚动内容中的版位。横幅高度可与设备屏幕高度一致，或受 API 限制为最大高度。
广告尺寸通过 BannerSize.Inline(width, maxHeight) 设置，其中宽度与最大高度以 Dp 传入（例如 320.dp）。Composable 内部会自动解析用于计算的 Context。
横幅状态通过 rememberBannerAdState() 创建，需显式调用 loadAd() 触发加载。若 adSize 发生变化，BannerAdView 会自动重建。

顶部不可点击安全区域的高度为 80 dp。该区域内的控件可以点击。
视觉元素（素材）的尺寸必须至少为 32×32 dp，包括关闭按钮及其他所有图标。
素材周围的可点击区域必须至少为 64×64 dp。例如，如果素材的尺寸为 32×32 dp，则其四周需有足够的内边距，以确保总可点击区域达到 64×64 dp。
如果控件有延迟出现，必须显示一个计时器或进度条，直到元素加载完成。

示例

加载与展示广告

要展示内嵌横幅，请使用 BannerSize.Inline 调用 rememberBannerAdState() 创建状态，再将其传入 Banner Composable，并通过显式调用 loadAd() 触发加载。

您需要来自 Yandex Advertising Network 界面的广告单元 ID。

可通过 AdRequest.Builder() 扩展广告请求参数，传入用户兴趣、页面上下文、地理位置等附加数据。请求中的额外上下文数据有助于显著提升广告质量。详见广告定向。

以下示例展示如何展示自适应内嵌横幅。加载成功后横幅会自动显示：

import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.Banner
import com.yandex.mobile.ads.compose.BannerSize
import com.yandex.mobile.ads.compose.rememberBannerAdState

@Composable
fun MyScreen() {
    val bannerState = rememberBannerAdState(
        adSize = BannerSize.Inline(width = 320.dp, maxHeight = 400.dp),
    )

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

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

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

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
import com.yandex.mobile.ads.compose.rememberBannerAdState

@Composable
fun MyScreen() {
    val bannerState = rememberBannerAdState(
        adSize = BannerSize.Inline(width = 320.dp, maxHeight = 400.dp),
        events = BannerEvents(
            onAdLoaded = { Log.d("YandexAds", "Banner loaded") },
            onAdFailedToLoad = { error -> Log.e("YandexAds", error.description) },
            onAdClicked = { Log.d("YandexAds", "Banner clicked") },
            onImpression = { data -> Log.d("YandexAds", "Impression: ${data?.rawData}") },
        ),
    )

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

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

如果您通过 Adfox 投放广告，则在横幅广告响应后，可以使用 AdAttributes 类型的 adAttributes 属性从 BannerAdView 对象访问 campaignId、bannerId 和 placeId 数据。

测试自适应内嵌横幅集成

使用演示广告单元进行广告测试

我们建议使用测试广告来测试您的自适应内联横幅集成和应用本身。

为了保证为每个广告请求返回测试广告，我们创建了一个特殊的演示广告版位 ID。用它来检查您的广告集成。

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

重要

在商店中发布您的应用程序之前，确保将演示版位 ID 替换为您在 Yandex Advertising Network 界面中获得的真实 ID。

您可以在用于测试的演示广告单元版块找到可用的演示广告版位 ID 列表。

测试广告集成

您可以使用 SDK 的内置分析器测试自适应内联横幅集成。

该工具可确保您的广告正确集成并向日志输出详细报告。要查看报告，请在用于 Android 应用调试的 Logcat 工具中搜索“YandexAds”关键字。

adb logcat -v brief '*:S YandexAds'

如果集成成功，您将看到以下消息：

adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type banner was integrated successfully

如果您在集成横幅广告时遇到问题，您将获得有关问题的详细报告以及如何解决这些问题的建议。

其他资源

GitHub 链接。

这篇文章是否有用？

TradPlus ↗

自适应粘性横幅