Rewarded Integration for Android Legacy pre v8.5.0

⚡ Before you start

Make sure you have correctly integrated the ironSource SDK into your application. Integration is outlined here.

Step 1. Implement the Rewarded Video Listener

The ironSource SDK fires several events to inform you of ad availability and completions so you’ll know when to reward your users.

The SDK will notify your listener of all possible events listed below:

IronSource.setLevelPlayRewardedVideoListener(new LevelPlayRewardedVideoListener() {
   // Indicates that there's an available ad. 
   // The adInfo object includes information about the ad that was loaded successfully
   // Use this callback instead of onRewardedVideoAvailabilityChanged(true)
   @Override
   public void onAdAvailable(AdInfo adInfo) {}
   // Indicates that no ads are available to be displayed 
   // Use this callback instead of onRewardedVideoAvailabilityChanged(false) 
   @Override
   public void onAdUnavailable() {}
   // The Rewarded Video ad view has opened. Your activity will loose focus
   @Override
   public void onAdOpened(AdInfo adInfo) {}
   // The Rewarded Video ad view is about to be closed. Your activity will regain its focus
   @Override
   public void onAdClosed(AdInfo adInfo) {}
   // The user completed to watch the video, and should be rewarded. 
   // The placement parameter will include the reward data.
   // When using server-to-server callbacks, you may ignore this event and wait for the ironSource server callback
   @Override
   public void onAdRewarded(Placement placement, AdInfo adInfo) {}
   // The rewarded video ad was failed to show
   @Override
   public void onAdShowFailed(IronSourceError error, AdInfo adInfo) {}
   // Invoked when the video ad was clicked. 
   // This callback is not supported by all networks, and we recommend using it 
   // only if it's supported by all networks you included in your build
   @Override
   public void onAdClicked(Placement placement, AdInfo adInfo) {}
});

You can view the full listeners implementation here.

SDK Initialization

Please make sure to set the listeners before SDK initialization. This will ensure the SDK sends all relevant information.

Callbacks

Please do not assume the callbacks are always running on the main thread. Any UI interaction or updates resulting from ironSource’s callbacks need to be passed to the main thread before executing.

Error Codes

ironSource provides an error code mechanism to help you understand errors you may run into during integration or live production. See the complete guide here.

Network Connectivity Status

You can determine and monitor the internet connection on the user’s device through the ironSource Network Change Status function. This enables the SDK to change its availability according to network modifications, i.e. in the case of no network connection, the availability will turn to FALSE.
The default of this function is false; if you’d like to listen to it for changes in connectivity, activate it in the SDK initialization with the following string:

IronSource.shouldTrackNetworkState(this, true);

Step 2. Show a Video Ad to Your Users

Ad Availability

By correctly implementing the RewardedVideoListener and its functions, you can receive the availability status through the onAdAvailabile callback.

public void onAdAvailable(AdInfo adInfo)

Alternatively, ask for ad availability directly by calling:

boolean available = IronSource.isRewardedVideoAvailable();

Once an ad network has an available video, you will be ready to show the video to your users. Before you display the ad, make sure to pause any game action, including audio, to ensure the best experience for your users.

Note: ironSource SDK automatically caches Rewarded Videos for you, to ensure you have ad availability throughout the entire session

Ad Placements

With the LevelPlay Ad Placements tool, you can customize and optimize the Rewarded Video experience. This tool enables you to present videos to your users from different placements depending on the reward. You can use the below function to define the exact Placement you’d like to show an ad from. Navigate to the Ad Placement document for more details.

Note: Make sure you use the placement name as written in the platform when using it as a parameter.

Serve Video Ad

By calling the showRewardedVideo() method of the ironSource class, you can show a video ad to your users and define the exact Placement you want to show an ad. The Reward settings of this Placement will be pulled from the ironSource server:

IronSource.showRewardedVideo(placementName);

Note: In the case the placementName parameter is null, the SDK will retrieve the default placement settings configured on the LevelPlay platform.

To get details about the specific Reward associated with each Ad Placement, you can call the following:

Placement placement = IronSource.getRewardedVideoPlacementInfo("placementName");
// Null can be returned instead of a placement if the placementName is not valid.
if (placement != null) {
    String rewardName = placement.getRewardName();
    int rewardAmount = placement.getRewardAmount();
}

Capping & Pacing

In addition to LevelPlay‘s Ad Placements, you can now configure capping and pacing settings for selected placements. Capping and pacing improves the user experience in your app by limiting the amount of ads served within a defined timeframe. Read more about capping and pacing here.

