迁移到 Android 的奖励广告单元 API
通过初始化 SDK、创建具有广告单元 ID 的奖励广告对象以及实现广告事件的监听器，迁移到 LevelPlay 奖励广告单元 API。
阅读时间8 分钟最后更新于 2 天前
本指南介绍如何从 SDK 9.0.0 版本开始集成 LevelPlay API，使用广告单元 ID 作为瀑布流标识符来加载和显示奖励广告服务。
在 LevelPlay 平台中找到广告单元 ID
要加载和显示奖励广告服务，需要使用 LevelPlay 聚合平台中的广告单元 ID：
- 在 LevelPlay 帐户中，导航到 Setup > Ad Units。
- 复制奖励的广告单元 ID 并将其集成到代码中。
初始化 LevelPlay SDK
要初始化 LevelPlay SDK，请执行以下步骤：
- 实现初始化成功和失败的回调。
- 使用 appKey 和用户 ID（如果相关）调用 LevelPlay init API。
LevelPlayInitRequest initRequest = new LevelPlayInitRequest.Builder(appKey) .withUserId("UserID") .build();LevelPlayInitListener initListener = new LevelPlayInitListener() { } @Override public void onInitFailed(@NonNull LevelPlayInitError 报错) { @Override public void onInitSuccess(LevelPlayConfiguration configuration) {};LevelPlay.init(context, initRequest, initListener);
LevelPlay 初始化监听器
onInitSuccess：初始化成功完成时触发。收到此指示后，您可以创建和加载广告。
onInitFailed：未成功检索配置，无法加载广告服务。建议稍后尝试并初始化 LevelPlay SDK（当互联网连接可用或故障原因得到解决时）。
初始化 | 旧版 | 广告单元（新） |
|---|---|---|
| API | IronSource.init | LevelPlay.init |
| 回调 | onInitializationComplete | onInitSuccess |
| – | onInitFailed |
创建奖励广告对象
必须在收到 onInitSuccess 回调后执行奖励广告对象的创建。
该对象是可重用的实例，可以处理多个加载并在整个会话中显示。创建后，应使用 来加载和展示同一广告单元的广告服务。
对于更高级的实现，如有必要，您可以创建多个奖励广告对象。
// 创建奖励广告mRewardedAd = new LevelPlayRewardedAd("adUnitId");
注册到奖励事件
为创建的奖励广告单元设置奖励监听器，以便了解广告投放情况。
- 建议在加载奖励广告之前设置监听器。
- 每个奖励广告都应有自己的监听器实现。
- 回调在主线程上运行。
// 创建奖励广告mRewardedAd = new LevelPlayRewardedAd("adUnitId");// 设置监听器mRewardedAd.setListener(this);// LevelPlayRewardedAdListener methods@Overridepublic void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdLoadFailed(@NonNull LevelPlayAdError error) {}@Overridepublic void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdDisplayFailed(@NonNull LevelPlayAdError error, @NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {}
LevelPlay 奖励广告回调
onAdLoaded：成功加载广告时提供。
onAdLoadFailed：在广告加载失败时提供。包含广告单元信息。
onAdDisplayed：在显示广告时提供。这相当于展示。
onAdDisplayFailed：广告无法显示时提供。
onAdRewarded：在广告获得奖励时提供。其中包含广告单元信息和奖励信息。
onAdClicked（可选）：在用户点击广告时提供。
onAdClosed：在广告关闭时提供。
onAdInfoChanged（可选）：在更新广告信息时提供。加载另一个广告后可用，并且包含更高的 CPM/速率。
组件 | 旧版 | 广告单元（新） |
|---|---|---|
| 监听器 | IronSourceRewardedVideoEvents | LevelPlayRewardedAd |
| 回调 | onAdReady | onAdLoaded |
| onAdLoadFailed | onAdLoadFailed | |
| onAdOpened | onAdDisplayed | |
| onAdClosed | onAdClosed | |
| onAdShowFailed | onAdDisplayFailed | |
| onAdRewarded | onAdRewarded | |
| onAdClicked | onAdClicked | |
| onAdShowSucceeded | n/a（已弃用） | |
| n/a | onAdInfoChanged |
加载奖励广告
收到 onInitSuccess 回调后，即可加载奖励广告。应使用 方法执行此操作：
// 加载或重新加载广告mRewardedAd.loadAd();
显示奖励广告
您可以在收到 onAdLoaded 回调后使用 showAd API 展示奖励广告。
如果使用广告位，请将广告位名称作为 API 的一部分共享，如下所示。
// 显示广告而不放置/位置 mRewardedAd.showAd(this);// 显示带有放置/位置的广告 mRewardedAd.showAd(this, placementName);
检查 Ad is Ready
为了避免展示失败，并确保广告可以正确展示，建议在调用 showAd API 之前使用以下 API。
isAdReady – 如果广告已成功加载且广告单元未设置上限，则返回 true，否则返回 false。
isPlacementCapped – 有效放置/位置被限制时返回 true。如果放置/位置无效或未设置上限，此 API 将返回 false。
// 检查广告是否已准备就绪并且放置/位置未设置上限 if(mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) { mRewardedAd.showAd(this, placementName);}
当广告成功展示给玩家时，您可以加载另一个广告，重复加载奖励广告步骤。一时间加载单个广告时，无需创建新的广告实体。
奖励用户
LevelPlay SDK 将在用户每次成功完成视频时触发 onAdRewarded。
onAdRewarded 和 onAdClosed 是异步的。确保设置监听器以提供奖励，即使 onAdRewarded 在 onAdClosed 之后被触发也是如此。
@Overridepublic void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) { } // 实现向用户授予奖励的逻辑 字符串 name = reward.getName(); int amount = reward.getAmount();}
多个广告单元奖励 API
组件 | 旧版 | 广告单元（新） |
|---|---|---|
| 类 | IronSource | LevelPlayRewardedAd |
| API | loadRewardedVideo | loadAd |
| showRewardedVideo | showAd | |
| isRewardedVideoPlacementCapped | isPlacementCapped | |
| isRewardedVideoAvailable | isAdReady | |
| placement.getRewardName | reward.name | |
| placement.getRewardAmount | reward.amount |
奖励广告的完整实现示例
public 类 RewardedAdActivity extends 活动实现 LevelPlayRewardedAdListener { 私有变量 LevelPlayRewardedAd mRewardedAd; void createRewardedAd() { mRewardedAd = new LevelPlayRewardedAd("adUnitId"); mRewardedAd.setListener(this); } void loadRewardedAd() { // 加载或重新加载广告 mRewardedAd.loadAd(); } void showRewardedAd() { if (mRewardedAd.isAdReady()) { mRewardedAd.showAd(this); } } void showRewardedAd(@NonNull 字符串 placementName) { // 检查广告是否已准备就绪并且放置/位置未设置上限 if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) { mRewardedAd.showAd(this, placementName); } } // LevelPlayRewardedAdListener 方法 @Override public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdLoadFailed(@NonNull LevelPlayAdError 报错) { @Override public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdClosed(@NonNull LevelPlayAdInfo adInfo) { @Override public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) { @Override public void onAdDisplayFailed(@NonNull LevelPlayAdError 报错, @NonNull LevelPlayAdInfo adInfo) { @Override public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) { @Override public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {}