Integrating Interstitial Ads in Android

This guide explains how to integrate interstitial ads into your app.
You need to install & initialize the SDK based on the Getting Started guide first before you can use interstitial ads.

Basics

The FeedAd SDK manages the interstitial display logic, leaving the following steps up to you:

  1. Implement the request of an interstitial ad.
  2. Decide when to show the interstitial.
  3. Set what to do after the interstitial has been displayed.

Integration

The integration will take you about 60 minutes.

You can display an interstitial ad from any Activity or Fragment.

The following example shows the integration of an interstitial within an Activity. If you want to display the ad from within a Fragment, you can implement it within your Fragment class in exactly the same way.

1. Prepare your activity

  • Add a field holding a reference to the interstitial ad.
  • Make sure the interstitial ad is released when the Activity is destroyed.
public class MyActivity extends Activity {

    @Nullable private InterstitialAd interstitialAd;

    // ... //

    @Override
    public void onDestroy() {
        super.onDestroy();

        // When the view is destroyed while the Interstitial is loading or shown, it should be canceled.
        // This does nothing when the interstital was already shown.
        if (interstitialAd != null) {
            interstitialAd.cancel();
        }
    }
}

2. Request an Interstitial ad

  • Implement the interstitial listener.
  • Request an interstitial placement.
public class MyActivity extends Activity {

    /**
    * Requests an interstitial ad
    */
    private void requestInterstitialAd() {
        // Check if an ad can be requested
        if (FeedAd.canRequestAd("your-placement-id")) {
            interstitialAd = FeedAd.requestInterstitialAd(this, "your-placement-id", new MyInterstitialAdListener());
        }
    }

    /**
    * Created when requesting an interstitial ad
    */
    private class MyInterstitialAdListener implements InterstitialAdListener {

        @Override
        public void onAdLoaded(InterstitialAdDialog interstitialAdDialog) {
            // the ad is ready to be displayed
        }

        @Override
        public void onSkipped() {
            // the ad was skippable and the user skipped it
        }

        @Override
        public void onPlacementComplete() {
            // the ad completed
        }

        @Override
        public void onError(FeedAdError feedAdError) {
            // there was an error loading the ad or the placement had no fill
        }

        @Override
        public void onCanceled() {
            // the user canceled the ad by pressing the back button
        }

        @Override
        public void onOpened() {
            // the user clicked the ad.
        }
    }
}

Placement ID?

You can choose placement IDs yourself. A placement ID should be named after the ad position inside your product. For example, if you want to display an ad inside a list of news articles, you could name it "ad-news-overview".
A placement ID may consist of lowercase a-z, 0-9, - and _. You do not have to manually create the placement IDs before using them. Just specify them within the code, and they will appear in the FeedAd admin panel after the first request. Learn more about Placement IDs and how they are grouped to play the same Creative

3. Show the Interstitial

Once the requested ad is loaded and ready to be displayed, the onAdLoaded(...) method of the listener is called with the interstitial dialog. Call the show() method on this dialog when you want the interstitial to be shown. You can keep a reference to the dialog as long as the Activity or Fragment that requested it is created.

E.g.: Display the Interstitial as soon as it's loaded:

private class MyInterstitialAdListener implements InterstitialAdListener {

    @Override
    public void onAdLoaded(InterstitialAdDialog dialog) {
        // the ad is ready to be displayed
        dialog.show();
    }

    // ... //
}

4. Take action when the Interstitial closes

You'll most likely want to execute some actions once the interstitial ad closes. The InterstitialAdListener provides four different callbacks indicating that the interstitial is now closed, each one for a different cause of the closing:

Successful Callbacks

Callbacks indicating that the interstitial ad was completed successfully:

  • onPlacementComplete()
    The ad was played until completion.
  • onSkipped():
    The ad was skippable and the user clicked the skip button.

Unsuccessful Callbacks

