Rewarded Video Integration for Android

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.setRewardedVideoListener(new RewardedVideoListener() {
    /**
     * Invoked when the RewardedVideo ad view has opened.
     * Your Activity will lose focus. Please avoid performing heavy
     * tasks till the video ad will be closed.
     */
    @Override
    public void onRewardedVideoAdOpened() {
    }
    /*Invoked when the RewardedVideo ad view is about to be closed.
    Your activity will now regain its focus.*/
    @Override
    public void onRewardedVideoAdClosed() {
    }
    /**
     * Invoked when there is a change in the ad availability status.
     *
     * @param - available - value will change to true when rewarded videos are *available.
     *          You can then show the video by calling showRewardedVideo().
     *          Value will change to false when no videos are available.
     */
    @Override
    public void onRewardedVideoAvailabilityChanged(boolean available) {
        //Change the in-app 'Traffic Driver' state according to availability.
    }
    /**
    /**
     * Invoked when the user completed the video and should be rewarded.
     * If using server-to-server callbacks you may ignore this events and wait *for the callback from the ironSource server.
     *
     * @param - placement - the Placement the user completed a video from.
     */
    @Override
    public void onRewardedVideoAdRewarded(Placement placement) {
        /** here you can reward the user according to the given amount.
         String rewardName = placement.getRewardName();
         int rewardAmount = placement.getRewardAmount();
         */
    }
    /* Invoked when RewardedVideo call to show a rewarded video has failed
     * IronSourceError contains the reason for the failure.
     */
    @Override
    public void onRewardedVideoAdShowFailed(IronSourceError error) {
    }
    /*Invoked when the end user clicked on the RewardedVideo ad.
     *Note - This callback is not supported by all ad networks and might not be supported for all ad types
    */
    @Override
   public void onRewardedVideoAdClicked(Placement placement){
   }
    * Note: the events AdStarted and AdEnded below are not available for all supported rewarded video 
       ad networks. Check which events are available per ad network you choose 
       to include in your build.
       We recommend only using events which register to ALL ad networks you 
       include in your build.
    * Invoked when the video ad starts playing.
    */
     @Override
     public void onRewardedVideoAdStarted(){
     }
    /* Invoked when the video ad finishes plating. */
    @Override
    public void onRewardedVideoAdEnded(){
    }
});
Note:
  • 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 onVideoAvailabilityChanged callback.

public void onVideoAvailabilityChanged(boolean available)

Alternatively, ask for ad availability directly by calling:

boolean available = IronSource.isRewardedVideoAvailable();

Once an Ad Network has an available video you are ready to show this video ad to your users.This is the ideal moment to insert a trigger to encourage your users to watch the video ad.

Note:  ironSource SDK is automatically caching Rewarded Videos for you, to make sure you have ad availability, through the entire session.

Ad Placements

With the ironSource 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 ironSource 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 ironSource‘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 adynamicUserId 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 onRewardedVideoAdRewarded 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 onRewardedVideoAdRewarded and onRewardedVideoAdClosed events are asynchronous. Make sure to set up your listener to grant rewards even in cases where onRewardedVideoAdRewarded is fired after the onRewardedVideoAdClosed event.
 

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

public void onRewardedVideoAdRewarded(Placement placement)
{
    //TODO - here you can reward the user according to the given amount
    String rewardName = placement.getRewardName();
    int rewardAmount = placement.getRewardAmount();
}
Note:
  1. The default setting in your ironSource 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.
  2. If you turn on server-to-server callbacks, remember not to reward the user more than once for the same completion. We will be firing both the client-side callback and the server-to-server callback, so you will get two notifications for each completion. To utilize server-to-server callbacks, see here.
First Time Integration Tip

If this is a new integration for your application, your app will by default be in ‘Test Mode‘ on your ironSource dashboard. While your app is in Test Mode, the ironSource SDK will print more logs to the console in order to provide greater visibility into the SDK processes. To test your ad inventory, set up your Test Devices. Until you turn on live ad inventory, you will receive test campaigns that don’t generate revenue. Make sure to select Go Live! on the Ad Units page when your app is ready for live ad inventory.

ironsource-go-live-with-rewarded-video

Done!
You are now all set to deliver Rewarded Video ads in your app!


What’s Next?
Follow our integration guides to integrate additional Rewarded Video Ad networks on our Mediation platform or configure additional Ad Units:
You can read this article in: