Get Started

Integrating Rewarded Video – iOS

Overview

Rewarded video ads are a great way to offer users an incentive to stay engaged in your app, while earning more ad revenue. The reward generally comes in the form of in-game currency (gold, coins, power-ups) and is distributed to the user after a successful video completion.

MoPub’s Rewarded Video offering features demand from MoPub Marketplace and 3rd party SDK Mediation to help publishers maximize their revenue and manage their waterfall. MoPub Marketplace Rewarded Video is now in beta. MoPub’s mediation solution officially supports rewarded videos from popular ad networks like AdColony, Unity Ads, Vungle, Chartboost and Tapjoy. We give you the flexibility to work with these popular ad networks without any extra integration with network SDKs.

Getting Started

  • Before integrating rewarded video ads in your app, you’ll need to go through the steps in our Getting Started guide, create an account on MoPub and integrate the SDK into your project.
  • Add a rewarded video ad unit to your app in the MoPub dashboard.
  • Make sure you have added the ad network SDKs you wish to use to your app.
  • Set up your networks as custom native networks in the MoPub dashboard.
  • Review Rewarded Video Best Practices.

Basic Integration

  1. Include the custom event class and JAR for the mediated network: Three adnetwork custom event adapters are included in the AdNetworkSupport directory:
    • ChartboostRewardedVideoCustomEvent.h/m
    • VungleRewardedVideoCustomEvent.h/m
    • AdColonyRewardedVideoCustomEvent.h/m
    • UnityAdsRewardedVideoCustomEvent.h/m
    • TapjoyRewardedVideoCustomEvent.h/m

    For each mediated network that you would like to support, add the corresponding network SDK into your application.

  2. Import the required classes: In your app delegate’s header file:
    • Import the MoPub.h header file
    • Import the MPRewardedVideo.h header file
  3. Initialize: Declare that your app delegate implements the MPRewardedVideoDelegate protocol. And In your app delegate’s implementation file, initialize rewarded video through the MoPub object using the below method, passing in your app delegate as the delegate. More details about integration are available below [MoPub sharedInstance] initializeRewardedVideoWithGlobalMediationSettings:nil delegate:self];
  4. Pre-fetch the rewarded video ad: for the given adunit, precache the rewarded video as shown below[MPRewardedVideo loadRewardedVideoAdWithAdUnitID:@”[Placeholder Ad Unit ID]” withMediationSettings:nil];
  5. Verify if the rewarded video is precached: In your view controller, call the +hasAdAvailableForAdUnitID: on the MPRewardedVideo class passing in your ad unit ID prior to displaying the ad.
  6. Show the rewarded video: Finally present the precached rewarded video

Optional- Implementing the delegate callbacks

