android-guidelines | Interstitial Ads

Interstitial ads are full page ads placed at natural break points in the app flow. With 10 times the real estate as compared to banner ads, Interstitials are guaranteed to catch your user's’ eye and drive higher revenue for your mobile business.

Follow these simple steps and start monetizing with Interstitial ads:

Setting up an Interstitial Ad

  1. To display an Interstitial 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 an Interstitial Ad to your App

Creating an Interstitial 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 interface InterstitialAdListener2 {
        /**
         * Callback to signal that a request to fetch an ad (by calling {@link #load()}
         * failed. The status code indicating the reason for failure is available as a
         * parameter.
         * You should call {@link #load()} again to request a fresh ad.
         * @param ad
         * @param status
         */
        void onAdLoadFailed(InMobiInterstitial inMobiInterstitial, InMobiAdRequestStatus status);
        /**
         * Called to indicate that an ad is available in response to a request for an ad (by
         * calling {@link #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 #isReady()} method.</p>
         *
         * @param ad
         */
        void onAdReceived(InMobiInterstitial inMobiInterstitial);
        /**
         * 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
         */
        void onAdLoadSucceeded(InMobiInterstitial inMobiInterstitial);
        /**
         * Called to indicate that rewards have been unlocked.
         *
         * @param ad
         * @param rewards
         */
        void onAdRewardActionCompleted(InMobiInterstitial inMobiInterstitial, Map<Object, Object> rewards);
        /**
         * Called to indicate that a request to show an ad (by calling {@link #show()} failed.
         * You should call {@link #load()} to request for a fresh ad.
         * @param ad
         */
        void onAdDisplayFailed(InMobiInterstitial inMobiInterstitial);
        /**
         * Called to indicate that the ad will be launching a fullscreen overlay.
         *
         * @param ad
         */
        void onAdWillDisplay(InMobiInterstitial inMobiInterstitial);
        /**
         * Called to indicate that the fullscreen overlay is now the topmost screen.
         *
         * @param ad
         */
        void onAdDisplayed(InMobiInterstitial inMobiInterstitial);
        /**
         * Called to indicate that an ad interaction was observed.
         *
         * @param ad
         * @param params
         */
        void onAdInteraction(InMobiInterstitial inMobiInterstitial, Map<Object, Object> params);
        /**
         * Called to indicate that the fullscreen overlay opened by the ad was closed.
         *
         * @param ad
         */
        void onAdDismissed(InMobiInterstitial inMobiInterstitial);
        /**
         * Called to indicate that the user may leave the application on account
         * of interacting with the ad.
         *
         * @param ad
         */
        void onUserLeftApplication(InMobiInterstitial inMobiInterstitial);
    }
	

Loading an Interstitial Ad

To request for an 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 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 an Interstitial 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.

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

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

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 interstitial 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 Interstitial 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 Interstitial Ads

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

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

In the Activity you are trying to monetize, you can then get an instance of this ad unit by calling the getFullscreenAd() 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 ad to be displayed by calling show() on the ad unit.