应用开屏广告

开屏广告是一种特殊的广告格式，用于通过应用加载屏幕变现。这些广告可以随时关闭，并且旨在当用户将您的应用带到前台时（无论是在启动时还是从后台返回时）投放。

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

外观

应用开屏广告会显示 Go to the app 按钮，以便用户知晓当前处于您的应用内并可以关闭广告。 以下为该广告的外观示例：

前置条件

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"))
}

实现

1. 在应用启动时初始化 SDK。
2. 使用 rememberAppOpenAdLoader() 创建广告加载器。
3. 使用挂起函数 loadAd() 加载广告。
4. 使用 show(Activity) 方法展示广告。

关键步骤

1. 在应用启动时初始化 SDK。

   YandexAds.initialize(this) {
       // 现在可以使用广告功能
   }
   

2. 使用 rememberAppOpenAdLoader() 创建广告加载器。

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

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

   import com.yandex.mobile.ads.compose.rememberAppOpenAdLoader
   
   @Composable
   fun SplashScreen(activity: Activity) {
       val loader = rememberAppOpenAdLoader()
       val AD_UNIT_ID = "R-M-XXXXXX-Y" // 测试可使用 "demo-appopenad-yandex"
   }
   

3. 在 LaunchedEffect 中通过挂起函数 loadAd() 加载广告。

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

4. 使用 show 方法展示广告。

   LaunchedEffect(appOpenAd) {
       appOpenAd?.show(activity)
   }
   

   备注

   如果广告已经投放，调用 show(Activity) 方法将在 AppOpenAdEventListener.onAdFailedToShow(AdError) 中返回显示错误。

完整示例

import com.yandex.mobile.ads.appopenad.AppOpenAdLoadResult
import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.rememberAppOpenAdLoader

@Composable
fun SplashScreen(activity: Activity) {
    var appOpenAd by remember { mutableStateOf<AppOpenAd?>(null) }

    val loader = rememberAppOpenAdLoader()

    // 进入 Composable 后立即加载
    LaunchedEffect(Unit) {
        when (val result = loader.loadAd(AdRequest.Builder("R-M-XXXXXX-Y").build())) {
            is AppOpenAdLoadResult.Success -> appOpenAd = result.ad
            is AppOpenAdLoadResult.Failure -> Log.e("YandexAds", result.error.description)
        }
    }

    LaunchedEffect(appOpenAd) {
        appOpenAd?.show(activity)
    }
}

应用开屏广告集成注意事项

1. 所有对 Yandex Mobile Ads SDK 的方法调用均须在主线程执行。
2. 加载可能耗时较长，若广告尚未加载完成，请勿因此阻塞冷启动流程。
3. 请提前预加载广告，以便在后续热启动时展示。
4. 不建议在应用启动时同时加载应用开屏广告与其他广告格式，因为此时应用可能正在下载所需数据，容易加重设备与网络负担，导致广告加载变慢。
5. 若在 AppOpenAdLoadResult.Failure 中收到错误，请勿立即尝试加载新广告。若必须重试，请限制重试次数，以免在受限网络环境下出现连续失败请求与连接问题。

测试应用开屏广告集成

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

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

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

演示广告单元 ID：demo-appopenad-yandex。

您可以在 用于测试的演示广告单元 版块找到可用的演示广告版位 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 App Open Ad was integrated successfully

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

建议

1. 请勿在加载界面（启动页）之前展示应用开屏广告。

   先展示加载界面可使用户体验更清晰：用户能明确知道打开了哪个应用，减少困惑。您可在该界面通过加载指示器或文案提示用户，说明广告结束后将恢复应用内容。

2. 若从发起广告请求到实际展示之间存在延迟，用户可能短暂进入应用后又突然看到与当前内容无关的广告，影响体验，应尽量避免。一种做法是在展示主内容前使用加载页，并从该页开始展示广告。若加载页之后立即进入某段内容，则不宜在该时机展示广告。

3. 对新用户应待其多次打开并使用应用后再展示应用开屏广告。仅向满足特定应用内条件的用户展示（例如完成某关卡、打开次数达到阈值、未参与激励任务等）。安装完成后请勿立即展示。

4. 根据用户在应用内的行为调节展示频率，勿在每次冷启动/热启动时都展示。

5. 仅当应用在后台停留一定时间后再展示（例如 30 秒、2 分钟、15 分钟等，可按产品策略设定）。

6. 请务必进行充分测试：各应用差异较大，需在提升收入与留存、使用时长之间找到适合自身的策略。用户行为会随时间变化，建议定期评估应用开屏广告的展示策略。

其他资源

• GitHub 链接。