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

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 by following the instructions here.

Basic Integration

1. Include the custom event class and JAR for the mediated networks.

All the CustomEventRewardedVideo subclasses are included in the extras/com/mopub/mobileads/ directory:

  • AdColony: AdColonyRewardedVideo.java
  • Chartboost: ChartboostRewardedVideo.java
  • Vungle: VungleRewardedVideo.java
  • Unity Ads: UnityRewardedVideo.java
  • Tapjoy: TapjoyRewardedVideo.java

For each mediated network that you would like to support, copy the corresponding source file into your application’s com.mopub.mobileads package, and copy the corresponding mediated network SDKs into your application’s libs/ directory.

Initialize MoPub rewarded video in your Activity’s onCreate().

You do not need to explicitly initialize any mediated rewarded video networks — the MoPub SDK properly handles that logic.

public class MainActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        MoPubRewardedVideos.initializeRewardedVideo(this);
        // ...
    }
}

Cache rewarded videos for a given adUnitId (often a placement within the app, e.g. game over screen or in-app store). For example:

private void loadRewardedVideo(){
    MoPubRewardedVideos.loadRewardedVideo("YOUR_AD_UNIT_ID");
}

Check if rewarded videos are available using MoPub.hasRewardedVideo(String adUnitId) before offering to display them to the user.

Show the rewarded video when the user clicks to watch it. For example:

private void userClickedToWatchAd() {
    MoPubRewardedVideos.showRewardedVideo("YOUR_AD_UNIT_ID");
}

2. Integrate lifecycle callbacks

Network SDKs need to be notified of changes in the activity lifecycle so they can keep track of the current activity and load/show rewarded videos. For example, you can add lifecycle callbacks to all of your activities (including your Launcher Activity) that will load or show rewarded videos.

Important note for specific networks:

  • For AdColony and Vungle rewarded videos, the only required lifecycle callbacks are onCreate, onPause, and onResume.
  • Chartboost rewarded videos require the full set below.
  • For additional help on Tapjoy integration, check here
  • Unity only requires onCreate and onResume. (see Integrate With the Activity Lifecycle)
public class MainActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       MoPubRewardedVideos.initializeRewardedVideo(this);
       MoPub.onCreate(this);
       // ...
    }

    @Override
    public void onPause() {
        super.onPause();
        MoPub.onPause(this);
    }

    @Override
    public void onResume() {
        super.onResume();
        MoPub.onResume(this);
    }

    // The following methods are required for Chartboost rewarded video mediation
    @Override
    public void onStart() {
        super.onStart();
        MoPub.onStart(this);
    }

    @Override
    public void onRestart() {
        super.onRestart();
        MoPub.onRestart(this);
    }

    @Override
    public void onStop() {
        super.onStop();
        MoPub.onStop(this);
    }

    @Override
    public void onDestroy() {
        super.onDestroy();
        MoPub.onDestroy(this);
    }

    @Override
    public void onBackPressed() {
        super.onBackPressed();
        MoPub.onBackPressed(this);
    }
}

Optional: Set a rewarded video listener

You can set a rewarded video listener to receive relevant callbacks.

public class MainActivity extends Activity {
    private MoPubRewardedVideoListener rewardedVideoListener;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        MoPubRewardedVideos.initializeRewardedVideo(this);
        MoPub.onCreate(this);

        rewardedVideoListener = new MoPubRewardedVideoListener() {
            @Override
            public void onRewardedVideoLoadSuccess(String adUnitId) {
                // Called when the video for the given adUnitId has loaded. At this point you should be able to call MoPubRewardedVideos.showRewardedVideo(String) to show the video.
            }
            @Override
            public void onRewardedVideoLoadFailure(String adUnitId, MoPubErrorCode errorCode) {
                // 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.
            }

            @Override
            public void onRewardedVideoStarted(String adUnitId) {
                // Called when a rewarded video starts playing.
            }

            @Override
            public void onRewardedVideoPlaybackError(String adUnitId, MoPubErrorCode errorCode) {
                //  Called when there is an error during video playback.
            }

            @Override
            public void onRewardedVideoClosed(String adUnitId) {
                // Called when a rewarded video is closed. At this point your application should resume.
            }

            @Override
            public void onRewardedVideoCompleted(Set<String> adUnitIds, MoPubReward reward) {
                // Called when a rewarded video is completed and the user should be rewarded.
                // You can query the reward object with boolean isSuccessful(), String getLabel(), and int getAmount().
            }
        };

        MoPubRewardedVideos.setRewardedVideoListener(rewardedVideoListener);
    }
}

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.

Each subclass of CustomEventRewardedVideo specifies its own implementation of mediation settings with its own constructor.For example:

public class MainActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       MoPubRewardedVideos.initializeRewardedVideo(this,

        /* ChartboostMediationSettings */
        new ChartboostMediationSettings("CB_CUSTOM_ID"),

        /* AdColonyMediationSettings */
        new AdColonyMediationSettings(true, true),

        /* VungleMediationSettings */
        new VungleMediationSettings.Builder()
            .withUserId("VUNGLE_USER_ID")
            .withCancelDialogTitle("Cancel?")
            .build();
        );
        MoPub.onCreate(this);
        // ...
    }
}

Advanced: Mediated Network Pre-initialization

This API has been deprecated as of MoPub 5.0. Make sure to switch over to using the new initializaton API, which will continue to allow you to initialize rewarded videos.

To mediate ad load performance, a new overloaded method MoPubRewardedVideos.initializeRewardedVideo() is introduced:

public static void initializeRewardedVideo(@NonNull Activity activity,
    @NonNull List<Class<? extends CustomEventRewardedVideo>> networksToInit,
    MediationSettings... mediationSettings)

Passing in a list of rewarded video network classes that extend from CustomEventRewardedVideo 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 MoPubRewardedVideo.loadRewardedVideo() will update the initialization parameters in the cache for that network.

Note: The existing on-demand network SDK initialization can be combined with this partial pre-initialization call.

An example of a partial pre-initialization is shown below:

private static boolean sRewardedVideoInitialized;


// Include any custom event rewarded video classes, if available, for initialization.
private static final List<Class<? extends CustomEventRewardedVideo>> sNetworksToInit = Arrays.asList(
    AdColonyRewardedVideo.class,
    ChartboostRewardedVideo.class,
    FacebookRewardedVideo.class,
    GooglePlayServicesRewardedVideo.class);

// The following code block will trigger pre-initialization of the networks defined above:
if (!sRewardedVideoInitialized) {
    MoPubRewardedVideos.initializeRewardedVideo(getActivity(), sNetworksToInit);
    sRewardedVideoInitialized = true;
}

To completely opt-out of network SDK pre-initialization, no code change is required - just call the existing “MoPubRewardedVideos.initializeRewardedVideo()” as before:

  public static void initializeRewardedVideo(@NonNull Activity activity, MediationSettings... mediationSettings)

Advanced: 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 MoPubRewardedVideos.showRewardedVideo(String adUnitId, String customData) – the second parameter is an optional String containing custom data. The optional custom data will be sent as part of the URL in the server-to-server callback.

Considerations:

  • 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 dashboard will also need to include a query parameter that uses the %%CUSTOM_DATA%% macro. For example:

https://www.your.com/reward?custom_data=%%CUSTOM_DATA%%

Known Limitations

  • Concurrent ad requests using the same adunits or multiple adunits is not recommended until we make additional improvements.

Last updated June 14, 2018

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.

© 2018 MoPub Inc.