Native Ads (Integrate Using AdPlacer)

Native ads let you monetize your app in a way that’s consistent with its existing design. The MoPub SDK gives you access to an ad’s individual assets so you can design the ad layout to be consistent with the look and feel of your app. The SDK automatically handles image caching and metrics tracking so you can focus on how, when, and where to display ads.

Prerequisites

Before integrating native ads into your app:

  1. Create an account on MoPub and integrate the MoPub SDK into your project.
  2. Read our Best Practices article for guidelines about displaying native ads in your app.

Integrate Native Ads Using Ad Placer via MoPubAdAdapter

This and the MoPubRecyclerAdapter option both involve using the Ad Placer. They offer the same advantages, but different specifics.

This option involves using the MoPubStreamAdPlacer to facilitate loading native ads into an app’s content stream. The advantage of using the Ad Placer is that it lets the MoPub SDK request new ads automatically when necessary, insert them into the stream of content, and handle impression tracking and clicks. By default, three native ads are requested and cached initially, and the SDK requests one at a time as the user scrolls through the feed. Each ad’s expiration timer starts once the ad is loaded or cached. After four hours, the SDK marks these ads as ready for cleanup by the OS.

You insert native ads into a ListView or GridView. This option uses the MoPubStreamAdPlacer class, and a MoPubAdAdapter that wraps your existing adapter subclasses to insert ads into a ListView. The MoPub SDK provides the class MoPubAdAdapter, which wraps your existing Adapter subclass to insert ads into a ListView, GridView, or other view that uses an implementation of Adapter (including CursorAdapter).

This option consists of these high-level steps:

  1. Set up your native ad layout.
  2. Place ads in your feed.
  3. Create a MoPubAdAdapter to wrap your existing Adapter subclass and begin loading ads.
  4. Begin loading ads.
  5. Destroy the MoPubAdAdapter.

Important: Please do not use publisher-provided overlays (such as close buttons) that are located with the ad placement and that subsequently cover the ad creative. Doing so is against MoPub Policy. If you have questions, please reach out to your account team or support@mopub.com for additional assistance.

Step 1. Set Up Your Native Ad Layout

  1. Start by defining an XML layout for how an ad should look inside your app’s feed. Choose the assets from the ad that will make it fit most seamlessly in your app’s feed.

     <RelativeLayout
         xmlns:android="http://schemas.android.com/apk/res/android"
         android:id="@+id/example_view"
         android:layout_width="match_parent"
         android:layout_height="wrap_content">
    
         <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" />
         <TextView
             android:id="@+id/native_sponsored_text_view" />
     </RelativeLayout>
    
    • Your ad must contain the Privacy Information icon. The recommended size for this is 40 dp with a 10 dp padding on all sides (so the icon display area is only 20 dp x 20 dp, but the click area is a little larger). This icon links to an important privacy notice, and is required for you to use MoPub’s native ads. The MoPub SDK automatically handles tap events on the privacy information icon.
  2. Create a ViewBinder object specifying the binding between your layout XML and the ad’s content. If you use mediation, specific ad networks might require specific ViewBinder bindings for additional assets.

     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)
         .sponsoredTextId(R.id.native_sponsored_text_view)
         .addExtra("sponsoredimage", R.id.sponsored_image) // If you display direct-sold native ads, you can add additional subviews for custom assets
         .build();
    
    • If you add an image via addExtra(), the key must end with image.

    • Starting with MoPub SDK v5.11.0, the Advertiser name is available in the sponsored text field. We recommend using “Sponsored by” or localized versions when this string is returned. Example:

      <string name="com_mopub_nativeads_sponsored_by">Sponsored by %s</string>
      
  3. Create an instance of MoPubStaticNativeAdRenderer to load ads:

     MoPubStaticNativeAdRenderer adRenderer = new MoPubStaticNativeAdRenderer(viewBinder);
    

Step 2. Place Ads in Your Feed

Next, you must define where in your feed you want ads to appear, using the MoPubNativeAdPositioning class to balance ads with your content. We provide server-side and client-side positioning approaches, in which you can specify starting positions in the feed where you always want to display ads, and set the interval for how often ads should appear.

Use server-side positioning to achieve the optimal balance of ads for your app without changing your app code or releasing a new version. To set up server-side positioning:

  1. Update your native ad unit settings page. In the example below, your ads will appear in positions 1, 4, and 7 (where 0 is the position of the first row in the feed). After position 7, your ads will appear every 5 positions.

    Server-Side Positioning

  2. After updating your settings in the UI, set up the MoPubNativeAdPositioning.MoPubServerPositioning object:

     MoPubNativeAdPositioning.MoPubServerPositioning adPositioning = MoPubNativeAdPositioning.serverPositioning();
    

Option B. Client-Side Positioning

The SDK supports setting positioning client-side. In this case, the position setting on the ad unit screen of the Publisher UI is ignored.

  1. Create an MoPubClientPositioning object:

     MoPubClientPositioning adPositioning = MoPubNativeAdPositioning.clientPositioning();
    
  2. If you want ads to appear at certain fixed positions within your feed, use addFixedPosition:

     adPositioning.addFixedPosition(1);
     adPositioning.addFixedPosition(3);
     adPositioning.addFixedPosition(7);
    
  3. Use enableRepeatingPositions to insert ads at a fixed interval:

     positioning.enableRepeatingPositions(5);
    

Step 3. Create a MoPubAdAdapter

The MoPubAdAdapter class places the ads according to the rules set in the MoPub UI and also handles ad caching.

  1. 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);
    
  2. 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);
    
  3. Set your old view’s adapter to be the new MoPubAdAdapter instance:

     myListView.setAdapter(mAdAdapter);
    

Step 4. Begin Loading Ads

  1. The MoPubAdAdapter is now ready to begin loading ads according to your specifications. To improve the relevance of the ads shown in your app, you can choose to pass location or additional keyword data (refer to our data passing article). You can also specify exactly which assets you want, to help conserve bandwidth, like so:

     final EnumSet<NativeAdAsset> desiredAssets = EnumSet.of(
                           NativeAdAsset.TITLE,
                           NativeAdAsset.TEXT,
                           NativeAdAsset.ICON_IMAGE,
                           NativeAdAsset.MAIN_IMAGE,
                           NativeAdAsset.CALL_TO_ACTION_TEXT,
                           NativeAdAsset.SPONSORED);
    
  2. Create a new RequestParameters object using the Builder:

     mRequestParameters = new RequestParameters.Builder()
                         .keywords(keywords)
                         .desiredAssets(desiredAssets)
                         .build();
    
  3. 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 force loading all-new ads into the stream you can call:

     mAdAdapter.refreshAds();
    

Step 5. Destroy the MoPubAdAdapter

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

Best Practice: Avoid Excessive Ad Requests

Making requests for ads that are never displayed to the user consumes unnecessary resources and may negatively impact your revenue. Therefore, try to request ads only when they are likely to be displayed. In particular, avoid caching large quantities of ads for long periods of time.

For example, when a user initially navigates to a ListView with many rows, avoid requesting ads that will be displayed near the bottom of the ListView (that is, far below the fold). Instead, wait for the user to begin scrolling through the feed before making additional ad requests.

Last updated October 06, 2020

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2020 MoPub (a division of Twitter, Inc.)