Ad Placer Integration of Native Ads - MoPub-Solutions-Eng/mopub.wiki.android.native.betasite GitHub Wiki

The Ad Placer approach is the easiest way for publisher to integrate native ads in an in-feed layout in an app. With this integration, the SDK automatically handles ad caching, ad requests, ad expiring, and metrics tracking so you can focus on how, when, and where to display ads.

The MoPub SDK provides a class, MoPubAdAdapter, that wraps your existing Adapter subclass to insert ads into a ListView, GridView, or other feed-based view that uses an implementation of Adapter (including CursorAdapter).

For more details on other supported integration methods, please check out the Native Ad Integration Types Overview.

Prerequisite

Before integrating native ads, follow the steps in our Android Getting Started Guide to create a MoPub account & integrate the MoPub SDK into your project. Additionally, check the Best Practices for guidelines on how native ads should be displayed in your app.

Requesting and Rendering Native Ads

Ad Placer integration takes five easy steps:

Create an XML layout for your native ads
Define where ads should be placed within your feed
Create a MoPubAdAdapter to wrap your existing Adapter subclass
Pass in required and optional parameters to Load ads
Destroy the MoPubAdAdapter in activity life cycle

1. Set up your Native Ad Layout

Start by defining an XML layout for how an ad should look inside your app’s feed. This example layout contains two TextViews for a title and additional text, plus three ImageViews for an icon image, a main image, and a Privacy Information icon image. Choose the assets from the ad that will make it fit in most seamlessly in your app’s feed.

Your native ad must display the privacy information icon. The MoPub SDK automatically handles tap events on the privacy information icon. The recommended size for this is 40 dp with a 10dp padding on all sides (so the icon display area is only 20dp by 20dp, but the click area is a bit larger). This icon links to an important privacy notice, and is required for you to use MoPub's native ads.

For example: res/layout/native_ad_layout.xml

<RelativeLayout ...>
  <ImageView android:id="@+id/native_ad_main_image"
    ... />
  <ImageView android:id="@+id/native_ad_icon_image"
    ... />
  <TextView android:id="@+id/native_ad_title"
    ... />
  <TextView android:id="@+id/native_ad_text"
    ... />
  <ImageView android:id="@+id/native_ad_privacy_information_icon_image"
    android:layout_width="40dp"
    android:layout_height="40dp"
    android:padding="10dp"
    ... />
</RelativeLayout>

IMPORTANT You should set the background property on your ImageViews to null in order to handle PNG transparency gracefully, e.g.

<ImageView
 android:background="@null"
 ... />

Next, create a ViewBinder object specifying the binding between your layout XML and the ad’s content.

ViewBinder viewBinder = new ViewBinder.Builder(R.layout.native_ad_layout)
    .mainImageId(R.id.native_ad_main_image)
    .iconImageId(R.id.native_ad_icon_image)
    .titleId(R.id.native_ad_title)
    .textId(R.id.native_ad_text)
    .privacyInformationIconImageId(R.id.native_ad_privacy_information_icon_image)
    .build();

Note: If you’re displaying direct-sold native ads, you may have additional subviews for text or images available. Extra fields may be added using:

new ViewBinder.Builder().addExtras(Map<String, Integer> resIds)

new ViewBinder.Builder().addExtra(String key, int resId)

Example: Let's say that in the MoPub Web UI you've added the custom fields "sponsoredtext" and "sponsoredimage":

"sponsoredtext" : "Sponsored",
  "sponsoredimage" : "http://www.mopub.com/sponsored.jpg"

You would add these sponsored fields to your XML layout, then bind them to the view like this:

ViewBinder viewBinder = new ViewBinder.Builder(R.layout.native_ad_layout)
  .mainImageId(R.id.native_ad_main_image)
  .iconImageId(R.id.native_ad_icon_image)
  .titleId(R.id.native_ad_title)
  .textId(R.id.native_ad_text)
  .privacyInformationIconImageId(R.id.native_ad_privacy_information_icon_image)
  // Your custom fields are bound with the addExtra() call.
  .addExtra("sponsoredtext", R.id.sponsored_text)
  .addExtra("sponsoredimage", R.id.sponsored_image)
  .build();

