Rewarded Video Integration for iOS SDK

Get up and running with the Rewarded Video Ad Unit in 5 easy steps:

Implement the Rewarded Video Delegate
Initialize the Rewarded Video Unit
Show a Video Ad to Your Users
Reward the User
Verify Your Integration

Before You Start
Make sure you have correctly integrated the ironSource SDK as well as any additional Ad Network Adapters into your application. Integration is outlined here.

Step 1. Implement the Rewarded Video Delegate

The ironSource SDK fires several events to inform you of ad availability and completions so you’ll know when to reward your users.
To receive these events, register to the delegate setRVAdapterDelegate:rvDelegate :

OBJECTIVE-C

[[Supersonic sharedInstance] setRVDelegate:YOUR_REWARDED_VIDEO_DELEGATE];

SWIFT

let YOUR_REWARDED_VIDEO_DELEGATE:RVDelegate  = RVDelegate()

Note:

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

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

OBJECTIVE-C

@interface RVDelegate : NSObject <SupersonicRVDelegate>
@end
@implementation RVDelegate
/**
* Invoked when initialization of RewardedVideo ad unit has finished successfully
*/
- (void)supersonicRVInitSuccess{}
/**
* Invoked when RewardedVideo initialization process has failed. NSError
* contains the reason for the failure.
*/
- (void)supersonicRVInitFailedWithError:(NSError *)error{}
/**
* Invoked when there is a change in the ad availability status.
* @param - hasAvailableAds - value will change to YES when rewarded videos are available. * You can then show the video by calling showRV(). Value will change to NO when no videos are available.
*/
- (void)supersonicRVAdAvailabilityChanged:(BOOL)hasAvailableAds{}
/**
* Invoked when the user completed the video and should be rewarded.
* If using server-to-server callbacks you may ignore these events and wait
* for the callback from the Supersonic server.
* @param - placementInfo - SupersonicPlacementInfo - an object contains the placement's reward name and amount
*/
- (void)supersonicRVAdRewarded:(SupersonicPlacementInfo*)placementInfo{}
/**
* Invoked when an Ad failed to display.
* @param - error - NSError which contains the reason for the
* failure. The error contains error.code and error.message.
*/
- (void)supersonicRVAdFailedWithError:(NSError *)error{}
/**
* Invoked when the RewardedVideo ad view has opened.
*/
- (void)supersonicRVAdOpened{}
/**
* Invoked when the user is about to return to the application after closing the
* RewardedVideo ad.
*/
- (void)supersonicRVAdClosed{}
/**
* Note: the events 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.
*/
/**
* Available for: AdColony, Vungle, AppLovin, UnityAds
* Invoked when the video ad starts playing.
*/
- (void)supersonicRVAdStarted{}
/**
* Available for: AdColony, Vungle, AppLovin, UnityAds
* Invoked when the video ad finishes playing.
*/
- (void)supersonicRVAdEnded{}
@end

SWIFT

