Flutter 的奖励广告服务集成
将奖励视频广告服务集成到 Flutter 应用程序中，利用广告位、封顶、节奏和手动加载选项来优化用户参与度。
阅读时间11 分钟最后更新于 3 天前
注意
本文档与 SDK 8.6.0+ 相关。
先决条件
- 确保将 Flutter 插件集成到 app 中。
- 确保使用 LevelPlay Initialization API 初始化 SDK。
- 在 LevelPlay 后台中找到 AdUnitID。
创建奖励并注册到事件
收到回调后，您可以使用 LevelPlay 平台中定义的相关 Ad Unit ID 创建广告单元（初始化 LevelPlay SDK 步骤）。
onInitSuccess为创建的奖励广告单元设置奖励监听器，以便了解广告投放情况。
final LevelPlayRewardedAd _rewardedAd = LevelPlayRewardedAd(adUnitId: [YOUR_AD_UNIT_ID]);@overridevoid initState() { super.initState(); _rewardedAd.setListener(this);}// LevelPlayRewardedAdListener methods@overridevoid onAdLoaded(LevelPlayAdInfo adInfo) {}@overridevoid onAdLoadFailed(LevelPlayAdError error) {} @overridevoid onAdDisplayed(LevelPlayAdInfo adInfo) {}@overridevoid onAdDisplayFailed(LevelPlayAdError error, LevelPlayAdInfo adInfo) {@override void onAdClosed(LevelPlayAdInfo adInfo) {}@overridevoid onAdClicked(LevelPlayAdInfo adInfo) {} @overridevoid onAdInfoChanged(LevelPlayAdInfo adInfo) {}@overridevoid onAdRewarded(LevelPlayReward reward, LevelPlayAdInfo adInfo) {}
LevelPlay 奖励广告回调
- ：成功加载广告时提供
onAdLoaded - ：在广告加载失败时提供。包含广告单元信息
onAdLoadFailed - ：在显示广告时提供。这相当于展示
onAdDisplayed - （可选）：广告无法显示时提供
onAdDisplayFailed - ：在广告获得奖励时提供。其中包含广告单元信息和奖励信息。
onAdRewarded - （可选）：在用户点击广告时提供
onAdClicked - ：广告关闭时提供
onAdClosed - （可选）：在更新广告信息时提供。加载另一个广告后可用，并且包含更高的 CPM/速率
onAdInfoChanged
获取奖励广告详细信息
使用 getReward API 可以访问您在 LevelPlay 后台中设置的奖励数据。与其他聚合 API 不同，这是一个独立调用，在初始化后返回存储在 SDK 本地的数据。这使您能够构建动态、数据驱动的 UI，在用户参与广告之前告知他们潜在的奖励，从而无需在app中硬编码奖励值。
先决条件
在实现 getReward API 之前，请确保项目满足以下技术要求：
- SDK 初始化：调用 initSDK 并等待 onInitializationSuccess 回调以确保奖励数据已缓存。
- Ad Object 实例：在调用 API 之前，使用有效的 Ad Unit ID 实例化奖励广告对象。
- 最低 SDK 版本：使用 LevelPlay SDK 8.1.0 或更高版本（原生或 Unity 软件包）。
最佳实践
遵循这些建议可确保稳定且可预测的集成。
- 初始化成功时调用：调用 getReward 的最佳时间是初始化成功监听器器内部。这样可以确保 UI 在用户进入屏幕时就绪。
- 检查空状态：在更新 UI 之前，请始终验证该数量> 0。如果在初始化期间发生网络报错，这将确保平滑的用户体验。
- 放置/位置精度：确保在 getReward("placementName") 中使用的字符串与 LevelPlay 后台中定义的名称完全匹配。
API 结构
getReward 方法允许您从 LevelPlay 后台访问同步的奖励数据。使用此方法可以查询本地 SDK 缓存中指定的广告放置/位置或全局广告单元默认值。
getReward
获取指定的广告放置/位置或默认广告单元的奖励名称和金额。没有其他参数可以使用。
- ：在 LevelPlay 后台中定义的放置/位置的唯一标识符。通道
placementName，用于获取广告单元的默认奖励。null
返回一个 LevelPlayReward 对象，其中包含名称（字符串）和金额（int）。
初始设置
getReward API 充当 LevelPlay SDK 的核心组件，在如下逻辑下运行以确保数据无延迟可用：
- 集成功能：由于奖励数据是在初始 SDK 设置期间获取的，因此 API 调用是即时的，不需要网络请求。
- 编辑器配置：将 app 与 LevelPlay SDK 集成后，API 可以立即使用。测试此功能不需要额外的资源或插件。
了解奖励选择逻辑
API 根据指定的层级视图返回 LevelPlayReward 对象。了解此逻辑有助于排除出现指定的奖励的原因。
- 放置/位置级别：如果在调用中提供了有效的广告放置/位置称，SDK 将返回控制面板中为该广告位放置/位置的指定的奖励。
- 广告单元级别：如果广告放置/位置名称为 null 或未找到，SDK 将回退到为广告单元定义的默认奖励。
- 回退状态：如果在初始化完成之前调用 API，则返回一个字符串名称为空且值为 0 的奖励对象。
动态更新 UI
使用 getReward API 可将静态按钮变换为高意图的行动调用。例如：您可以显示“Watch to earn 50 Gold”，而不是通用的“Watch Video”按钮。
- 验证金额：在更新 UI 组件之前，请务必验证 reward.amount > 0。
- 事件驱动的更新：在初始化成功监听器器中调用 API 以确保 UI 在用户进入屏幕时准确无误。
- 区分大小写：确保代码中的放置/位置名称字符串与 LevelPlay 后台完全匹配；不匹配的字符串将触发器广告单元回退。
getReward API 实现故障排除
- 奖励金额返回 0：如果在 onInitializationSuccess 回调之前调用 API，通常会发生这种情况。在查询奖励之前，请确保 SDK 完全准备就绪。
- 显示的错误奖励类型：检查是否有多个广告位。如果放置/位置名称拼写错误，SDK 默认认为主广告单元奖励，而不是指定的广告放置/位置奖励。
加载奖励广告
收到 onInitSuccess 回调后，即可加载奖励广告。应使用 方法执行此操作：
_rewardedAd.loadAd();
显示奖励广告
您可以在收到 onAdLoaded 回调后使用 showAd API 展示奖励广告。
如果使用广告位，请将广告位名称作为 API 的一部分共享，如下所示。
// Show ad without placement_rewardedAd.showAd();// Show ad with placement_rewardedAd.showAd(placement: [YOUR_PLACEMENT]);
检查广告就绪状态
为了避免显示失败，并确保广告可以正确显示，建议在调用 showAd() API 之前使用以下 API。
- ：如果广告加载成功并且广告单元未设置上限，则返回 true，否则返回 false。
isAdReady - ：限制有效放置/位置时返回 true。如果放置/位置无效或未设置上限，此 API 将返回 false。
isPlacementCapped
// Check that ad is ready and that the placement is not capped if(_rewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped([YOUR_PLACEMENT])) { _rewardedAd.showAd(placement:[YOUR_PLACEMENT]);}
广告成功展示给玩家后，您可以加载另一个广告，重复加载奖励广告步骤。一时间加载单个广告时，无需创建新的广告实体。
动态 UserId
动态 UserID 是一个参数，用于验证可在整个会话中更改的 AdRewarded 交易。您将通过服务器到服务器的广告奖励回调收到此参数，必须在调用 showAd 之前设置此参数。
- 字符字符串必须为 1 到 64 个字母数字角色。
- 您将在回调网址中收到一个 参数以及奖励详细信息。
dynamicUserId
LevelPlay.setDynamicUserId("userId");
奖励用户
LevelPlay SDK 将在用户每次成功完成视频时触发。
onAdRewardedonAdRewardedonAdClosedonAdClosedonAdRewarded@overridevoid onAdRewarded(LevelPlayReward reward, LevelPlayAdInfo adInfo) { // Implement logic to grant the reward to the user}
多个广告单元奖励 API
Category | 旧版 | Ad Unit（广告单元）（新） |
|---|---|---|
| 类 | | |
| API | | |
| API | | |
| API | | |
| API | | |
| API | | |
| API | | |
奖励广告的完整实现示例
final LevelPlayRewardedAd _rewardedAd = LevelPlayRewardedAd(adUnitId:'YOUR_AD_UNIT_ID');@overridevoid initState() { super.initState(); _rewardedAd.setListener(this); _rewardedAd.loadAd();}@overridevoid onAdRewarded(LevelPlayReward reward, LevelPlayAdInfo adInfo) { // Implement your logic here...}@overridevoid onAdClicked(LevelPlayAdInfo adInfo) { // Implement your logic here...}@overridevoid onAdClosed(LevelPlayAdInfo adInfo) { // Implement your logic here...}@overridevoid onAdDisplayFailed(LevelPlayAdError error, LevelPlayAdInfo adInfo) { // Implement your logic here...}@overridevoid onAdDisplayed(LevelPlayAdInfo adInfo) { // Implement your logic here...}@overridevoid onAdInfoChanged(LevelPlayAdInfo adInfo) { // Implement your logic here...}@overridevoid onAdLoadFailed(LevelPlayAdError error) { // Implement your logic here...}@overridevoid onAdLoaded(LevelPlayAdInfo adInfo) { // Implement your logic here, for example showing the ad _rewardedAd.showAd();}// Rest of the widget// End of widget...