Note: If you are adding an image to extras, the key must end with "image" The MoPubAdAdapter uses a class called MoPubStaticNativeAdRenderer to load ads within your feed. Create an instance with the ViewBinder:

MoPubStaticNativeAdRenderer adRenderer = new MoPubStaticNativeAdRenderer(viewBinder);

2. Place Ads in your Feed

Next, you’ll need to define where in your feed you’d like ads to appear using the MoPubNativeAdPositioning class. It provides sever-side and client-side positioning approaches:

Server-side Positioning (Recommended)

You can specify positions in the feed where you always want to display ads and set the interval at which ads should appear in the MoPub native ad unit settings page. Firstly, you have to update your settings in the UI. In the settings below, your ads will appear in positions 1, 4, and 7 (where 0 is the position of the first ad). After position 7, your ads will appear every 5 positions.

Secondly, you have to set up the MoPubNativeAdPositioning.MoPubServerPositioning object:

MoPubNativeAdPositioning.MoPubServerPositioning adPositioning =
      MoPubNativeAdPositioning.serverPositioning();

Client-side Positioning

We strongly recommend using server side positioning. However, the SDK does support setting positioning directly in the client. In this case, the position setting on ad unit page will be ignored. To set up client positioning:

Create an MoPubClientPositioning object

MoPubClientPositioning adPositioning = MoPubNativeAdPositioning.clientPositioning();

If you want ads to appear at certain fixed positions within your feed, use addFixedPosition

adPositioning.addFixedPosition(1);
adPositioning.addFixedPosition(3);
adPositioning.addFixedPosition(7);

Use enableRepeatingPositions to instruct adapter insert ads at the specified interval as more items are loaded into your feed

positioning.enableRepeatingPositions(5);

3. Create a MoPubAdAdapter

This step is for ad placed in ListView or GridView. For RecyclerView, please refer to Create a MoPubRecyclerAdapter instead.

The MoPubAdAdapter class places the ads according to the rules set in the MoPub UI and also handles ad caching. Create an instance of MoPubAdAdapter using the current Context, your existing Adapter subclass, and the MoPubNativeAdPositioning object you created in the previous step.

mAdAdapter = new MoPubAdAdapter(this, adapter, adPositioning);

Next, register the ad renderer (created from your ViewBinder in step 1) so that the adapter renders your ads according to the layout you created:

   mAdAdapter.registerAdRenderer(adRenderer);

Finally, set your old view’s adapter to be the new MoPubAdAdapter instance:

   myListView.setAdapter(mAdAdapter);

4. Begin Loading Ads

The MoPubAdAdapter is now ready to begin loading ads according to your specifications. To improve the relevance of the ads that get shown in your app, you can choose to pass up location or additional keyword data (see the data passing guide). You can also specify exactly which assets you want, to help conserve bandwidth.

final EnumSet<NativeAdAsset> desiredAssets = EnumSet.of(
                      NativeAdAsset.TITLE,
                      NativeAdAsset.TEXT,
                      // Don't pull the ICON_IMAGE
                      // NativeAdAsset.ICON_IMAGE,
                      NativeAdAsset.MAIN_IMAGE,
                      NativeAdAsset.CALL_TO_ACTION_TEXT);

Then, create a new RequestParameters object using the Builder:

 mRequestParameters = new RequestParameters.Builder()
                      .location(location)
                      .keywords(keywords)
                      .desiredAssets(desiredAssets)
                      .build();

You're now ready to load ads, using the request parameters and the ad unit ID you created on the MoPub dashboard:

mAdAdapter.loadAds(AD_UNIT_ID, mRequestParameters);

To test your implementation, you can also use the following test ad unit ID: 11a17b188668469fb0412708c3d16813
It will always return a static MoPub native creative.

To load all-new ads into the stream you can call MoPubAdAdapter.refreshAds().

5. Destroy the MoPubAdAdapter

The MoPubAdAdapter must be destroyed when its hosting Activity is destroyed. You should destroy the adapter in the life-cycle method that is the opposite of the method used to create the adapter. If you created the adapter in Activity.onCreate(), you should destroy it in Activity.onDestroy(). If you created the adapter in Activity.onResume(), you should destroy it in Activity.onPause(). Sample code:

@Override
protected void onDestroy() {
    mAdAdapter.destroy();
    super.onDestroy();
}

Important Note: For information on using Native Ads outside of an Adapter or without using the StreamAdPlacer, see Manual Integration of Native Ads.

Native Video

Native video is currently in private beta. For more information about using MoPub for native video ads, please contact your account team or [email protected] to learn more.

Integrating MoPub Native Video ads into your app is as easy as integrating standard "static" native ads.

To add Native Video ads to an existing app with Native Ads you'll need to:

Create a XML layout for your video ads.
Create and add a video ad renderer to your app.
Enable video ads on your ad unit in the MoPub Web UI.

Prerequisites

This guide assumes that you've already integrated Native Ads into your app. If you haven't, first follow the Native Ads Integration Guide

Read the best practices article for guidelines on how native ads can be displayed in your app.

Additional Steps for Native Video Ads

1. Create a layout for Native Video Ads.

For example:
res/layout/native_ad_layout.xml

<RelativeLayout ...>    
  <com.mopub.nativeads.MediaLayout android:id="@+id/native_ad_media_layout"
    ... />  
  <ImageView android:id="@+id/native_ad_icon_image"  
    ... />  
  <TextView android:id="@+id/native_ad_title"  
    ... />  
  <TextView android:id="@+id/native_ad_text"  
    ... />
  <ImageView android:id="@+id/native_ad_daa_icon_image"
    android:layout_width="40dp"
    android:layout_height="40dp"
    android:padding="10dp"
    ... />
</RelativeLayout>

MediaLayout is a custom View provided by MoPub that handles displaying video. You are required to use it for Native Video Ads. We strongly recommend setting your MediaLayout to a fixed width & height based on device size and resolution. The MediaLayout should be designed with a 16:9 aspect ratio.

2. Add Support for Video Rendering to your Apps

Create an ViewBinder for your video layout.

MediaViewBinder videoAdBinder = new MediaViewBinder.Builder()
  .mediaLayoutId(R.id.video_ad_media_layout)
  .iconImageId(R.id.video_ad_icon_image)
  .titleId(R.id.video_ad_title)
  .textId(R.id.video_ad_text)
  .daaIconImageId(R.id.video_ad_daa_icon_image)
  .build();

Add the view binder to your Adapter or StreamAdPlacer

ViewBinder staticAdBinder = new ViewBinder.Builder()
  .mainImageId(R.id.native_ad_main_image)
  .iconImageId(R.id.native_ad_icon_image)
  .titleId(R.id.native_ad_title)
  .textId(R.id.native_ad_text)
  .daaIconImageId(R.id.native_ad_daa_icon_image)
  .build();

MoPubAdAdapter myAdAdapter = new MoPubAdAdapter(context, myContentAdapter, new MoPubServerPositioning());

// You should still register a renderer for static native ads as well.
myAdAdapter.registerAdRenderer(new MoPubStaticNativeAdRenderer(staticAdBinder));
myAdAdapter.registerAdRenderer(new MoPubVideoNativeAdRenderer(videoAdBinder));


myListView.setAdapter(myAdAdapter);

3. Enable Video Ads in the Web UI.

Open your ad unit in the MoPub Web UI and select "Edit Ad Unit" in the top-right corner.

In the form that appears, check the box labeled "Allow video ads for this ad unit."

More Resources

Android Getting Started Guide
Best Practices
Code Samples
FAQ
Manual Integration
Custom Manual Integration
Mediation