android-guidelines | Rewarded Video Ads

Rewarded Video ads are short (15 sec), non-skippable HD videos, which a user opts-in to watch in exchange for rewards like virtual goods or in-game gifts. Preferred by acquisition and brand marketers, these are perfect for integrating in shop fronts, start of gameplay or end of gameplay and help increase the retention of the non paying users. With the reward action dependent only on completed video views, rewarded video ads provide high quality engaged users to advertisers and high eCPMs to publishers.

Follow these simple steps and start monetizing with Rewarded Video ads:

Setting up a Rewarded Video Ad

  1. To display a rewarded video ad, you need a interstitial placement ID.
  2. After adding your app, select REWARDED VIDEO to create a placement for ad type Interstitial.
  3. Once you successfully create the placement, the placement ID is available.

You can fill in the key value pair for the reward details, the SDK will honour when providing the callback when the user has completed the requisite action. For example, you could fill in the following reward details:
Key = Coins
Value = 1000
Note: InMobi SDK provides you the callback in any case, so you could choose not to fill in anything and handle the rewards completely at your end.

Adding a rewarded Video Ad to your App

Creating a Rewarded Video Ad

To create a rewarded video ad, create an instance of an InMobiInterstitial:

InMobiInterstitial interstitialAd = new InMobiInterstitial(InterstitialAdsActivity.this, 1471550843414L, mInterstitialAdEventListener);
	

Here, mInterstitialAdEventListener is an implementation of the InterstitialAdEventListener abstract class. It is mandatory to supply an implementation of this interface to create an interstitial ad.

Notes:

  • The InMobiInterstitial class is not thread-safe. An interstitial instance must be created on the UI thread.
  • Similarly, all methods on this instance must be called on the UI thread. Not doing so will lead to unpredictable behavior and may affect your ability to monetize with InMobi.

The InterstitialAdEventListener abstract class allows you to listen to key lifecycle events for an interstitial ad. You should listen to these events to ensure that your application correctly handles the various lifecycle transitions.

   /**
* Listener for receiving notifications during the lifecycle of an interstitial.
*/
public abstract class InterstitialAdEventListener {
   /**
    * Called to indicate that an ad was loaded and it can now be shown. This will always be called
    * <strong>after</strong> the {@link #onAdReceived(InMobiInterstitial)} callback.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad which was loaded
    */
   public void onAdLoadSucceeded(InMobiInterstitial ad) {}
   /**
    * Callback to signal that a request to fetch an ad (by calling
    * {@link InMobiInterstitial#load()} failed. The status code indicating the reason for failure
    * is available as a parameter. You should call {@link InMobiInterstitial#load()} again to
    * request a fresh ad.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad which failed to load
    * @param status Represents the {@link InMobiAdRequestStatus} status containing error reason
    */
   public void onAdLoadFailed(InMobiInterstitial ad, InMobiAdRequestStatus status) {}
   /**
    * Called to indicate that an ad is available in response to a request for an ad (by calling
    * {@link InMobiInterstitial#load()}. <p class="note"><strong>Note</strong> This does not
    * indicate that the ad can be shown yet. Your code should show an ad <strong>after</strong> the
    * {@link #onAdLoadSucceeded(InMobiInterstitial)} method is called. Alternately, if you do not
    * want to handle this event, you must test if the ad is ready to be shown by checking the
    * result of calling the {@link InMobiInterstitial#isReady()} method.</p>
    *
    * @param ad Represents the {@link InMobiInterstitial} ad for which ad content was received
    */
   public void onAdReceived(InMobiInterstitial ad) {}
   /**
    * Called to indicate that an ad interaction was observed.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad on which user clicked
    * @param params Represents the click parameters
    */
   public void onAdClicked(InMobiInterstitial ad, Map<Object, Object> params) {}
   /**
    * Called to indicate that the ad will be launching a fullscreen overlay.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad which will display
    */
   public void onAdWillDisplay(InMobiInterstitial ad) {}
   /**
    * Called to indicate that the fullscreen overlay is now the topmost screen.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad which is displayed
    */
   public void onAdDisplayed(InMobiInterstitial ad) {}
   /**
    * Called to indicate that a request to show an ad (by calling {@link InMobiInterstitial#show()}
    * failed. You should call {@link InMobiInterstitial#load()} to request for a fresh ad.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad which failed to show
    */
   public void onAdDisplayFailed(InMobiInterstitial ad) {}
   /**
    * Called to indicate that the fullscreen overlay opened by the ad was closed.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad which was dismissed
    */
   public void onAdDismissed(InMobiInterstitial ad) {}
   /**
    * Called to indicate that the user may leave the application on account of interacting with the ad.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad
    */
   public void onUserLeftApplication(InMobiInterstitial ad) {}
   /**
    * Called to indicate that rewards have been unlocked.
    *
    * @param ad Represents the {@link InMobiInterstitial} ad for which rewards was unlocked
    * @param rewards Represents the rewards unlocked
    */
   public void onRewardsUnlocked(InMobiInterstitial ad, Map<Object, Object> rewards) {}
 }
	