class RVDelegate: NSObject, SupersonicRVDelegate {
/**
* Invoked when initialization of RewardedVideo ad unit has finished successfully
*/
func supersonicRVInitSuccess(){ }
/**
* Invoked when RewardedVideo initialization process has failed. NSError
* contains the reason for the failure.
*/
func supersonicRVInitFailedWithError(error:NSError){ }
/**
* Invoked when there is a change in the ad availability status.
* @param - hasAvailableAds - value will change to YES when rewarded videos are available. * You can then show the video by calling showRV(). Value will change to NO when no videos are available.
*/
func supersonicRVAdAvailabilityChanged(hasAvailableAds:Bool){ }
/**
* Invoked when the user completed the video and should be rewarded.
* If using server-to-server callbacks you may ignore these events and wait
* for the callback from the Supersonic server.
* @param - placementInfo - SupersonicPlacementInfo - an object contains the placement's reward name and amount
*/
func supersonicRVAdRewarded(placementInfo:SupersonicPlacementInfo){ }
/**
* Invoked when an Ad failed to display.
* @param - error - NSError which contains the reason for the
* failure. The error contains error.code and error.message.
*/
func supersonicRVAdFailedWithError(error:NSError){ }
/**
* Invoked when the RewardedVideo ad view has opened.
*/
func supersonicRVAdOpened(){ }
/**
* Invoked when the user is about to return to the application after closing the
* RewardedVideo ad.
*/
func supersonicRVAdClosed(){ }
/**
* Note: the events 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.
*/
/**
* Available for: AdColony, Vungle, AppLovin, UnityAds
* Invoked when the video ad starts playing.
*/
func supersonicRVAdStarted(){ }
/**
* Available for: AdColony, Vungle, AppLovin, UnityAds
* Invoked when the video ad finishes playing.
*/
func supersonicRVAdEnded(){ }

Note: Note: 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.

Step 2. Initialize the Rewarded Video Unit

Once the Rewarded Video Unit is initialized, the ironSource SDK will automatically check all available Ad Networks for Video Ads throughout the life-cycle of the app. You should initialize Rewarded Video as early as possible to allow time for all Ad Networks to prepare Video Ad content. We recommend doing so on app launch.

Initialize the Rewarded Video Ad Unit:

OBJECTIVE-C

[[Supersonic sharedInstance] setRVDelegate:YOUR_REWARDED_VIDEO_DELEGATE];
[[Supersonic sharedInstance] initRVWithAppKey:APP_KEY withUserId:USER_ID];

SWIFT

Supersonic.sharedInstance().setRVDelegate(YOUR_REWARDED_VIDEO_DELEGATE)
Supersonic.sharedInstance().initRVWithAppKey(APP_KEY, withUserId: USER_ID)

Note: Note:

APP_KEY is the unique ID of your Application in your ironSource account. You can find the App Key on any of the Mediation or Setting pages.
USER_ID is the unique ID of your end user. We support NSString from 1 to 64 characters. Common practice is to use the Apple IDFV (Identifier for Vendor). More information on User IDs can be found here.
ironSource supports Network Change Status, which enables the SDK to change the 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; in the case you’d like to utilize it, you can activate it in the Init with the following string:
```
[Supersonic sharedInstance] setShouldTrackReachability:YES];
```

Step 3. Show a Video Ad to Your Users

By correctly implementing the Rewarded Video Delegate and its functions, you can receive the availability status through the supersonicRVAdAvailabilityChanged. You will then be notified with the delegate function below upon ad availability change:

OBJECTIVE-C

supersonicRVAdAvailabilityChanged:(BOOL)hasAvailableAds;

SWIFT

func supersonicRVAdAvailabilityChanged(hasAvailableAds:Bool)

Alternatively, you can also request ad availability directly by calling:

OBJECTIVE-C

[[Supersonic sharedInstance] isAdAvailable];

SWIFT

Supersonic.sharedInstance().isAdAvailable()

Once an Ad Network has an available video, you are ready to serve this video ad to your user. This is the ideal moment to insert a trigger to encourage your users to watch the video ad. By calling the showRV method on your Supersonic instance, you can show a Video Ad to your users:

OBJECTIVE-C

[[Supersonic sharedInstance] showRVWithViewController:viewController];

SWIFT

Supersonic.sharedInstance().showRVwithViewController:viewController()

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.

OBJECTIVE-C

[[Supersonic sharedInstance] showRVWithPlacementName:placementName]

SupersonicPlacementInfo * pInfo = [[Supersonic sharedInstance] getRVPlacementInfo:pName];
if(pInfo != NULL)
{
	 NSString * rewardName = [pInfo rewardName];
	 NSNumber * rewardAmount = [pInfo rewardAmount];
}

SWIFT

Supersonic.sharedInstance().showRVWithPlacementName(placementName)

if let pInfo:SupersonicPlacementInfo = Supersonic.sharedInstance().getRVPlacementInfo(pName)
{
    let rewardAmount:NSNumber = pInfo.rewardAmount
    let rewardName:NSString = pInfo.rewardName
}

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

OBJECTIVE-C

 [[Supersonic sharedInstance] getRVPlacementInfo:@"PLACEMENT_NAME"];

SWIFT

Supersonic.sharedInstance().getRVPlacementInfo("PLACEMENT_NAME")

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: Note: If you choose to use the capping and pacing tool 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.

[[Supersonic sharedInstance] isRewardedVideoPlacementCapped:placementName];

New! Dynamic UserID to Verify AdRewarded Transactions
The Dynamic UserID is a parameter that can be changed throughout the session and will be received in the server-to-server ad rewarded callbacks. This parameter helps verify AdRewarded transactions and must be set before calling ShowRV.

[[Supersonic sharedInstance] setDynamicUserId:@"DynamicUserID"];

Step 4. Reward the User

Each time the user successfully completes a video, the ironSource SDK will fire the supersonicAdRewarded:amount event. Upon reward, you will be notified with the delegate function below.

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

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

OBJECTIVE-C

(void)supersonicRVAdRewarded:(SupersonicPlacementInfo*)placementInfo{
	 NSNumber * rewardAmount = [placementInfo rewardAmount];
	 NSString * rewardName = [placementInfo rewardName];
}

SWIFT

func supersonicRVAdRewarded(placementInfo:SupersonicPlacementInfo){
	 let rewardAmount:NSNumber = placementInfo.rewardAmount
	 let rewardName:NSString = placementInfo.rewardName
}

Note: Note:

The default setting in your ironSource account is to notify you of user completions/rewards via the supersonicAdRewarded: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.
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.

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 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.

What’s Next?
Follow our integration guides to integrate additional Rewarded Video Ad networks or configure additional Ad Units: