---
metadata:
- name: generator
content: Diplodoc Platform v5.52.0
alternate:
- https://ads.yandex.com/helpcenter/en/dev/flutter/rewarded.md
- https://ads.yandex.com/helpcenter/ru/dev/flutter/rewarded.md
- https://ads.yandex.com/helpcenter/zh/dev/flutter/rewarded.md
- href: zh/dev/flutter/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
# 激励广告
激励广告是一种受欢迎的全屏广告格式，用户观看广告后会获得奖励。
广告展示采用主动选择机制：例如，用户可以主动触发广告以获取游戏奖励或额外生命值。
强烈的用户动机使这种广告格式成为免费应用中最受欢迎且盈利能力最强的广告格式。
{% cut "外观" %}
{% list tabs %}
- 文字和图片广告
- 视频广告
{% endlist %}
{% endcut %}
本指南将展示如何将插屏广告集成到 Flutter 应用中。
除了代码示例和说明之外，本指南还包含特定于格式的建议和其他资源的链接。
## 前提条件 {#pre}
1. 按照 [快速入门](https://ads.yandex.com/helpcenter/zh/dev/flutter/quick-start.md) 中的流程集成 Yandex Mobile Ads Flutter 插件。
2. 确保您运行的是最新的 [Yandex Mobile Ads Flutter 插件](https://ads.yandex.com/helpcenter/zh/dev/platforms.md) 版本。如果您使用聚合，请确保您运行的是最新版本的 [统一构建](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)。
## 实施 {#implement}
集成激励广告的关键步骤：
* 创建并配置 `RewardedAdLoader` 广告加载器。
* 加载 `RewardedAd` 广告。
* 为广告回调方法注册 `RewardedAdEventListener` 监听器。
* 呈现 `RewardedAd`。
* 奖励观看广告的用户。
## 激励广告集成的特点 {#features}
如果您在 `onAdFailedToLoad()` 回调中收到错误，请不要尝试再次加载新广告。如果没有其他选项，请限制广告加载重试次数。这将有助于避免出现限制时持续出现不成功的请求和连接问题。
## 加载广告
要加载激励广告，请创建并设置 `RewardedAdLoader` 对象。
为此，请调用 `RewardedAdLoader.create(onAdLoaded, onAdFailedToLoad)` 方法并向其传递加载器回调监听器。
这需要 Activity 上下文和来自 Yandex Advertising Network 界面 (adUnitId) 的广告单元 ID。
您可以通过 `AdRequestConfiguration`扩展广告请求参数集，在构造函数中传递用户兴趣、上下文应用数据、位置详细信息或其他数据。在请求中提供额外的上下文数据可以显着提高您的广告质量。请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/flutter/target.md)版块了解更多信息。
以下示例展示了如何加载激励广告：
```dart
late final Future _adLoader;
RewardedAd? _ad;
@override
void initState() {
super.initState();
YandexAds.initialize();
_adLoader = _createRewardedAdLoader();
_loadRewardedAd();
}
Future _createRewardedAdLoader() {
return RewardedAdLoader.create(
onAdLoaded: (RewardedAd rewardedAd) {
// 广告加载成功。现在您可以显示已加载的广告
_ad = rewardedAd;
},
onAdFailedToLoad: (error) {
// 广告加载失败，出现 AdRequestError。
// 强烈建议不要尝试通过 onAdFailedToLoad() 方法加载新广告。
},
);
}
Future _loadRewardedAd() async {
final adLoader = await _adLoader;
await adLoader.loadAd(adRequestConfiguration: AdRequestConfiguration(adUnitId: 'R-M-XXXXXX-Y')); // 为了调试，您可以使用 'demo-rewarded-yandex'
}
```
## 广告呈现
激励广告是一种基于激励的广告形式，在用户观看广告后给予他们奖励。奖励可能是额外的生命或在游戏中晋级到下一个级别。奖励格式是在应用级别确定的。
要跟踪激励广告生命周期并发放奖励，请为 `RewardedAd` 对象设置 `RewardedAdEventListener` 回调方法监听器。
要展示激励广告，请使用 `show()` 方法。要等待观看完成，请使用 `waitForDismiss()` 方法：
```dart
_showAd() async {
_ad?.setAdEventListener(
eventListener: RewardedAdEventListener(
onAdShown: () {
// 广告展示时调用。
},
onAdFailedToShow: (error) {
// 广告展示失败时调用。
// 销毁广告，这样就不会再次展示该广告。
_ad?.destroy();
_ad = null;
// 现在您可以预加载下一个广告。
_loadRewardedAd();
},
onAdClicked: () {
// 记录广告点击时调用。
},
onAdDismissed: () {
// 广告关闭时调用。
// 销毁广告，这样就不会再次展示该广告。
_ad?.destroy();
_ad = null;
// 现在您可以预加载下一个广告。
_loadRewardedAd();
},
onAdImpression: (impressionData) {
// 记录广告展示次数时调用。
},
onRewarded: (Reward reward) {
// 当用户可以获得奖励时调用。
}
));
await _ad?.show();
final reward = await _ad?.waitForDismiss();
if (reward != null) {
print('got ${reward.amount} of ${reward.type}');
}
}
```
## 释放资源
针对之前展示的广告调用 `destroy()` 方法。这可以释放资源并防止内存泄漏。
不要存储先前呈现的广告的链接。
您可以使用 `onAdDismissed` 回调方法执行以下操作：
```dart
_ad?.setAdEventListener(
eventListener: RewardedAdEventListener(
//...
onAdDismissed: () {
_ad?.destroy();
_ad = null;
},
//...
));
```
## 测试激励广告集成 {#test}
{% list tabs %}
- Android
### 使用演示广告单元进行广告测试 {#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
```
如果存在任何激励广告集成问题，您将收到详细的问题报告和故障排除建议。
- iOS
### 使用演示广告单元进行广告测试
我们建议使用测试广告来测试您的广告集成和应用本身。
为了保证为每个广告请求返回测试广告，我们创建了一个特殊的演示广告版位 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 列表。
### 测试广告集成
您可以使用本机控制台工具测试广告集成。
要查看详细日志，请调用 `YMAMobileAds` 类的 `enableLogging` 方法。
```swift
YMAMobileAds.enableLogging()
```
要查看 SDK 日志，请前往控制台工具并设置 `Subsystem = com.mobile.ads.ads.sdk`。您还可以按类别和错误级别过滤日志。
如果您在集成广告时遇到问题，您将获得有关问题的详细报告以及如何解决这些问题的建议。
{% endlist %}
## 提示
### 广告预加载
加载广告可能需要几秒钟的时间，具体取决于移动聚合中对接的广告网络数量和用户的互联网速度。我们建议在展示广告之前预加载广告。
提前调用 `load` 以在适当的时刻显示加载的广告。
要在投放当前广告后立即开始加载下一个广告，请将此进程绑定到 `onAdDismissed()` 事件。
如果您在太多不太可能显示的屏幕上缓存广告，您的广告效果可能会下降。例如，如果用户每次会话完成 2-3 个游戏关卡，则您不应缓存 6-7 个屏幕的广告。否则，您的广告可见性可能会降低，并且广告系统可能会降低您的应用的优先级。
为确保您为应用程序找到良好的平衡，请在 Yandex Advertising Network 界面中跟踪“收视数比例”或“可见收视数比例”指标。如果它低于 20%，可能需要修改您的缓存算法。收视数比例越高越好。
## 其他资源 {#resources}
*
[Pub.dev](https://pub.dev/packages/yandex_mobileads/example) 链接。