Callbacks indicating that the ad playback was not completed successfully.

  • onCanceled():
    The ad was either canceled by the user pressing the back button or programmatically by calling the InterstitialAd#cancel() method. You can read more about cancelable Interstitials in the Advanced Options section.
  • onError(FeedAdError feedAdError):
    This method is called when the interstitial ad fails due to an error. It can be called at any time during the request of an interstitial or while it is being displayed. For example, if there is currently no ad available, this callback will be executed after you've called FeedAd.requestInterstitialAd(...) and onAdLoaded(...) will never be called.

All listener callbacks are called on the application's main thread.


Advanced Options

Configure the Dialog

You can change some settings for the interstitial dialog after it has been passed via InterstitialAdListener#onAdLoaded(...) and before calling the show() method on the dialog. The following configuration methods are available:

  • setCancelable(boolean)
    Set if the interstitial is cancelable by pressing the back button (Default: false).
  • setShutterDrawable(Drawable)
    Set the interstitial background (Default: black).
  • setShowLoadingIndicator(boolean)
    Set if the loading indicator should be shown while the ad is loading.

Listen for the Click Out Event

The InterstitialAdListener#onOpened() method is called when the user clicked the interstitial ad and is redirected to the browser. The Interstitial Ad pauses when the user leaves the application and resumes once he returns.
If you want to close the interstitial when the user clicks on it, you can call the InterstitialAd#cancel() method within this callback.


Full Code Example

The complete code of the interstitial integration guide.

package com.feedad.demo;

import android.app.Activity;
import android.os.Bundle;
import android.support.annotation.Nullable;
import android.widget.Toast;

import com.feedad.android.FeedAd;
import com.feedad.android.FeedAdError;
import com.feedad.android.InterstitialAd;
import com.feedad.android.InterstitialAdDialog;
import com.feedad.android.InterstitialAdListener;

public class MyActivity extends Activity {

    @Nullable private InterstitialAd interstitialAd;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // request an interstitial on activity creation
        requestInterstitialAd();
    }

    @Override
    public void onDestroy() {
        super.onDestroy();

        // When the view is destroyed while the interstitial is loading or shown, it should be canceled.
        // This does nothing when the interstital was already shown.
        if (interstitialAd != null) {
            interstitialAd.cancel();
        }
    }

    /**
     * Requests an interstitial ad
     */
    private void requestInterstitialAd() {
        // Check if an ad can be requested
        if (FeedAd.canRequestAd("your-placement-id")) {
            interstitialAd = FeedAd.requestInterstitialAd(this, "your-placement-id", new MyInterstitialAdListener());
        }
    }

    /**
     * Created when requesting an interstitial ad
     */
    private class MyInterstitialAdListener implements InterstitialAdListener {

        @Override
        public void onAdLoaded(InterstitialAdDialog dialog) {
            dialog.setCancelable(true);
            dialog.show();
        }

        @Override
        public void onSkipped() {
            // the ad was skippable and the user skipped it
            Toast.makeText(MyActivity.this, "interstitial skipped by user", Toast.LENGTH_LONG).show();
        }

        @Override
        public void onPlacementComplete() {
            // the ad completed
            Toast.makeText(MyActivity.this, "interstitial completed", Toast.LENGTH_LONG).show();
        }

        @Override
        public void onError(FeedAdError feedAdError) {
            // there was an error loading the ad or the placement had no fill
            Toast.makeText(MyActivity.this, "interstitial failed: " + feedAdError, Toast.LENGTH_LONG).show();
        }

        @Override
        public void onCanceled() {
            // the user canceled the ad by pressing the back button
            Toast.makeText(MyActivity.this, "interstitial canceled", Toast.LENGTH_LONG).show();
        }

        @Override
        public void onOpened() {
            // the user clicked the ad.
            Toast.makeText(MyActivity.this, "interstitial clicked", Toast.LENGTH_LONG).show();
        }
    }
}