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.

Updated Interstitial Integration

The interstitial ad integration received a breaking code change update in FeedAd version 1.4.3.
If you want to integrate interstitial ads and are using an older version of FeedAd you should update the SDK. Do not worry about unresolved class names after the update. Not much has changed. Read through this guide, and you will see how the code has to be refactored.

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();
            interstitialAd = null;
        }
    }
}

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 MyInterstitialAdRequestListener());
        }
    }

    /**
    * Created when requesting an interstitial ad
    */
    private class MyInterstitialAdRequestListener implements InterstitialAdRequestListener {

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

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

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 presenter. Call the show() method on this presenter when you want the interstitial to be shown. You will need to supply a listener implementation to receive callbacks about the ad playback.

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

private class MyInterstitialAdRequestListener implements InterstitialAdRequestListener {

    @Override
    public void onAdLoaded(InterstitialAdPresenter presenter) {
        // specify if the user can cancel the interstitial by pressing the back button
        boolean allowCancellation = false;
        // the ad is ready to be displayed
        presenter.show(requireActivity(), new InterstitialAdPlaybackListener() {

            @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 during ad playback
                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
            }

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

        }, allowCancellation);
    }

    // ... //
}

4. Take action when the Interstitial closes

You'll most likely want to execute some actions once the interstitial ad closes. The InterstitialAdPlaybackListener 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 configure if the user can cancel the ad by setting the second parameter of InterstitialAdPresenter.show(...). If it is true, the user can cancel the ad at any time by pressing the back button. If it is false, presses on the back button will have no effect.
• 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.

Threading

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

---

Advanced Options

Listen for the Click Out Event

The InterstitialAdRequestListener#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.

Ad Request Options

You can create an optional request options object, that you can specify alongside the ad request. This object can contain information about the ad's relation to the content of your ad.

You can specify the following options:

Option	Description
Content URL	A deep-link that opens the screen on which the ad is shown from an external origin.
Placement Context	The position of the ad in relation to the main content of the screen. For example, if it is a pre-roll ad shown before the use can access the content.

Example:

AdRequestOptions requestOptions = new AdRequestOptions.Builder()
    .setContentUrl("deeplink//to/your/content")
    .setPlacementContext(PlacementContext.PRE_ROLL)
    .create();

You can pass those options as a second parameter to the interstitial ad request:

interstitialAd = FeedAd.requestInterstitialAd(this, "your-placement-id", new MyInterstitialAdRequestListener(), requestOptions);

---

Preloading Interstitial Ads

The context argument given to FeedAd.requestInterstitialAd(context, ...) holds a reference to the application-context. This means, that you can call this method from any component that has access to the any context (Fragment, Activity, Service, custom Singletons).
Only when calling InterstitialAdPresenter#show(activity, ...) a reference to an activity is created. This reference will be held until the interstitial is closed.
This way you can request an interstitial at any time, and keep the InterstitialAdPresenter across activities, until the interstitial ad should be shown.

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.InterstitialAdPresenter;
import com.feedad.android.InterstitialAdRequestListener;
import com.feedad.android.InterstitialAdPlaybackListener;

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();
            interstitialAd = null;
        }
    }

    /**
     * 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 MyInterstitialAdRequestListener());
        }
    }

    /**
     * Created when requesting an interstitial ad
     */
    private class MyInterstitialAdRequestListener implements InterstitialAdRequestListener {

        @Override
        public void onAdLoaded(InterstitialAdPresenter presenter) {
            // specify if the user can cancel the interstitial by pressing the back button
            boolean allowCancellation = false;
            // the ad is ready to be displayed
            presenter.show(requireActivity(), new InterstitialAdPlaybackListener() {

                @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 during ad playback
                    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
                }

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

            }, allowCancellation);
        }

        @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();
        }
    }
}