---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/android/compose/rewarded.md
  - https://ads.yandex.com/helpcenter/ru/dev/android/compose/rewarded.md
  - https://ads.yandex.com/helpcenter/zh/dev/android/compose/rewarded.md
  - href: zh/dev/android/compose/rewarded.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt


# 激励广告

<!-- source: zh/dev/_includes/rewarded.md -->
激励广告是一种受欢迎的全屏广告格式，用户观看广告后会获得奖励。
<!-- endsource: zh/dev/_includes/rewarded.md -->

<!-- source: zh/dev/_includes/rewarded.md -->
广告展示采用主动选择机制：例如，用户可以主动触发广告以获取游戏奖励或额外生命值。
<!-- endsource: zh/dev/_includes/rewarded.md -->

<!-- source: zh/dev/_includes/rewarded.md -->
强烈的用户动机使这种广告格式成为免费应用中最受欢迎且盈利能力最强的广告格式。
<!-- endsource: zh/dev/_includes/rewarded.md -->

{% cut "外观" %}

{% list tabs %}

- 文本和图形广告

  <iframe width="200" height="405.5" allow="autoplay" src="https://runtime.strm.yandex.ru/player/video/vplvwvhqbegh6vee44kp?autoplay=1&mute=0&loop=1" frameborder="0" allowfullscreen></iframe>

- 视频广告

  <iframe width="200" height="405.5" allow="autoplay" src="https://runtime.strm.yandex.ru/player/video/vplvozdigmqlrtjfki7o?autoplay=1&mute=0&loop=1" frameborder="0" allowfullscreen></iframe>

{% endlist %}

{% endcut %}

本指南展示了如何使用 Jetpack Compose 扩展将激励广告集成到 Android 应用中。 除了代码示例和说明之外，它还提供使用此广告格式的建议和其他资源的链接。

## 前提条件 {#pre}

