激励广告

激励广告是一种受欢迎的全屏广告格式，用户观看广告后会获得奖励。

这种广告类型的显示由用户激活，例如，为了在游戏中获得奖励或额外生命。

高度的用户积极性使得这种广告格式成为免费应用中最受欢迎和最具盈利性的广告格式。

外观

本指南说明如何借助 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"))
}

实现

集成激励广告的关键步骤：

  • 使用 rememberRewardedAdLoader() 创建广告加载器。
  • 通过挂起函数 loadAd() 加载广告，并处理 RewardedAdLoadResult。
  • 注册 RewardedAdEventListener 以接收广告事件回调。
  • 展示 RewardedAd。
  • 在用户观看完毕后发放奖励。

激励广告集成注意事项

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

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

  3. 建议在发生广告交互的整个界面生命周期内对广告对象保持强引用。

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

加载广告

使用 rememberRewardedAdLoader() 加载激励广告。通过挂起函数 loadAd() 执行加载，其返回值为 RewardedAdLoadResult。

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

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

以下示例展示如何加载激励广告：

import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.rememberRewardedAdLoader
import com.yandex.mobile.ads.rewarded.RewardedAdLoadResult

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

    val loader = rememberRewardedAdLoader()

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

展示广告

激励广告是一种基于激励的广告格式，允许用户因观看广告而获得奖励。奖励可能是额外的生命或在游戏中晋级到下一个级别。激励广告是在应用级别确定的。

要跟踪激励广告生命周期事件并发放奖励，请在 RewardedAd 对象上设置 RewardedAdEventListener 回调。

在调用 show() 时，奖励会通过 onRewarded 回调直接传递：

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

    val loader = rememberRewardedAdLoader()

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

    LaunchedEffect(rewardedAd) {
        rewardedAd?.apply {
            setAdEventListener(object : RewardedAdEventListener {
                override fun onAdShown() {
                    // 广告已展示时调用。
                }

                override fun onAdFailedToShow(adError: AdError) {
                    // RewardedAd 展示失败时调用。
                    // 此时可预加载下一条激励广告。
                    loadRewardedAd()
                }

                override fun onAdDismissed() {
                    // 广告已关闭时调用。
                    // 此时可预加载下一条激励广告。
                    loadRewardedAd()
                }

                override fun onAdClicked() {
                    // 记录到广告点击时调用。
                }

                override fun onAdImpression(impressionData: ImpressionData?) {
                    // 记录到广告展示（impression）时调用。
                }

                override fun onRewarded(reward: Reward) {
                    // 用户满足领奖条件时调用。
                }
            })
            show(activity)
        }
    }
}

测试激励广告集成

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

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

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

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

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

其他资源

上一篇
插屏广告
下一篇
开屏广告