插屏广告

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

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

插屏广告会使用户注意力完全集中在广告上,因此单次展示成本更高。

展示效果

本指南介绍如何在 Compose Multiplatform 应用中集成插屏广告。除代码示例外,还包含格式相关建议与更多资源链接。

前提条件

  1. 请按快速入门完成 Yandex Mobile Ads Compose Multiplatform 插件集成。
  2. 请使用最新的 Yandex Mobile Ads Compose Multiplatform 插件版本。若使用聚合,请同时使用最新的统一构建版本。

实现

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

  • 在 Composable 作用域内获取 rememberInterstitialAdLoader()
  • 在协程(suspend)中通过 loadAd(AdRequest) 加载 InterstitialAd
  • 可选:在调用 show() 前为已加载的广告设置 InterstitialAdEventListener
  • 在界面就绪时(例如用户操作后)调用 show()

插屏广告集成注意事项

如果加载抛出异常或在错误处理中报告失败,请勿立即再次加载新广告。如确有必要,请限制重试次数,以避免在受限情况下持续失败请求与连接问题。

加载广告

使用 rememberInterstitialAdLoader() 创建加载器,然后使用包含 Yandex Advertising Network 界面中 adUnitIdAdRequest 调用 loadAd

可通过 AdRequest 扩展请求(targetingparameterspreferredTheme 等)。在请求中提供额外上下文数据可显著提升广告质量。详见 广告定向

加载插屏广告示例:

@Composable
fun InterstitialBlock(adUnitId: String) {
    val loader = rememberInterstitialAdLoader()
    val scope = rememberCoroutineScope()
    var interstitialAd by remember { mutableStateOf<InterstitialAd?>(null) }
    var isLoading by remember { mutableStateOf(false) }

    Button(
        onClick = {
            isLoading = true
            scope.launch {
                try {
                    interstitialAd = loader.loadAd(AdRequest(adUnitId = adUnitId))
                } catch (e: Exception) {
                    // Ad failed to load with AdRequestError.
                    // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
                }
                isLoading = false
            }
        },
        enabled = !isLoading,
    ) {
        Text(if (isLoading) "加载中..." else "加载插屏")
    }

    Button(
        onClick = {
            interstitialAd?.show()
            interstitialAd = null
        },
        enabled = interstitialAd != null,
    ) {
        Text("展示插屏")
    }
}

调试时可将 adUnitId 设为 'demo-interstitial-yandex'

展示广告

插屏广告应放在应用流程的自然停顿处,例如关卡之间或转化完成后(如文件下载完成)。

要跟踪插屏广告生命周期,请在调用 show() 前在 InterstitialAd 实例上设置 InterstitialAdEventListener

val ad = interstitialAd ?: return
ad.setAdEventListener(
    object : InterstitialAdEventListener {
        override fun onAdShown() {
            // Called when an ad is shown.
        }

        override fun onAdFailedToShow(adError: AdError) {
            // Called when an ad failed to show. Clear the reference and preload the next ad if needed.
        }

        override fun onAdDismissed() {
            // Called when ad is dismissed. Preload the next interstitial here if appropriate.
        }

        override fun onAdClicked() {
            // Called when a click is recorded for an ad.
        }

        override fun onAdImpression(impressionData: ImpressionData?) {
            // Called when an impression is recorded for an ad.
        }
    },
)
ad.show()

释放资源

onAdDismissedonAdFailedToShow 之后释放广告对象引用,必要时开始加载下一条素材。不要对已展示的广告保持强引用。

测试插屏广告集成

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

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

为了保证为每个广告请求返回测试广告,我们创建了一个特殊的演示广告版位 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

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

使用演示广告单元测试

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

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

演示广告单元 ID:demo-interstitial-yandex

重要

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

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

验证广告集成

您可以使用本机控制台工具测试广告集成。

要查看详细日志,请调用 YMAMobileAds 类的 enableLogging 方法。

YMAMobileAds.enableLogging()

要查看 SDK 日志,请前往控制台工具并设置 Subsystem = com.mobile.ads.ads.sdk。您还可以按类别和错误级别过滤日志。

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

提示

预加载广告

加载广告可能需要几秒钟的时间,具体取决于移动聚合中对接的广告网络数量和用户的互联网速度。我们建议在展示广告之前预加载广告。

提前调用 loadAd,以便在合适时机展示已加载的广告。

若要在展示当前广告后立即开始加载下一条,请将流程绑定到 onAdDismissed 事件。

如果您在太多不太可能显示的屏幕上缓存广告,您的广告效果可能会下降。例如,如果用户每次会话完成 2-3 个游戏关卡,则您不应缓存 6-7 个屏幕的广告。否则,您的广告可见性可能会降低,并且广告系统可能会降低您的应用的优先级。

为确保您为应用程序找到良好的平衡,请在 Yandex Advertising Network 界面中跟踪“收视数比例”或“可见收视数比例”指标。如果它低于 20%,可能需要修改您的缓存算法。收视数比例越高越好。

更多资源