`MPRewardedVideoDelegate’ includes a variety of optional callbacks that you can use to be notified of events, e.g. when a rewarded video has successfully loaded, or when a rewarded video is about to appear. Check out the MPRewardedVideoDelegate for the following methods:

  • (void)rewardedVideoAdDidLoadForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdDidFailToLoadForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdWillAppearForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdDidAppearForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdWillDisappearForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdDidDisappearForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdDidExpireForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdDidFailToPlayForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdDidReceiveTapEventForAdUnitID:(NSString *)adUnitID
  • (void)rewardedVideoAdWillLeaveApplicationForAdUnitID
  • (void)rewardedVideoAdShouldRewardForAdUnitID:(NSString *)adUnitID

Here’s a couple examples of how callbacks can be useful:

  • Example 1 (Pre-fetching): You can be notified when a rewarded video has been fetched successfully by implementing `-rewardedVideoAdDidLoadForAdUnitID:`.
  • Example 2 (Presentation/dismissal callbacks) : Suppose that your application is a game. You’d like to pause the game whenever you present a rewarded video, and resume it when the rewarded video is dismissed. You can accomplish this by using the optional `-rewardedVideoAdWillAppearForAdUnitID:` and `-rewardedVideoAdDidDisappearForAdUnitID:` delegate callbacks:
- (void)rewardedVideoAdWillAppearForAdUnitID:(NSString *)adUnitID {
    [self pauseGame];
}

- (void)rewardedVideoAdDidDisappearForAdUnitID:(NSString *)adUnitID {
    [self resumeGame];
}

Advanced: Mediation Settings

Mediation settings enable you to pass in third-party network specific settings and can be provided as additional parameters during the rewarded video initialization call. For Vungle, Unity and Chartboost mediation, this is the only mechanism by which a user-Id or custom-Id can be specified in networks’ server-side callbacks.

Upon initializing rewarded video via a call to

`-initializeRewardedVideoWithGlobalMediationSettings:delegate:`, you may pass in an array of configured global mediation objects. These objects are used to configure the underlying ad networks which in turn affects all ads for the specific network. Any given ad network may or may not have global mediation settings classes. Using a global mediation settings class involves:

  1. Create an instance of a mediation settings class for each ad network that may supply ads to your application.
  2. Configure the properties on the mediation settings objects.
  3. Pass them inside an array when initializing rewarded video.

Furthermore, you may pass in instance mediation settings when calling `+loadRewardedVideoAdWithAdUnitID:withMediationSettings:`. These settings apply to the ad network for the ad unit ID you are using to load an ad. Any given ad network may or may not have instance mediation settings classes. Using a instance mediation settings class involves:

  1. Create an instance of a mediation settings class for each ad network that may supply ads to your ad unit ID.
  2. Configure the properties on the mediation settings objects.
  3. Pass them inside an array when loading a rewarded video ad.

Look in your ad network’s custom event directory to see what mediation settings objects exist for the network.

Code Examples

The following code snippets demonstrate the above steps in the context of a game application; specifically, how to pre-fetch a rewarded video and display it after a level has ended.

// AppDelegate.h
#import <UIKit/UIKit.h>
#import "MoPub.h"
#import "MPRewardedVideo.h"

@interface AppDelegate : UIResponder <UIApplicationDelegate, MPRewardedVideoDelegate>

@property (strong, nonatomic) UIWindow *window;
// Our user’s current coin amount.
@property (nonatomic, assign) NSInteger coinAmount;

@end

// AppDelegate.m
@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // … your -application:didFinishLaunchingWithOptions: code …
    [self loadRewardedVideo];
    
    return YES;
}

- (void)loadRewardedVideo {
    // Initialize rewarded video before loading any ads.
    [MoPub sharedInstance] initializeRewardedVideoWithGlobalMediationSettings:nil delegate:self];

    // Fetch the rewarded video ad.
    [MPRewardedVideo loadRewardedVideoAdWithAdUnitID:@“[Placeholder Ad Unit ID]“ withMediationSettings:nil];
}

#pragma mark - MPRewardedVideoDelegate

- (void)rewardedVideoAdShouldRewardForAdUnitID:(NSString *)adUnitID reward:(MPRewardedVideoReward *)reward {
    // You define the reward's currency type on your ad network's portal.
    // We have defined coin as a currency type and will increment the user's coin amount when we receive a reward with coin as 
    // the currency type.
    if ([reward.currencyType isEqualToString:@"coin"]) {
        if ([reward.amount integerValue] == kMPRewardedVideoRewardCurrencyAmountUnspecified) {
            // Come up with your own reward amount.
        } else {
            self.coinAmount += [reward.amount integerValue];
        }
    }
}

// … other MPRewardedVideoDelegate delegate methods…

@end

// MyViewController.m
#import "MyViewController.h"

@implementation MyViewController
// … your view controller code …

// Present the ad only after it is ready.
- (void)levelDidEnd {
    if ([MPRewardedVideo hasAdAvailableForAdUnitID:@"[Placeholder Ad Unit ID]"]) {
        [MPRewardedVideo presentRewardedVideoAdForAdUnitID:@"[Placeholder Ad Unit ID]" fromViewController:self];
    } else {
        // The rewarded video wasn't ready, so continue as usual.
    }
}

@end

Choosing between Client-side and Server-side Rewarding

The MoPub SDK provides ad request options for both Client-side and Server-side Rewarding.

  • Client-side ad request – Option 1
    • loadRewardedVideoAdWithAdUnitID:(NSString *)adUnitID 
    keywords:(NSString *)keywords 
    location:(CLLocation *)location 
    mediationSettings:(NSArray *)mediationSettings;
  • Client-side ad request – Option 2
    • loadRewardedVideoAdWithAdUnitID:(NSString *)adUnitID 
    withMediationSettings:(NSArray *)mediationSettings;
  • Server-Side ad request
    • loadRewardedVideoAdWithAdUnitID:(NSString *)adUnitID 
    keywords:(NSString *)keywords 
    location:(CLLocation *)location 
    customerId:(NSString *)customerId 
    mediationSettings:(NSArray *)mediationSettings;
  • Note that the customerID string is passed for the Server-side ad request. This passed value fills in the %%CUSTOMER_ID%% macro provided in the Server-side Callback URL in the UI.
  • Note that the method `rewardedVideoAdShouldRewardForAdUnitID` is not called for Server-side rewards. Instead a completion ping is sent to the MoPub Ad Server and a callback is sent to a reward server.
  • For more details about callbacks, see “Rewarded Video Server-side Setup” for more details.

See Also:

Rewarded Video Best Practices

Unity Engine Integration