Loading a Rewarded Video Ad

To request for a interstitial ad, call the load() method on the InMobiInterstitial instance:

interstitialAd.load();
	

The InterstitialAdListener2 event interface notifies the result of this method. If the ad request was successful, the onAdReceived(InMobiInterstitial) event is generated. This is followed by either the onAdLoadSucceeded or the onAdLoadFailed event.

If the onAdLoadFailedevent is generated, the reason is indicated by the InMobiAdRequestStatus object passed in this event.

If the onAdLoadSucceeded event is generated, you can show the ad anytime after this by calling show() on the InMobiInterstitial instance.

Note: Calling load() on the same interstitial ad after the onAdLoadSucceeded event is generated by the SDK is not guaranteed to request a fresh ad from the network. A fresh ad will only be fetched if either the previous ad was discarded by the SDK, or if the ad expired or the user cleared application data and caches.

Showing a Rewarded Video Ad

To show a rewarded video ad, call show() on the InMobiInterstitial instance anytime after the onAdLoadSucceeded event has been generated by the SDK.

The code fragment below illustrates the same.

 InterstitialAdListener2 mInterstitialListener = new InMobiInterstitial.InterstitialAdListener2() {
        // implementation for other events
        // onAdReceived, onAdLoaFailed, etc
        @Override
        public void onAdLoadSucceeded(InMobiInterstitial inMobiInterstitial) {
            Log.d(TAG, "Ad can now be shown!");
            mCanShowAd = true;
        }
    };
   void init() {
       InMobiInterstitial interstitialAd = new InMobiInterstitial(GameActivity.this, 1471550843414L, mInterstitialListener);
   }
   void prepareGameLevel() {
       interstitialAd.load();
   }
   void handleGameLevelCompleted() {
        If (mCanShowAd) interstitialAd.show();
   }
	

The InterstitialAdListener2 interface notifies the result of this request.

If the ad can be shown, the SDK will notify your code by calling on the onAdWillDisplay interface, followed by calling the onAdDisplayed method when the ad is actually presented on the screen.

If the ad cannot be displayed, the onAdDisplayFailed event is generated by the SDK to let your application know that the ad could not be displayed. You can request for a fresh ad by calling load() again to handle this event.

When an interstitial ad is dismissed, your application will be notified in the onAdDismissed callback.

Animations

You can animate the presenting and dismissing of the interstitial ad by supplying animation resource IDs to be used in this process. This is done simply by calling the show(int, int) variant:

interstitialAd.show(R.anim.anim_entry, R.anim.anim_exit);
	

Implementing the Callback for Rewards

For rewarded video ads, the SDK will generate the onAdRewardActionCompleted event, passing the meta data you configured on the InMobi support portal. You can handle this event in the following way:

    InterstitialAdEventListener mInterstitialAdEventListener = new InterstitialAdEventListener() {
        // implementation for other events
        // onAdLoadSucceeded, onAdDisplayed, etc
        @Override
        public void onAdRewardActionCompleted(InMobiInterstitial inMobiInterstitial, Map map) {
            Log.d(TAG, "Ad rewards unlocked!");
            for (Object key : map.keySet()) {
                Object value = map.get(key);
                Log.v(TAG, "Unlocked " + value + " " + key);
            }
        }
    };
	

You can check the code samples for interstitial ad integrations on GitHub here.

Retrieving CreativeID

At times, there are rogue advertisers who escape all the ad quality checks and end up compromising the user experience on the app by showcasing either an irrelevant, distasteful or disrupting creative to the user. To combat such situations, you can retrieve the creativeID of the ad instance and report back to your InMobi point of contact with the encrypted creativeID.

mInterstitialAd.getCreativeId()// mInterstitialAd is an example instance.

Testing the Integration

  1. Configure the test mode on InMobi portal.

    Go to Tools - Diagnostics and switch Test Mode to either Global ON or Selective ON.

    If you are integrating an ad unit for the first time Set Test Mode to Global ON.
    If you want to selectively turn on test traffic for a set of devicesĀ·

    You already have a prior version of the SDK integrated for this particular ad unit and therefore you should restrict your testing to only few devices
    Set Test Mode to Selective ON.

    In the device section:

    1. In the Device ID box, type the device ID.
    2. In the Device Name box, set any name.
    3. Click Add Device to add the test device.

    If you already have a device configured, you can select the device and test mode would be enabled.

    Note: You MUST turn off the test mode before going live or else your app will fail to monetize.

    Now you are all set to get test ads.

    Getting the Device ID

    The device id is the Google Play Advertising ID (GPID). To get the device ID, configure the SDK to print debug logs to the console. You can do so by adding the following line to your Activity where you are integrating rewarded video ads.

    InMobiSdk.setLogLevel(LogLevel.DEBUG);
    		

    The device ID will now be printed in debug logs in the DDMS console:

  2. You will also get feedback on the diagnostics tab on the ad unit and ad request and this can be particularly helpful during integration.

