---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/compose-multiplatform/rewarded.md
  - https://ads.yandex.com/helpcenter/ru/dev/compose-multiplatform/rewarded.md
  - https://ads.yandex.com/helpcenter/zh/dev/compose-multiplatform/rewarded.md
---
> **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 %}

本指南展示了如何将激励广告集成到 Compose Multiplatform 应用中。
除了代码示例和说明之外，它还包含特定格式的建议和其他资源的链接。

## 前提条件 {#pre}

<!-- source: zh/dev/_includes/pre-compose-multiplatform.md -->
1. 按照[快速入门](https://ads.yandex.com/helpcenter/zh/dev/compose-multiplatform/quick-start.md)中的流程集成 Yandex Mobile Ads Compose Multiplatform 插件。
2. 确保您运行的是最新的 [Yandex Mobile Ads Compose Multiplatform 插件](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)版本。 如果您使用聚合，请确保运行最新版本的[统一构建](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)。
<!-- endsource: zh/dev/_includes/pre-compose-multiplatform.md -->

## 实施 {#implement}

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

1. 使用 `rememberRewardedAdLoader()` 创建广告加载器。
2. 通过挂起函数 `loadAd()` 加载广告。
3. 在调用 `show()` 之前，可选择为已加载的广告设置 `RewardedAdEventListener`。
4. 使用 `show()` 展示广告。

## 激励广告集成的特点 {#features}

如果错误处理期间加载失败，请不要立即再次尝试加载新广告。 如果没有其他选项，请限制广告加载重试次数。 这将有助于避免在出现限制时持续出现不成功的请求。

## 加载广告

使用 `rememberRewardedAdLoader()` 和 `loadAd`，并传入 `AdRequest`，其中包含来自 Yandex Advertising Network 界面的 `adUnitId`。 在加载失败时，`loadAd` 会从 `com.yandex.mobile.ads.kmp.common` 中抛出 `AdLoadException`。

您可以通过 `AdRequest` 扩展请求（`targeting`、`parameters`、`preferredTheme` 等）。 在请求中提供额外的上下文数据可以显著提高您的广告质量。 详情请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/compose-multiplatform/target.md)部分。

激励广告加载示例：

```kotlin
@Composable
fun RewardedBlock(adUnitId: String) {
    val loader = rememberRewardedAdLoader()
    val scope = rememberCoroutineScope()
    var rewardedAd by remember { mutableStateOf<RewardedAd?>(null) }
    var isLoading by remember { mutableStateOf(false) }

    Button(
        onClick = {
            isLoading = true
            scope.launch {
                try {
                    rewardedAd = loader.loadAd(AdRequest(adUnitId = adUnitId))
                } catch (e: AdLoadException) {
                    // 加载错误：e.error (AdRequestError)。 不建议无限制重试。
                }
                isLoading = false
            }
        },
        enabled = !isLoading,
    ) {
        Text(if (isLoading) "Loading..." else "Load rewarded")
    }

    Button(
        onClick = { rewardedAd?.show() },
        enabled = rewardedAd != null,
    ) {
        Text("Show rewarded")
    }
}
```

为了进行调试，您可以使用 `'demo-rewarded-yandex'` 作为 `adUnitId`。

## 广告渲染

激励广告是一种基于激励的广告格式：用户在观看广告后会获得奖励（额外生命、进入下一关卡等）。 奖励由应用决定。

为跟踪激励广告生命周期并发放奖励，请先为 `RewardedAd` 实例设置 `RewardedAdEventListener`，然后再调用 `show()`。

```kotlin
val ad = rewardedAd ?: return
ad.setAdEventListener(
    object : RewardedAdEventListener {
        override fun onAdShown() {
            // 广告展示时调用。
        }

        override fun onAdFailedToShow(adError: AdError) {
            // 广告无法展示时调用。
        }

        override fun onAdDismissed() {
            // 广告关闭时调用。 在适当情况下，预加载下一个激励广告。
        }

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

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

        override fun onRewarded(reward: Reward) {
            // 发放奖励：reward.type、reward.amount
        }
    },
)
ad.show()
```

## 释放资源

在 `onAdDismissed` 或 `onAdFailedToShow` 之后，删除对广告对象的引用，并在需要时开始加载下一个创意。 不要保持对已展示广告的强引用。

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

{% list tabs %}

- Android

   <!-- 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 -->

- iOS

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

   <!-- source: zh/dev/_includes/test-ios-rewarded.md -->
   我们建议使用测试广告来测试您的广告集成和应用本身。

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

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

   {% note warning %}

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

   {% endnote %}

   您可以在 [用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/ios/demo-blocks.md) 版块找到可用的演示广告版位 ID 列表。
   <!-- endsource: zh/dev/_includes/test-ios-rewarded.md -->

   ### 测试广告集成

   <!-- source: zh/dev/_includes/test-integration-ios.md -->
   您可以使用本机控制台工具测试广告集成。

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

   ```swift
   YMAMobileAds.enableLogging()
   ```

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

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

   <img src= "https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/common/integration-ios-2.png">
   <!-- endsource: zh/dev/_includes/test-integration-ios.md -->

{% endlist %}

## 提示

### 广告预加载

<!-- source: zh/dev/_includes/preload.md -->
加载广告可能需要几秒钟的时间，具体取决于移动聚合中对接的广告网络数量和用户的互联网速度。我们建议在展示广告之前预加载广告。
<!-- endsource: zh/dev/_includes/preload.md -->

提前调用 `LoadAd`，以在适当的时刻展示加载的广告。

要在投放当前广告后立即开始加载下一个广告，请将此进程绑定到 `onAdDismissed` 事件。

<!-- source: zh/dev/_includes/cash-ads.md -->
如果您在太多不太可能显示的屏幕上缓存广告，您的广告效果可能会下降。例如，如果用户每次会话完成 2-3 个游戏关卡，则您不应缓存 6-7 个屏幕的广告。否则，您的广告可见性可能会降低，并且广告系统可能会降低您的应用的优先级。

为确保您为应用程序找到良好的平衡，请在 Yandex Advertising Network 界面中跟踪“收视数比例”或“可见收视数比例”指标。如果它低于 20%，可能需要修改您的缓存算法。收视数比例越高越好。
<!-- endsource: zh/dev/_includes/cash-ads.md -->

## 其他资源 {#resources}

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