<!-- source: zh/dev/_includes/pre-android.md -->
1. 按照[快速入门](https://ads.yandex.com/helpcenter/zh/dev/android/quick-start.md) 中描述的 SDK 集成步骤进行操作。
2. 首先，您需要[初始化](https://ads.yandex.com/helpcenter/zh/dev/android/quick-start.md#init) 广告 SDK。
3. 确保您使用的是[最新Yandex Mobile Ads SDK 版本](https://ads.yandex.com/helpcenter/zh/dev/android/changelog-android.md)。如果您使用的是广告中介服务，请更新至最新的[单一构建版本](https://ads.yandex.com/helpcenter/zh/dev/android/changelog-android.md)。
<!-- endsource: zh/dev/_includes/pre-android.md -->

<!-- source: zh/dev/_includes/pre-jetpack-compose.md -->
要使用 Compose 扩展，请在 `build.gradle.kts` 中添加依赖：

```kotlin
dependencies {
    implementation("com.yandex.android:mobileads:8.2.0")
    implementation("com.yandex.android:mobileads-compose:8.2.0")

    // Compose BOM (最低版本 2024.01.00)
    implementation(platform("androidx.compose:compose-bom:2025.03.00"))
}
```
<!-- endsource: zh/dev/_includes/pre-jetpack-compose.md -->

## 实施 {#implement}

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

1. 使用 `rememberRewardedAdLoader()` 创建广告加载器。
1. 通过挂起函数 `loadAd()` 加载广告，并处理 `RewardedAdLoadResult`。
1. 为广告事件回调 `RewardedAdEventListener` 注册监听器。
1. 展示 `RewardedAd`。
1. 为用户发放观看广告的奖励。

## 激励广告集成说明 {#features}

1. 所有 Yandex Mobile Ads SDK 方法调用都必须在主线程中进行。

2. 如果您在 `RewardedAdLoadResult.Failure` 中收到错误，请不要尝试立即加载新广告。 如果必须重试，请限制重新加载尝试次数，以避免在条件受限的情况下请求持续失败并出现连接问题。

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

4. 当可组合项从组合树中移除时，`cancelLoading()` 将自动调用 — 无需显式释放加载器资源。

## 加载广告 {#load}

要加载激励广告，请使用 `rememberRewardedAdLoader()`。 加载通过挂起函数 `loadAd()` 执行，该函数返回 `RewardedAdLoadResult`。

要加载广告，您需要从 Yandex Advertising Network 界面获取广告单元 ID (adUnitId)。

您可以通过 `AdRequest.Builder()` 传递用户兴趣数据、页面上下文数据、位置或其他附加数据来扩展广告请求参数。 请求中的附加上下文数据可以显著提高广告质量。 有关更多信息，请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/android/target.md)。

### 激励广告加载示例

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

    val loader = rememberRewardedAdLoader()

    LaunchedEffect(Unit) {
        val adRequest = AdRequest.Builder("your-ad-unit-id").build()
        when (val result = loader.loadAd(adRequest)) {
            is RewardedAdLoadResult.Success -> rewardedAd = result.ad
            is RewardedAdLoadResult.Failure -> {
                // Ad failed to load with AdRequestError.
                // Attempting to load a new ad from here is strongly discouraged.
            }
        }
    }
}
```

## 展示广告 {#ad-view}

<!-- source: zh/dev/_includes/rewarded.md -->
激励广告是一种激励型广告格式，允许用户通过观看广告来获得奖励。这些奖励可能包括额外生命值或游戏中的晋级机会。具体奖励形式由应用自身决定。
<!-- endsource: zh/dev/_includes/rewarded.md -->

为了跟踪激励广告生命周期事件并获得奖励，请为 `RewardedAd` 对象设置 `RewardedAdEventListener` 回调监听器。

调用 `show()` 方法时，奖励会直接传递到 `onRewarded` 回调：

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

    val loader = rememberRewardedAdLoader()

    LaunchedEffect(Unit) {
        val adRequest = AdRequest.Builder("your-ad-unit-id").build()
        when (val result = loader.loadAd(adRequest)) {
            is RewardedAdLoadResult.Success -> rewardedAd = result.ad
            is RewardedAdLoadResult.Failure -> {
                // Ad failed to load with AdRequestError.
            }
        }
    }

    LaunchedEffect(rewardedAd) {
        rewardedAd?.apply {
            setAdEventListener(object : RewardedAdEventListener {
                override fun onAdShown() {
                    // Called when ad is shown.
                }

                override fun onAdFailedToShow(adError: AdError) {
                    // Called when an RewardedAd failed to show.
                    // Now you can preload the next rewarded ad.
                    loadRewardedAd()
                }

                override fun onAdDismissed() {
                    // Called when ad is dismissed.
                    // Now you can preload the next rewarded ad.
                    loadRewardedAd()
                }

                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.
                }

                override fun onRewarded(reward: Reward) {
                    // Called when the user can be rewarded.
                }
            })
            show(activity)
        }
    }
}
```

## 测试激励广告集成 {#test}

<!-- source: zh/dev/_includes/test-android-rewarded.md -->
### 使用演示广告单元进行广告测试 {#demo-blocks}

使用测试广告来检查您的激励广告集成和应用本身。为了确保每次广告请求都能返回测试广告，您可以使用一个特殊的演示广告版位 ID。

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

{% note warning %}

在应用商店发布应用前，请务必将演示广告版位 ID 替换为您在 Yandex Advertising Network 接口中获取的真实 ID。

{% endnote %}

有关所有可用演示广告版位 ID 的列表，请参阅[用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/android/demo-blocks.md)。

### 测试广告集成 {#test-int}

您可以使用 SDK 的内置分析工具检查激励广告是否已正确集成。日志中将显示包含测试结果的详细报告。

要查看报告，请在 Android 应用调试工具 [Logcat](https://developer.android.com/studio/command-line/logcat) 中搜索关键词“YandexAds”。
```bash
adb logcat -v brief '*:S YandexAds'
```

如果集成成功，将返回以下消息：
```bash
adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type rewarded was integrated successfully
```

如果存在任何激励广告集成问题，您将收到详细的问题报告和故障排除建议。
<!-- endsource: zh/dev/_includes/test-android-rewarded.md -->

## 其他资源 {#resources}

* <!-- source: zh/dev/_includes/github-pubdev-links.md -->
  [GitHub](https://github.com/yandexmobile/yandex-ads-sdk-android) 链接。
  <!-- endsource: zh/dev/_includes/github-pubdev-links.md -->