Helpful Debug Information

Once you have enabled debug logs as mentioned in step 1, SDK will print key logs to the DDMS console that provide useful information about the initialization and ad load lifecycle.

The following tables capture these logs.

SDK Initialization

Scenario Log Level Logs
Publisher passed null or empty account id Error Account id cannot be null or empty. Please provide a valid Account id.
Publisher passed a valid account id Debug InMobi SDK initialized with account id: <account id>
Publisher Passed an invalid account Id Error Invalid account id passed to init. Please provide a valid account id.
Publisher did not grant the mandatory permissions Debug Please grant the mandatory permissions : INTERNET & ACCESS_NETWORK_STATE, SDK could not be initialized.
Permissions granted to the SDK Debug Permissions granted to the SDK are :<List of permissions granted>
Newer version of SDK is available Debug A newer version (ver. 6.0.0) of the InMobi SDK is available! You are currently on an older version (ver. 5.3.1). Download the latest InMobi SDK from http://www.inmobi.com/products/sdk/#downloads

Common Ad Lifecycle Messages

Scenario Log Level Logs
Ad requested when no network available Error LogLevel Network not reachable currently. Please try again.
Ad requested when ad state is loading or available Error LogLevel An ad load is already in progress. Please wait for the load to complete before requesting for another ad (Placement id : <placement id> ).
Ad requested when ad is viewed by user Error LogLevel An ad is currently being viewed by the user. Please wait for the user to close the ad before requesting for another ad (Placement id : <placement id> ).
Publisher device Id Debug LogLevel Publisher device id is <Device Id>
Requested ad being returned from cache Returning ad from cache for the Placement Id - <Placement Id>
Requested ad being fetched from network Ad will be fetched from network for the Placement Id - <Placement Id>

Messages for Rewarded Video Ad Integrations

Scenario Log Level Logs
Publisher created an interstitial without initializing the SDK Error Please initialize the SDK before creating an interstitial ad
Publisher called load on interstitial Debug Fetching an interstitial ad for placement id: <placement id>
Successfully fetched ad Debug Interstitial ad successfully fetched for placement id: <Placement id>
Failed to fetch the ad Error Failed to fetch interstitial ad for placement id:<Placement id> with error: <Status code / message>
Started loading the interstitial in a webview Debug Started loading interstitial ad markup in the webview for placement id: <Placement id>
Interstitial successfully loaded in the webview Debug Successfully loaded interstitial ad markup in the webview for placement id: <placement id>
Failed to load interstitial in the webview Error Failed to load interstitial markup in the webview for placement id: <placement id>
Failed to load interstitial in the webview due to timeout Error Failed to load interstitial markup in the webview due to timeout for placement id: <placement id>
Interstitial Ad displayed Debug Successfully displayed Interstitial for placement id:<placement id>
Interstitial Ad dismissed Debug Interstitial ad dismissed for placement id:<placement id>
No Listener specified Set Listener to null in constructor Error The Ad unit cannot be created as no event listener was supplied. Please attach a listener to proceed
Null context Set Context to null in constructor Error Unable to create ad unit with NULL context object
Ad show before ready Show ad before it's ready Error Ad Load is not complete. Please wait for the Ad to be in a ready state before calling show The supplied resource id with show for animations is invalid
InMobiAdActivity not added Error Do not declare InMobiAdActivity in manifest file.

In addition to logs printed by the SDK, you can also get feedback on the diagnostics tab on the ad unit and ad request, which can be particularly helpful during integration.

Advanced: Prefetching Rewarded Video Ads

InMobi SDK can prefetch rewarded video ads to leverage each monetization opportunity in your app. The InMobi SDK allows you to create interstitial rewarded video ad units that can be maintained in your Application subclass. Your app can then use the video ad unit in the Activity where the monetization event will occur.

public class YourApplication extends Application {
    ... 
    private InMobiAdRequest mInMobiAdRequest;
    private InterstitialAdRequestListener mListener;
    Private InMobiInterstitial mRewardedVideoAd;
    ...
    public void onCreate() {
        mInMobiAdRequest = new InMobiAdRequest.Builder(PlacementId.YOUR_PLACEMENT_ID)
                .build();
        mListener = new InMobiInterstitial.InterstitialAdRequestListener() {
            @Override
            public void onAdRequestCompleted(InMobiAdRequestStatus status, InMobiInterstitial videoAd) {
                if (status.getStatusCode() == NO_ERROR && videoAd != null) {
                    mRewardedVideoAd = videoAd;
                } 
            }
        };
        InMobiInterstitial.requestAd(this, mInMobiAdRequest, mListener);
        ...
    }
    public InMobiInterstitial getRewardedVideoAd() {
        return mRewardedVideoAd;
    }
}
	

In the Activity you are trying to monetize, you can then get an instance of this ad unit by calling the getVideoAd() method on your Application subclass. Request the ad unit to load the ad markup by calling load(), just as you would for a non-prefetched interstitial ad unit. When your monetization event occurs, request for the video to be played by calling show() on the ad unit.