Rewarded Video Integration for Unity Plugin

Before you start

Make sure you have correctly integrated the ironSource Unity Plugin as well as any additional Ad Network Adapters into your application. Integration is outlined here.

Step 1. Implement the Rewarded Video Events

The ironSource Unity Plugin fires several events to inform you of ad availability.

Add the following code to register to the events:

//Add AdInfo Rewarded Video Events
IronSourceRewardedVideoEvents.onAdOpenedEvent += RewardedVideoOnAdOpenedEvent;
IronSourceRewardedVideoEvents.onAdClosedEvent += RewardedVideoOnAdClosedEvent;
IronSourceRewardedVideoEvents.onAdAvailableEvent += RewardedVideoOnAdAvailable;
IronSourceRewardedVideoEvents.onAdUnavailableEvent += RewardedVideoOnAdUnavailable;
IronSourceRewardedVideoEvents.onAdShowFailedEvent += RewardedVideoOnAdShowFailedEvent;
IronSourceRewardedVideoEvents.onAdRewardedEvent += RewardedVideoOnAdRewardedEvent;
IronSourceRewardedVideoEvents.onAdClickedEvent += RewardedVideoOnAdClickedEvent;

The Plugin will notify the Listener of all possible events listed below:


/************* RewardedVideo AdInfo Delegates *************/
// Indicates that there’s an available ad.
// The adInfo object includes information about the ad that was loaded successfully
// This replaces the RewardedVideoAvailabilityChangedEvent(true) event
void RewardedVideoOnAdAvailable(IronSourceAdInfo adInfo) {
}

// Indicates that no ads are available to be displayed
// This replaces the RewardedVideoAvailabilityChangedEvent(false) event
void RewardedVideoOnAdUnavailable() {
}

// The Rewarded Video ad view has opened. Your activity will loose focus.
void RewardedVideoOnAdOpenedEvent(IronSourceAdInfo adInfo){
}

// The Rewarded Video ad view is about to be closed. Your activity will regain its focus.
void RewardedVideoOnAdClosedEvent(IronSourceAdInfo 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.
void RewardedVideoOnAdRewardedEvent(IronSourcePlacement placement, IronSourceAdInfo adInfo){
}

// The rewarded video ad was failed to show.
void RewardedVideoOnAdShowFailedEvent(IronSourceError error, IronSourceAdInfo 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.
void RewardedVideoOnAdClickedEvent(IronSourcePlacement placement, IronSourceAdInfo adInfo){
}

Error Codes

ironSource provides an error code mechanism to help you understand any error you may encounter during integration or in 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.Agent.shouldTrackNetworkState (true);

Step 2. Show a Video Ad to Your Users

Ad Availability

You will receive the availability status of the Rewarded Video ad through the onAdAvailableEvent events.

In addition, you have the possibility to ask for ad availability directly by calling:

bool available = IronSource.Agent.isRewardedVideoAvailable();

Serve Video Ad

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. Use the showRewardedVideo() method on your IronSource.Agent instance, to show a video ad to your users:

IronSource.Agent.showRewardedVideo();

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. The Reward settings of this Placement will be pulled from the ironSource server:

IronSource.Agent.showRewardedVideo("YOUR_PLACEMENT_NAME");

To get details about the specific reward associated with each ad placement, you can call the following:

Placement placement = IronSource.Agent.getPlacementInfo(placementName);
//Placement can return null if the placementName is not valid.
if(placement != null)
{
    String rewardName = placement.getRewardName();
    int rewardAmount = placement.getRewardAmount();
}
Note: Make sure you use the placement name as written in the platform when using it as a parameter.

Capping & Pacing

ironSource SDK gives you the ability to set your app’s capping and pacing by ad unit, ad placement, or both. When you use both, the more restrictive settings will be applied.

By ad unit: This enables you to control the number of rewarded video ads delivered over a user’s entire session. If an ad is capped, then you will not received available ad / load success indication when trying to load the ad. 

By placement: This helps you ensure you’re serving the optimal number of ads at each location in your app. If you choose to use the capping and pacing tool by placement for Rewarded Video, we recommend calling the below method to verify if a certain placement has reached its ad limit. This is to ensure you don’t portray the Rewarded Video button when the placement has been capped or paced and thus will not serve the Video ad.

bool isRewardedVideoPlacementCapped(string placementName);

Read more about capping and pacing here.

Dynamic User ID

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. 

boolean setDynamicUserId(String dynamicUserID);

Step 3. Reward the User

The ironSource SDK will fire the onAdRewardedEvent each time the user successfully completes a video.

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

void RewardedVideoOnAdRewardedEvent(IronSourcePlacement placement, IronSourceAdInfo adInfo){
    //TODO - here you can reward the user according to the reward name and amount
    ssp.getPlacementName();
    ssp.getRewardName();
    ssp.getRewardAmount();
}
Note: The default setting in your LevelPlay account is to notify you of user completions/rewards via the IronSourceAdRewardedEvent event 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 LevelPlay 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.

Done!
You are now all set to deliver Rewarded Video in your application.

First Time Integration Tip

If this is a new integration for your application, your app will by default be in ‘Test Mode‘ on your LevelPlay 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


What’s Next?
Follow our integration guides to implement additional Rewarded Video Ad networks on our Video Mediation platform or configure additional Ad Units: