插屏广告

插屏广告是一种全屏广告格式，嵌入在应用内容中，在自然暂停时显示，例如在游戏关卡之间过渡或完成目标操作时。

当应用展示插屏广告时，用户可以选择：点击广告前往广告主站点，或关闭广告并返回应用。

插屏广告会占据用户的全部注意力，因此其 CPM 通常更高。

外观

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

前置条件

  1. 按照 快速入门 中描述的 SDK 集成步骤进行操作。
  2. 提前 初始化 您的广告 SDK。
  3. 确保您运行的是最新的 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"))
}

实现

集成插屏广告的关键步骤：

  • 使用 rememberInterstitialAdLoader() 创建广告加载器。
  • 通过挂起函数 loadAd() 加载广告，并处理 InterstitialAdLoadResult。
  • 注册 InterstitialAdEventListener 以接收广告事件回调。
  • 展示 InterstitialAd。

插屏广告集成注意事项

  1. 所有对 Yandex Mobile Ads SDK 的方法调用均须在主线程执行。

  2. 若在 InterstitialAdLoadResult.Failure 中收到错误，请勿立即尝试加载新广告。若必须重试，请限制重试次数，以免在受限网络环境下出现连续失败请求与连接问题。

  3. 建议在发生广告交互的整个界面生命周期内对广告对象保持强引用，以避免被垃圾回收。

  4. 当 Composable 离开组合树时，系统会自动调用 cancelLoading()，无需手动释放加载器资源。

加载广告

使用 rememberInterstitialAdLoader() 加载插屏广告。通过挂起函数 loadAd() 执行加载，其返回值为 InterstitialAdLoadResult。

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

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

以下示例展示如何加载插屏广告：

import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.rememberInterstitialAdLoader
import com.yandex.mobile.ads.interstitial.InterstitialAdLoadResult

@Composable
fun MyScreen(activity: Activity) {
    var interstitialAd by remember { mutableStateOf<InterstitialAd?>(null) }

    val loader = rememberInterstitialAdLoader()

    LaunchedEffect(Unit) {
        when (val result = loader.loadAd(AdRequest.Builder("your-ad-unit-id").build())) {
            is InterstitialAdLoadResult.Success -> interstitialAd = result.ad
            is InterstitialAdLoadResult.Failure -> {
                // 广告因 AdRequestError 加载失败。
                // 强烈不建议在此处立即尝试加载新广告。
            }
        }
    }
}

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

展示广告

插屏广告应在应用使用的自然停顿点展示，例如关卡之间或完成目标操作之后（如文件下载完成）。

展示前请设置广告事件监听器 InterstitialAdEventListener。

@Composable
fun MyScreen(activity: Activity) {
    var interstitialAd by remember { mutableStateOf<InterstitialAd?>(null) }

    val loader = rememberInterstitialAdLoader()

    LaunchedEffect(Unit) {
        when (val result = loader.loadAd(AdRequest.Builder("your-ad-unit-id").build())) {
            is InterstitialAdLoadResult.Success -> interstitialAd = result.ad
            is InterstitialAdLoadResult.Failure -> {
                // 广告因 AdRequestError 加载失败。
            }
        }
    }

    LaunchedEffect(interstitialAd) {
        interstitialAd?.apply {
            setAdEventListener(object : InterstitialAdEventListener {
                override fun onAdShown() {
                    // 广告已展示时调用。
                }
                override fun onAdFailedToShow(adError: AdError) {
                    // InterstitialAd 展示失败时调用。
                    loadInterstitialAd()
                }
                override fun onAdDismissed() {
                    // 广告已关闭时调用。
                    // 此时可预加载下一条插屏广告。
                    loadInterstitialAd()
                }
                override fun onAdClicked() {
                    // 记录到广告点击时调用。
                }
                override fun onAdImpression(impressionData: ImpressionData?) {
                    // 记录到广告展示（impression）时调用。
                }
            })
            show(activity)
        }
    }
}

测试插屏广告集成

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

我们建议使用测试广告来测试您的插屏广告集成和应用本身。

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

演示广告单元 ID：demo-interstitial-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 interstitital was integrated successfully

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

其他资源

上一篇
自适应粘性横幅
下一篇
激励广告