Rewarded Video Ads
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 mediation solution officially supports rewarded videos from popular ad networks. We give you the flexibility to work with these popular ad networks without any extra integration with network SDKs. We recommend placing rewarded video ads where your users are already engaging with in-app purchases or in locations where users may be seeking an in-app reward, such as the end of a game or at currency redemption points. Once your users have finished watching the video ad, you can designate the reward they will receive.
- In the MoPub UI, create an account with MoPub, create an app, and create an ad unit whose format is ‘Rewarded Video’.
- Follow our steps to get started by integrating the MoPub SDK into your project.
- If you use mediation, make sure you have added the ad network SDKs and the corresponding adapters you wish to use to your app.
1. Import the required headers
- Import the
- Import the
2. Initialize the MoPub SDK
Initialize the MoPub SDK on app launches. You can typically do that in your AppDelegate. Note: If you have been using the
[[MoPub sharedInstance] initializeRewardedVideoWithGlobalMediationSettings] API, it has been deprecated in the 5.0.0 SDK release, so make sure to start using the new initialization API.
You do not need to explicitly initialize any mediated rewarded video network SDKs via their APIs — the MoPub SDK properly handles that logic on your behalf.
3. Request and Cache the Rewarded Video
Cache a rewarded video for the given ad unit ID (often a placement within the app, e.g. game-over screen or in-app store):
4. Set the delegate to receive rewarded video events
You should set
MPRewardedVideo delegate for a given adunit to allow the application to respond to the events for the corresponding ad.
[MPRewardedVideo setDelegate:self forAdUnitId:self.info.ID];
5. Show the Rewarded Video
Check if the rewarded video has been fully cached by calling
hasAdAvailableForAdUnitID: before offering to display it to the user.
Show the rewarded video when the user clicks to watch it.
withReward accepts an
MPRewardedVideoReward reward object, which can be extracted from the
[MPRewardedVideo availableRewardsForAdUnitID:@"YOUR_AD_UNIT_ID"] NSArray.
customData accepts an NSString containing any applicable data unique to that user you would like to pass to the ad request.
[MPRewardedVideo presentRewardedVideoAdForAdUnitID:@"YOUR_AD_UNIT_ID" fromViewController:self withReward:YOUR_MPRewardedVideoReward customData:@"YOUR_CUSTOM_DATA"];
6. Configure the Callback Server
Your callback server must return a 200 HTTP response status code when it successfully receives the reward callback. If your server returns a 500 HTTP response status code, MoPub will continually call the server at increasing intervals until your server returns a 200 HTTP code or the maximum retry limit of 14 is reached. The maximum retry limit is subjected to a two-hour time limit. MoPub stops the retries when your server returns a 200 HTTP response status code.
|HTTP Response Code||Description||When Used|
|200||Successful Request||Return this response code for a successful callback|
|500||Internal Server Error||Return this response code when a callback server error occurs|
If any other HTTP response status code is used, MoPub will log the response and will not retry.
If the MoPub server detects a failure to connect, it may retry, to ensure that your server receives callbacks. Because of this, there is a slight possibility that your callback server may receive duplicate callbacks (from the same callback URL, for the same rewarded video). We recommend that you store the hash ID (the value from the
%%VERIFIER%% macro) and only give a user one reward for each unique ID.
To secure the callback sent from MoPub to your callback server, the
%%VERIFIER%% macro must be present in the callback URL. The
%%VERIFIER%% is a SHA256 hash generated from the callback’s parameter values and uses a Secret Key. You can find the Callback Secret Key in the MoPub UI Account Settings page.
Your server should use the Callback Secret Key to regenerate the SHA256 hash from the callback’s parameter values. If the hash generated on your server matches the one in the callback sent by MoPub, this signals that the callback is valid and the user should be rewarded.
To generate the hash on the reward server:
|1. Parse the callback URL and retrieve the query parameters.||Callback URL:
|2. Drop the verifier key and value from the array of parameters.||Verifier Hash:
|3. Sort the query parameters alphabetically.||Alphabetical array of query parameters (excluding the verifier)
|4. Concatenate the values in that alphabetical order.||Concatenated String:
|5. Hash the concatenated string using a HMAC SHA256 hash algorithm and the Callback Secret Key.||HMAC SHA256 the concatenated string and the Secret Key: 7dbcfd2a42134f47bfb72daa02f85ec9
* The result:
* The result matches the hash passed in the request
After generating the hash, compare the received hash with your generated hash. They should equal each other. Once verified, your server must return a 200 response code to MoPub and can reward the user.
Refer to our list of available server-side callback macros here.
7. Optional: Implement the Delegate Methods
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 // Called when the video for the given adUnitId has loaded. At this point you should be able to call presentRewardedVideoAdForAdUnitID to show the video. - (void)rewardedVideoAdDidFailToLoadForAdUnitID:(NSString *)adUnitID error:(NSError *)error // Called when a video fails to load for the given adUnitId. The provided error code will provide more insight into the reason for the failure to load. - (void)rewardedVideoAdDidFailToPlayForAdUnitID:(NSString *)adUnitID error:(NSError *)error // Called when there is an error during video playback. - (void)rewardedVideoAdWillAppearForAdUnitID:(NSString *)adUnitID // Called when a rewarded video starts playing. - (void)rewardedVideoAdDidAppearForAdUnitID:(NSString *)adUnitID - (void)rewardedVideoAdWillDisappearForAdUnitID:(NSString *)adUnitID - (void)rewardedVideoAdDidDisappearForAdUnitID:(NSString *)adUnitID // Called when a rewarded video is closed. At this point your application should resume. - (void)rewardedVideoAdShouldRewardForAdUnitID:(NSString *)adUnitID reward:(MPRewardedVideoReward *)reward // Called when a rewarded video is completed and the user should be rewarded. - (void)rewardedVideoAdDidExpireForAdUnitID:(NSString *)adUnitID // Called when a rewarded video is expired. - (void)rewardedVideoAdDidReceiveTapEventForAdUnitID:(NSString *)adUnitID - (void)rewardedVideoAdWillLeaveApplicationForAdUnitID:(NSString *)adUnitID /** Called when an impression is fired on a Rewarded Video. Includes information about the impression if applicable. @param adUnitID The ad unit ID of the rewarded video that fired the impression. @param impressionData Information about the impression, or @c nil if the server didn't return any information. */ - (void)didTrackImpressionWithAdUnitID:(NSString *)adUnitID impressionData:(MPImpressionData *)impressionData;
Here are a few examples of how callacks can be useful:
- You can be notified that a rewarded video was fetched successfully by implementing
- If 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 it using the
Advanced Use Cases
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, during Unity and Chartboost mediation, this is the only mechanism by which a user ID or customer ID can be specified in networks’ server-side callbacks.
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:
- Creating an instance of the global settings class for an ad networks that may supply ads to your application.
- Configuring the properties on the objects.
- Passing 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:
- Creating an instance of the mediation settings class for ad networks that may be loaded for your ad unit ID.
- Configuring the properties on the objects.
- Passing them inside an array when loading a rewarded video.
Mediated Network Pre-Initialization
Passing in a list of rewarded video network classes that extend from
MPMediationSdkInitializable will automatically try to pre-initialize those rewarded networks, in the order passed in, with the last cached initialization parameters for each network. If no cached initialization parameters are found for a network, pre-initialization for that network is skipped.
By pre-initializing the network SDKs, this gives the network the necessary lead time between SDK initialization and ad request to ensure a successful ad request. Every successful call to
loadRewardedVideoAdWithAdUnitID will update the initialization parameters in the cache for that network.
To utilize the rewarded video pre-initialization API, follow the instructions to do so when initializing the MoPub SDK. To opt out of the pre-initialization API, simply pass in an empty list.
Note: The existing on-demand network SDK initialization can be combined with this partial pre-initialization call.
Passing Custom Data
There may be cases where your reward server will need additional information to determine an appropriate reward for the user. When the rewarded video is presented, the app can call
+presentRewardedVideoAdForAdUnitID:fromViewController:withReward:customData:, and include an optional string containing custom data. The optional custom data will be sent as part of the URL in the server-to-server callback.
- It is recommended that the custom data string not exceed 8kb in size as this will significantly degrade performance. Try to keep the custom data payload as small as possible.
- Custom data will only be passed if the ad unit has been setup with a server side callback.
In addition to specifying the custom data at presentation time, the server-side callback URL in the MoPub UI will also need to include a query parameter that uses the
%%CUSTOM_DATA%% macro. For example:
- Concurrent ad requests using the same ad units is not supported until we make additional improvements.
Last updated August 27, 2019
TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.
© 2019 MoPub (a division of Twitter, Inc.)