Rewarded Video Integration for iOS

The ironSource Rewarded Video ad unit offers an engaging ad experience that rewards your users with valuable virtual content in exchange for a completed view. This user-initiated ad unit is great for gaming apps; and enhances every app experience!

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.

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

OBJECTIVE-C

#pragma mark - ISRewardedVideoDelegate
//Called after a rewarded video has changed its availability.
//@param available The new rewarded video availability. YES if available //and ready to be shown, NO otherwise.
- (void)rewardedVideoHasChangedAvailability:(BOOL)available {
}
//Called after a rewarded video has been viewed completely and the user is //eligible for reward.@param placementInfo An object that contains the //placement's reward name and amount.
- (void)didReceiveRewardForPlacement:(ISPlacementInfo *)placementInfo {
}
//Called after a rewarded video has attempted to show but failed.
//@param error The reason for the error
- (void)rewardedVideoDidFailToShowWithError:(NSError *)error {
}
//Called after a rewarded video has been opened.
- (void)rewardedVideoDidOpen {
}
//Called after a rewarded video has been dismissed.
- (void)rewardedVideoDidClose {
}
//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.
 //Called after a rewarded video has started playing.
- (void)rewardedVideoDidStart {
}
//Called after a rewarded video has finished playing.
- (void)rewardedVideoDidEnd {
}

SWIFT

//MARK: ISRewardedVideoDelegate Functions
    /**
     Called after a rewarded video has changed its availability.
     
     @param available The new rewarded video availability. YES if available and ready to be shown, NO otherwise.
     */
    public func rewardedVideoHasChangedAvailability(_ available: Bool) {
   }
    
    /**
     Called after a rewarded video has finished playing.
     */
    public func rewardedVideoDidEnd() {
    }
    
    /**
     Called after a rewarded video has started playing.
     */
    public func rewardedVideoDidStart() {
   }
    
    /**
     Called after a rewarded video has been dismissed.
     */
    public func rewardedVideoDidClose() {
   }
    
    /**
     Called after a rewarded video has been opened.
     */
    public func rewardedVideoDidOpen() {
   }
    
    /**
     Called after a rewarded video has attempted to show but failed.
     
     @param error The reason for the error
     */
    public func rewardedVideoDidFailToShowWithError(_ error: Error!) {
   }
    
    /**
     Called after a rewarded video has been viewed completely and the user is eligible for reward.
     
     @param placementInfo An object that contains the placement's reward name and amount.
     */
    public func didReceiveReward(forPlacement placementInfo: ISPlacementInfo!) {
   }
 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.
  •  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.

Step 2. Show a Video Ad to Your Users

Ad Availability

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

OBJECTIVE-C

/**
*Called after a rewarded video has changed its availability.
*@param available The new rewarded video availability. YES if available *and *ready to be shown, NO otherwise.
*/
(void)rewardedVideoHasChangedAvailability:(BOOL)available {
}

SWIFT

 /**
     Called after a rewarded video has changed its availability.
     @param available The new rewarded video availability. YES if available and ready to be shown, NO otherwise.
     */
    public func rewardedVideoHasChangedAvailability(_ available: Bool) {
   }

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

OBJECTIVE-C

[IronSource hasRewardedVideo];

SWIFT

IronSource.hasRewardedVideo()

Serve Video Ad

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.  Call the following method to show a video ad to your users:

OBJECTIVE-C

[IronSource showRewardedVideoWithViewController:(UIViewController *)viewController placement:(nullable NSString *)placementName];

SWIFT

IronSource.showRewardedVideo(with: <UIViewController>, placement: <String?>)

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

Ad Placements

With ironSource Ad Placements, 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.

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

OBJECTIVE-C

[IronSource rewardedVideoPlacementInfo:(NSString *)placementName];
if(pInfo != NULL)
{
	 NSString * rewardName = [pInfo rewardName];
	 NSNumber * rewardAmount = [pInfo rewardAmount];
}

SWIFT

 let placementInfo = IronSource.rewardedVideoPlacementInfo(<placementName: String>)
        if  placementInfo != nil {
            let rewardName = placementInfo.placementName
            let rewardAmount = placementInfo.rewardAmount
        }

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

OBJECTIVE-C

[IronSource isRewardedVideoCappedForPlacement:@"Placement"];

SWIFT

IronSource.isRewardedVideoCapped(forPlacement: <String>)

Dynamic UserID

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.

OBJECTIVE-C

[IronSource setDynamicUserId:@"DynamicUserId"];

SWIFT

IronSource.setDynamicUserId(<dynamicUserId: String>)

Step 3. Reward the User

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

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

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

OBJECTIVE-C

//Called after a rewarded video has been viewed completely and the user is //eligible for reward.
//@param placementInfo is an object that contains the placement's reward //name and amount.
- (void)didReceiveRewardForPlacement:(ISPlacementInfo *)placementInfo {
    	 NSNumber *rewardAmount = [placementInfo rewardAmount];
	 NSString *rewardName = [placementInfo rewardName];
}

SWIFT

/**
     Called after a rewarded video has been viewed completely and the user is eligible for reward. @param placementInfo An object that contains the placement's reward name and amount.
*/
  public func didReceiveReward(forPlacement placementInfo: ISPlacementInfo!) {
    }
Note:

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

 

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.
Supersonic Switch App to Live Mode Rewarded Video Ad Unitironsource-go-live-with-rewarded-video

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