android-guidelines | Full-screen Video Ads

Full-screen video ads are short (15-30 sec), skippable videos, which help in monetization with high eCPMs. Preferred by brands and game developers, these are perfect for happy moments such as level wins and wait times in Player vs Player (PVP). Video ads leverage the power of sight, sound, and motion to create immersive experiences for the user thereby enhancing the in-app ad experience.

To create a video ad, you need to start with an interstitial ad placement. Once you have an interstitial ad placement, you have controls on the InMobi portal to either run a mix of static and video ads or video only.

You also have access to advanced video controls on whether you want to run skippable video ads and only when the user is on Wifi.

Follow these simple steps and start monetizing with Video ads:

Setting up a Full-screen Video Ad

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

Adding a Full-screen Video Ad to your App

Creating a Full-screen Video Ad

To create an interstitial ad, create an instance of an InMobiInterstitial:

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

Here, mInterstitialAdListener is an implementation of the InterstitialAdListener2 interface. 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 InterstitialAdListener2 interface 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 Full-screen Video Ad

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

interstitialAd.load();
	

Your application will be notified of the result of this request via the InterstitialAdEventListener abstract class. 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 onAdLoadFailed event 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 Full-screen Video Ad

To show an interstitial 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.

    InterstitialAdEventListener mInterstitialAdEventListener = new InterstitialAdEventListener() {
        // 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, mInterstitialAdEventListener);
   }
   void prepareGameLevel() {
       interstitialAd.load();
   }
   void handleGameLevelCompleted() {
        If (mCanShowAd) interstitialAd.show();
   }
	

Your application will be notified of the result of this request via the InterstitialAdEventListener abstract class.

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);
	

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 full-screen 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 Full-screen 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 Full-screen Video Ads

InMobi SDK can prefetch video ads to leverage each monetization opportunity in your app. The InMobi SDK allows you to create interstitial 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.

To prefetch video ads, you will need to create an InMobiAdRequest to supply specific targeting information to the Ad server.

public class YourApplication extends Application {
    ... 
    private InMobiAdRequest mInMobiAdRequest;
    private InterstitialAdRequestListener mListener;
    Private InMobiInterstitial mVideoAd;
    ...
    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) {
                    mVideoAd = videoAd;
                } 
            }
        };
        InMobiInterstitial.requestAd(this, mInMobiAdRequest, mListener);
        ...
    }
    public InMobiInterstitial getVideoAd() {
        return mVideoAd;
    }
}
	

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.