Rewarded Video Ads

Overview

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

MoPub’s mediation solution officially supports rewarded videos from 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 rewards, such as at the end of a game level or at currency redemption points. Once your user has completed the rewarded experience, you can designate the reward they will receive.

Basic Integration

Step 1. Initialize Rewarded Video

MoPub.InitializeSdk()

Step 2. Pre-Fetch the Rewarded Video Ad

MoPub.RequestRewardedVideo(rewardedVideoAdUnit, mediationSettings, keywords, latitude, longitude, customerId);

Step 3. Show the Rewarded Video

Check if the rewarded video has been fully cached by calling MoPub.HasRewardedVideo(rewardedVideoAdUnit) before offering to display it to the user:

MoPub.HasRewardedVideo(rewardedVideoAdUnit)

Show the rewarded video:

MoPub.ShowRewardedVideo(rewardedVideoAdUnit);

Step 4. 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 returned, MoPub logs the response and does 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:

Step Example
1. Parse the callback URL and retrieve the query parameters. Callback URL: https://api.example.com/callback.php?customer_id=3453523454&id=70bae1905f7844a3a012a5f4173021db&hash=28f3b28b09b2578db06ee371990b5a02882523eba954d5a1b57afe2c7e7d3f10&value=20&type=Coins
2. Drop the verifier key and value from the array of parameters. Verifier Hash: hash=28f3b28b09b2578db06ee371990b5a02882523eba954d5a1b57afe2c7e7d3f10
3. Sort the query parameters alphabetically. Alphabetical array of query parameters (excluding the verifier)
* customer_id=3453523454
* id=70bae1905f7844a3a012a5f4173021db
* type=Coins
* value=20
4. Concatenate the values in that alphabetical order. Concatenated String: 345352345470bae1905f7844a3a012a5f4173021dbCoins20
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: 28f3b28b09b2578db06ee371990b5a02882523eba954d5a1b57afe2c7e7d3f10
* The result matches the hash passed in the request

After generating the hash, compare the received hash with your generated hash. They should be identical. Once the hash is 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.

Step 5. Optionally Implement Lifecycle Callbacks

These are the rewarded video-related callback handlers:

OnRewardedVideoLoadedEvent (string adUnitId)
OnRewardedVideoFailedEvent (string adUnitId, string errorMsg)
OnRewardedVideoExpiredEvent (string adUnitId)
OnRewardedVideoShownEvent (string adUnitId)
OnRewardedVideoClickedEvent (string adUnitId)
OnRewardedVideoFailedToPlayEvent (string adUnitId, string errorMsg)
OnRewardedVideoReceivedRewardEvent (string adUnitId, string label, float amount)
OnRewardedVideoClosedEvent (string adUnitId)
OnRewardedVideoLeavingApplicationEvent (string adUnitId)

Best Practices

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

  • You can be notified that a rewarded video was fetched successfully by implementing onRewardedVideoLoaded. We highly recommend waiting for the onRewardedVideoLoaded callback before showing the rewarded video. This ensures that the ad has enough time to load and show as expected.

Known Limitations

  • Reward type must be in English only. We do not currently support localized characters.

  • At this time, we do not support concurrent ad requests using the same ad unit ID.

Last updated August 24, 2020

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.

© 2020 MoPub (a division of Twitter, Inc.)