Note: To ensure you don’t show the traffic driver (Rewarded Video button) to prompt the user to watch an ad when the placement is capped, you must call the below method to verify if a specific placement has reached its ad limit.

IronSource.isRewardedVideoPlacementCapped("Your Placements");

When requesting availability, you might receive a TRUE response but in the case your placement has reached its capping limit, the ad will not be served to the user.

Dynamic UserID

The Dynamic UserID is a parameter to verify AdRewarded transactions and can be changed throughout the session. To receive this parameter through the server to server callbacks, it must be set before calling showRewardedVideo. You will receive a dynamicUserId parameter in the callback URL with the reward details.

IronSource.setDynamicUserId("UserID");

Step 3. Reward the User

Make sure you’ve set the userID before you initialize the ironSource SDK in order to successfully reward your users.

The ironSource SDK will fire the onAdRewarded event each time the user successfully completes a video. The RewardedVideoListener will be in place to receive this event so you can reward the user successfully.

Note: The onAdRewarded and onAdClosed events are asynchronous. Make sure to set up your listener to grant rewards even in cases where onAdRewarded is fired after the onAdClosed event.

The Placement object contains both the Reward Name & Reward Amount of the Placement as defined in your LevelPlay Admin:

 public void onAdRewarded(Placement placement, AdInfo adInfo) {
    //TODO - here you can reward the user according to the given amount
    String rewardName = placement.getRewardName();
    int rewardAmount = placement.getRewardAmount();
}

Note: The default setting in your LevelPlay account is to notify you of user completions/rewards via the AdRewarded:amount callback within the client of your app. Additionally, if you would also like to receive notifications to your back-end server, you can turn on server-to-server callbacks.

Server-to-server callbacks

If you turn on server-to-server callbacks, make sure you’ve set the userID before you initialize the ironSource SDK so your users can get rewarded, and make sure to reward your user only once for the same completion.

ironSource will be firing both the client-side callback and the server-to-server callback. So, you will get two notifications in total for each completion.

To utilize server-to-server callbacks, see here.

Alternative integration: Manual Load Rewarded Ads

In addition to loading ironSource SDK rewarded video ads automatically, you can also set rewarded video ads to load manually. To do this, you must set the entire session loading mode prior to SDK initialization. This is supported from ironSource SDK 7.2.0+ (Beta 7.1.13 Android).

Step 1: Set up rewarded video manual loading

Set the operation mode of rewarded video ads before you initialize the ironSource SDK. By setting the manual mode, you will also create a new listener: RewardedVideoManualListener.

This listener will trigger callbacks to inform you of ad availability and completions so you’ll know when to display ads and to reward your users.

The SDK will notify your listener of all possible events listed below:

IronSource.setLevelPlayRewardedVideoManualListener(new LevelPlayRewardedVideoManualListener() {
   // Indicates that the Rewarded video ad was loaded successfully. 
   // AdInfo parameter includes information about the loaded ad
   @Override
   public void onAdReady(AdInfo adInfo) {}
   // Invoked when the rewarded video failed to load 
   @Override
   public void onAdLoadFailed(IronSourceError error){}
   // The Rewarded Video ad view has opened. Your activity will loose focus
   @Override
   public void onAdOpened(AdInfo adInfo){}
   // The Rewarded Video ad view is about to be closed. Your activity will regain its focus
   @Override
   public void onAdClosed(AdInfo adInfo){}
   // The user completed to watch the video, and should be rewarded. 
   // The placement parameter will include the reward data.
   // When using server-to-server callbacks, you may ignore this event and wait for the ironSource server callback
   @Override
   public void onAdRewarded(Placement placement, AdInfo adInfo){}
   // The rewarded video ad was failed to show
   @Override
   public void onAdShowFailed(IronSourceError error, AdInfo adInfo){}
   // Invoked when the video ad was clicked. 
   // This callback is not supported by all networks, and we recommend using it 
   // only if it's supported by all networks you included in your build
   @Override
   public void onAdClicked(Placement placement, AdInfo adInfo){}
   
});

You can view the full listeners implementation here.

Step 2: Manually load rewarded video ads

Request a rewarded video ad d before you plan on showing it to your users as the loading process can take time. Use the following API to load your ad:

IronSource.loadRewardedVideo();

If you’d like to serve multiple rewarded video ads in your app, you should repeat this step after you’ve shown and closed the previous rewarded video ad. Once the onRewardedAdClosed callback is triggered, you’ll be able to load a new rewarded video ad.