Integrating Rewarded Video - Android


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 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
  • Review Rewarded Video Best Practices.

Basic Integration

  1. Include the custom event class and JAR for the mediated network Three CustomEventRewardedVideo subclasses are included in the extras/com/mopub/mobileads/ directory:
    • AdColonyRewardedVideo.java
    • ChartboostRewardedVideo.java
    • VungleRewardedVideo.java
    • UnityRewardedVideo.java
    • 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 SDK into your application’s libs/ directory.

  2. Initialize MoPub rewarded video in your initial 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);
    		// ...
    	}
    }
    
  3. 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");
        }
    
  4. Check if rewarded videos are available using ‘MoPubRewardedVideos.hasRewardedVideo(String adUnitId)’ before offering to display them to the user.
  5. Show the rewarded video when the user clicks to watch it.
    For example:
    private void userClickedToWatchAd() {
        MoPubRewardedVideos.showRewardedVideo("YOUR_AD_UNIT_ID");
        }
    

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

Note :

  • For AdColony and Vungle rewarded videos, the only required lifecycle callbacks are onCreate, onPause, and onResume.
  • Unity only requires onCreate and onResume. (see “ Integrate With the Activity Lifecycle “)
  • For additional information on Tapjoy, check here .
  • Chartboost rewarded videos require the full complement below.
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 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 ad unit id. 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 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().
			}
		};

		MoPub.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 and Chartboost mediation, this is the only mechanism by which to specific user- or custom-ID for use in server-side callbacks.

Each subclass of `CustomEventRewardedVideo` specifies its own implementations 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);
		// ...
	}
}

Choosing between Client-side and Server-side Rewarding

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

  • Ad request
loadRewardedVideo(@NonNull String adUnitId,
    @Nullable MoPubRewardedVideoManager.RequestParameters requestParameters,
    @Nullable MediationSettings... mediationSettings)
  • RequestParameters
  • public RequestParameters(@Nullable final String keywords, @Nullable final Location location,
        @Nullable final String customerId) {
            mKeywords = keywords;
            mLocation = location;
            mCustomerId = customerId;
        }
    
    • 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.
    • For more details about callbacks, see “ Rewarded Video Server-side Setup ” for more details.

    See Also:

    Rewarded Video Best Practices

    Unity Engine Integration

    Updated: August 2017