Integrating FeedAds in Android

This guide explains different ways to include FeedAds into your app.
You need to install & initialize the SDK based on the Getting Started guide before the following methods will work.

Basics

How you integrate FeedAds into your app, is completely up to you.
There is just one important thing to remember:

There must be only one FeedAdView instance in the view hierarchy of an activity.
If you include multiple views at a time, it will cause unexpected behavior.

Quick Integration

This will take you about 5 to 15 minutes, depending on the complexity of your layout.

By default, FeedAds start loading and displaying as soon as a FeedAdView becomes visible in your layout. All you need to do, is to include it in your layout.

<com.feedad.android.FeedAdView
    android:id="@+id/texture_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:feedadPlacementId="your-placement-id"
    />

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

Ads within lists

FeedAds are meant to be displayed within scrollable content. If your layout is built using RecyclerView or other list views that support the display of multiple view types you can just add FeedAdView as another view type. Depending on the size of your content views and the screen size you should make sure that there will be only one FeedAdView visible at any time.

Check the sizing behavior to learn how the view is measured.

Advanced Integration

If you want to make sure that an ad can be displayed before integrating a view into your layout, please follow this guide. Depending on the complexity of your layouts and the amount of activities of your app, this might take you about 30 minutes per activity.

1. Listen for Ad Loaded Event

Create a private class MyFeedAdListener implementing FeedAdListener in your activity:

public class MyActivity extends Activity {

    private FeedAdListener feedAdListener = new MyFeedAdListener();

    /* ... */

    private class MyFeedAdListener implements FeedAdListener {

        @Override
        public void onAdLoaded(String placementId) {

        }

        @Override
        public void onTagComplete(String placementId) {

        }

        @Override
        public void onPlacementComplete(String placementId) {

        }

        @Override
        public void onOpened(String placementId) {

        }

        @Override
        public void onError(String placementId, FeedAdError error) {

        }
    }
}

2. Register the Listener

In your activity, extend the following methods:

public class MyActivity extends Activity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        FeedAd.addListener(feedAdListener);
    }

    @Override
    protected void onDestroy() {
        FeedAd.removeListener(feedAdListener);
        super.onDestroy();
    }
}

3. Create the Ad View

Create a new instance of FeedAdView inside the onAdLoaded method of the listener and add it to your view hierarchy:

@Override
public void onAdLoaded(String placementId) {
    FeedAdView adView = new FeedAdView(MyActivity.this, placementId);
    //add view to content hierarchy
}

4. Request an Ad

Manually request a placement:

public class MyActivity extends Activity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        FeedAd.addListener(feedAdListener);
        //manually request a new ad if there is none running for the placement
        if (!FeedAd.isActive(yourPlacementId) && !FeedAd.isRequesting(yourPlacementId)) {
            FeedAd.requestAd(yourPlacementId);
        }
    }

    /* ... */
}

A manual ad request via FeedAd.requestAd(...) always starts a new request and stops the currently playing ad, regardless if the requested Placement ID is of the same Placement Group.

Finished

Once the view created in step 3 becomes visible, it will start playing the ad.

Continuous Ad Playback

FeedAds support continuous playback across screen changes, as described in FeedAd Behavior.

To benefit from this behavior for your app, make sure that your placements are linked to the same placement group and follow the integration instructions above for each of your screens.

Passing ads between screens, is then handled by the FeedAd SDK.

FeedAdView Sizing Behavior

The FeedAdView size is based on its layout_width and layout_height attributes depending on the aspect ratio of the current ad. If no ad is playing, the fallback aspect ratio is 16:9.

Width	Height	Resulting size
`match_parent`	`match_parent`	Width and height of parent element. Content video is centered and scaled to fit closest side.
`match_parent`	`wrap_content`	Width of parent element. Height is calculated based on aspect ratio of content video.
`wrap_content`	`match_parent`	Height of parent element. Width is calculated based on aspect ratio of content video.
`wrap_content`	`wrap_content`	Width and height of content video size.
`specific_dp`	`specific_dp`	Width and height as specified. Content video is centered and scaled to fit closest side.

Using FeedAds as Part of an Ad Mediation Waterfall

FeedAds have been designed with ad mediation waterfalls in mind.

We have implemented and tested FeedAd integration in major mediation networks. Read the mediation documentation to learn more about supported networks or take a look into our example app.

FeedAd will not automatically request more ads under the following conditions:

There is no fill for the placement.
All ads of a placement were successfully played.
An error occurred while playing an ad.

Implement the FeedAdListener to get notified when one of those events occurs to continue your mediation:

class MyFeedAdListener implements FeedAdListener {

    /* ... */

    @Override
    public void onPlacementComplete(String placementId) {
        // TODO: remove all FeedAdViews
        // TODO: unregister all FeedAdListeners
    }

    @Override
    public void onError(String placementId, FeedAdError error) {
        boolean isNoFill = error.getErrorCode() == FeedAdErrorCode.NO_FILL;
        // TODO: remove all FeedAdViews
        // TODO: unregister all FeedAdListeners
    }
}

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 a manual ad request:

FeedAd.requestAd(yourPlacementId, requestOptions);