This guide explains how to integrate the LevelPlay APIs available to use starting from SDK 8.6.0 (aka LevelPlay APIs), using an ad unit ID as a waterfall identifier, to load and display rewarded ads.
Prerequisites
APIs introduced in this article should be used instead of the integration methods currently in use (ironSource init, ironSource load rewarded, rewarded listeners). You can find the API replacements below.
The advanced settings and regulations settings have not been changed, and they are supported before or after initializing the LevelPlay SDK.
Locate the ad unit ID in the LevelPlay platform
To load and display rewarded ads, you need to use the ad unit ID available in LevelPlay mediation platform:
In your LevelPlay account, navigate to Setup → Ad Units
Copy the rewarded ad unit ID and integrate it into your code
It is possible to test the integration inside the editor. To learn how to preview mock ads in the Unity Editor, see the Preview mock ads guide.
Initializing the ironSource SDK
To initialize the ironSource SDK, follow these steps:
- Implement callbacks for initialization success and failure.
- Define the list of ad formats to initialize in the session. This should include all the ad formats that you would like to use non multiple ad unit APIs.
- Call the LevelPlay init API using the appKey, ad formats, and user ID if relevant.
LevelPlayInitRequest initRequest = new LevelPlayInitRequest.Builder(appKey) .build(); LevelPlayInitListener initListener = new LevelPlayInitListener() { @Override public void onInitFailed(@NonNull LevelPlayInitError error) {} @Override public void onInitSuccess(LevelPlayConfiguration configuration) {} }; LevelPlay.init(context, initRequest, initListener);
val initRequest = LevelPlayInitRequest.Builder("AppKey") .withUserId("UserId") .build() LevelPlay.init(context, initRequest, object: LevelPlayInitListener { override fun onInitSuccess(configuration: LevelPlayConfiguration) {} override fun onInitFailed(error: LevelPlayInitError) {} }
LevelPlay Init Listeners
onInitSuccess: triggered when the initialization is completed successfully. After you receive this indication, you can create and load the ad.
onInitFailed: the configuration was not retrieved successfully and ads cannot be loaded. It is recommended to try and initialize the ironSource SDK later (when internet connection is available, or when the failure reason is resolved).
| Init | Legacy | Ad Unit (new) |
|---|---|---|
| API | IronSource.init | LevelPlay.init |
| Callbacks | onInitializationComplete | onInitSuccess |
| – | onInitFailed |
Create Rewarded Ad Object
The creation of the rewarded ad object must be performed after receiving the onInitSuccess callback.
The object is a reusable instance that can handle multiple loads and shows throughout the session. Once created, it should be used to load and show ads for the same ad unit.
For more advanced implementations, you may create multiple rewarded ad objects if necessary.
// Create rewarded Ad mRewardedAd = new LevelPlayRewardedAd("adUnitId");
// Create rewarded Ad mRewardedAd = LevelPlayRewardedAd("adUnitId")
Register to Rewarded Events
Set the rewarded listener for the rewarded ad unit created, to get informed of ad delivery.
- It is recommended to set the listener before loading the rewarded ad.
- Each rewarded ad should have its own listener implementation.
- Callbacks run on the main thread.
// Create rewarded Ad mRewardedAd = new LevelPlayRewardedAd("adUnitId"); // Set listener mRewardedAd.setListener(this); // LevelPlayRewardedAdListener methods @Override public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdLoadFailed(@NonNull LevelPlayAdError error) {} @Override public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdDisplayFailed(@NonNull LevelPlayAdError error, @NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {}
// Create rewarded Ad mRewardedAd = LevelPlayRewardedAd("adUnitId") // Set listener mRewardedAd.setListener(this) // LevelPlayRewardedAdListener methods override fun onAdLoaded(adInfo: LevelPlayAdInfo) {} override fun onAdLoadFailed(error: LevelPlayAdError) {} override fun onAdInfoChanged(adInfo: LevelPlayAdInfo) {} override fun onAdDisplayed(adInfo: LevelPlayAdInfo) {} override fun onAdDisplayFailed(error: LevelPlayAdError, adInfo: LevelPlayAdInfo) {} override fun onAdClicked(adInfo: LevelPlayAdInfo) {} override fun onAdClosed(adInfo: LevelPlayAdInfo) {} override fun onAdRewarded(reward: LevelPlayReward, adInfo: LevelPlayAdInfo) {}
LevelPlay Rewarded Ad Callbacks
onAdLoaded: Provided when the ad is successfully loaded.
onAdLoadFailed: Provided when the ad fails to load. Ad Unit information is included.
onAdDisplayed: Provided when the ad is displayed. This is equivalent to an impression.
onAdDisplayFailed: Provided when the ad fails to be displayed.
onAdRewarded: Provided when the ad is rewarded. Ad Unit info and the reward info are included.
onAdClicked (optional): Provided when the user clicks on the ad.
onAdClosed: Provided when the ad is closed.
onAdInfoChanged (optional): Provided when the ad info is updated. Available when another ad has loaded, and includes a higher CPM/Rate.
| Component | Legacy | Ad Unit (new) |
|---|---|---|
| Listener | IronSourceRewardedVideoEvents | LevelPlayRewardedAd |
| Callbacks | onAdReady | onAdLoaded |
| onAdLoadFailed | onAdLoadFailed | |
| onAdOpened | onAdDisplayed | |
| onAdClosed | onAdClosed | |
| onAdShowFailed | onAdDisplayFailed | |
| onAdRewarded | onAdRewarded | |
| onAdClicked | onAdClicked | |
| onAdShowSucceeded | n/a (deprecated) | |
| n/a | onAdInfoChanged |
Load Rewarded Ad
Once you receive the onInitSuccess callback, you are ready to load a rewarded ad. This should be done using the method:
// Load or reload the ad mRewardedAd.loadAd();
// Load or reload the ad mRewardedAd.loadAd()
Show Rewarded Ad
You can show a rewarded ad after you receive onAdLoaded callback, using the showAd APIs. If you are using placements, share their name as part of the API, as shown below.
// Show ad without placement mRewardedAd.showAd(this); // Show ad with placement mRewardedAd.showAd(this, placementName);
// Show ad without placement mRewardedAd.showAd(this) // Show ad with placement mRewardedAd.showAd(this, placementName)
Check Ad is Ready
To avoid show failures, and to make sure the ad could be displayed correctly, we recommend using the following API, before calling the showAd API.
isAdReady – returns true if ad was loaded successfully and ad unit is not capped, or false otherwise.
isPlacementCapped – returns true when a valid placement is capped. If the placement is not valid, or not capped, this API will return false.
// Check that ad is ready and that the placement is not capped if(mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) { mRewardedAd.showAd(this, placementName); }
// Check that ad is ready and that the placement is not capped if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) { mRewardedAd.showAd(this, placementName) }
When the ad displays successfully to the player, you can load another ad, repeating the Load Rewarded Ad step. There is no need to create a new ad entity, when loading a single ad at a time.
Reward the User
The LevelPlay SDK will fire the onAdRewarded each time the user successfully completes a video.
The onAdRewarded and onAdClosed are asynchronous. Make sure to set up your listener to grant rewards even in cases where onAdRewarded is fired after the onAdClosed.
@override public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) { // Implement logic to grant the reward to the user String name = reward.getName(); int amount = reward.getAmount(); }
override fun onAdRewarded(reward: LevelPlayReward, adInfo: LevelPlayAdInfo) { // Implement logic to grant the reward to the user val name: String = reward.name val amount: Int = reward.amount }
Multiple Ad Unit Rewarded APIs
| Component | Legacy | Ad Unit (new) |
|---|---|---|
| Class | IronSource | LevelPlayRewardedAd |
| API | loadRewardedVideo | loadAd |
| showRewardedVideo | showAd | |
| isRewardedVideoPlacementCapped | isPlacementCapped | |
| isRewardedVideoAvailable | isAdReady | |
| placement.getRewardName | reward.name | |
| placement.getRewardAmount | reward.amount |
Full Implementation Example of Rewarded Ad
public class RewardedAdActivity extends Activity implements LevelPlayRewardedAdListener { private LevelPlayRewardedAd mRewardedAd; void createRewardedAd() { mRewardedAd = new LevelPlayRewardedAd("adUnitId"); mRewardedAd.setListener(this); } void loadRewardedAd() { // Load or reload the ad mRewardedAd.loadAd(); } void showRewardedAd() { if(mRewardedAd.isAdReady()) { mRewardedAd.showAd(this); } } void showRewardedAd(@NonNull String placementName) { // Check that ad is ready and that the placement is not capped if(mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) { mRewardedAd.showAd(this, placementName); } } // LevelPlayRewardedAdListener methods @Override public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdLoadFailed(@NonNull LevelPlayAdError error) {} @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 error, @NonNull LevelPlayAdInfo adInfo) {} @Override public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {} public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {} }
class RewardedAdActivity : Activity(), LevelPlayRewardedAdListener { private lateinit var mRewardedAd: LevelPlayRewardedAd fun createRewardedAd() { mRewardedAd = LevelPlayRewardedAd("adUnitId") mRewardedAd.setListener(this) } fun loadRewardedAd() { mRewardedAd.loadAd() } fun showRewardedAd() { if (mRewardedAd.isAdReady()) { mRewardedAd.showAd(this) } } fun showRewardedAd(placementName: String) { // Check that ad is ready and that the placement is not capped if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) { mRewardedAd.showAd(this, placementName) } } // LevelPlayRewardedAdListener methods override fun onAdLoaded(adInfo: LevelPlayAdInfo) {} override fun onAdLoadFailed(error: LevelPlayAdError) {} override fun onAdInfoChanged(adInfo: LevelPlayAdInfo) {} override fun onAdDisplayed(adInfo: LevelPlayAdInfo) {} override fun onAdDisplayFailed(error: LevelPlayAdError, adInfo: LevelPlayAdInfo) {} override fun onAdClicked(adInfo: LevelPlayAdInfo) {} override fun onAdClosed(adInfo: LevelPlayAdInfo) {} override fun onAdRewarded(reward: LevelPlayReward, adInfo: LevelPlayAdInfo) {} }