Native Ads (RecyclerView)

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 and MoPubRecyclerAdapter

Like the MoPubAdAdapter option, this option involves using the MoPubStreamAdPlacer to facilitate loading native ads into an app’s content stream; for example, a scrolling list. 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.

With this option, you insert native ads into a RecyclerView. This option uses the MoPubStreamAdPlacer class, and a MoPubRecyclerAdapter that wraps your existing adapter subclasses to insert ads into a RecyclerView.

The MoPub SDK includes a RecyclerView.Adapter class called MoPubRecyclerAdapter. Using this class, you can insert ads automatically into a RecyclerView, as you do with a ListView or GridView using MoPubAdAdapter.

The SDK automatically requests new ads when needed, inserts them into the stream of content, and handles impression tracking and clicks. You can add and remove content from the RecyclerView.

Creating a MoPubRecyclerAdapter

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState)
    // Set up your own recycler adapter
    // Set up your RecyclerView

    // Pass the recycler Adapter your original adapter.
    MoPubRecyclerAdapter myMoPubAdapter = new MoPubRecyclerAdapter(context, YOUR_OWN_ADAPTER);
    // Create an ad renderer and view binder that describe your native ad layout.
    ViewBinder myViewBinder = new ViewBinder.Builder(R.layout.my_ad_layout)
            .titleId(R.id.my_ad_title)
            .textId(R.id.my_ad_text)
            .mainImageId(R.id.my_ad_image)
            .iconImageId(R.id.my_ad_icon)
            .callToActionId(R.id.my_call_to_action)
            .privacyInformationIconImageId(R.id.my_ad_privacy_information_icon)
            .build());

    MoPubStaticNativeAdRenderer myRenderer = new MoPubStaticNativeAdRenderer(myViewBinder);

    myMoPubAdapter.registerAdRenderer(myRenderer);

    // Set up the RecyclerView and start loading ads
    recyclerView.setAdapter(myMoPubAdapter);
    myMoPubAdapter.loadAds("YOUR_AD_UNIT_ID");
}

@Override
public void onDestroy() {
    myMoPubAdapter.destroy();
    super.onDestroy();
}

If you register any data observers on your original adapter, instead register them on the MoPubRecyclerAdapter so that they receive messages with the adjusted position of content items. If you do not do this, the positions you receive for insertion and removal messages may be inaccurate. Be sure to check isAd(position) and use MoPubRecyclerAdapter.getOriginalPosition() if you need the position of the item in your local adapter.

Manipulating RecyclerView.Adapter Content

Keeping Ads in the Same Relative Position

When adding or removing content items from your RecyclerView.Adapter, the MoPub SDK automatically displays and hides ads as the length of the content stream changes. When adding or removing from the end, ads may appear or be hidden. When removing or inserting ads at the beginning or middle of the stream, the SDK also adjusts the ads so that they remain in the same position relative to the content in the stream.

All content manipulation happens through an AdapterDataObserver that the MoPub SDK registers on your original adapter. When adding or deleting items from your stream, call these methods from your adapter:

notifyItemInserted(position);
notifyItemRemoved(position);
notifyItemsInserted(position, count);
notifyItemsRemoved(position, count);

You must do this so that the RecyclerView is notified to schedule a layout.

If you instead call notifyDataSetChanged when changing your content, the ads’ position is not adjusted along with your content. We do not recommend this.

Keeping Ads in the Same Absolute Position

If you want MoPub to keep its ads in the same absolute position when inserting or deleting items, simply call notifyDataSetChanged() from your adapter, instead of notifyItemsInserted or notifyItemsRemoved.

Advanced: Setting the ContentChangeStrategy

If you require more fine-grained control of insertion and deletion behavior with a MoPubRecyclerAdapter, you can set the ContentChangeStrategy on the adapter. The default strategy, INSERT_AT_END, behaves as described in Manipulating RecyclerView.Adapter Content.

To always keep ads in the same position, you can set the strategy to KEEP_ADS_FIXED. To always move ad positions when content is added or deleted, set the strategy to MOVE_ADS_WITH_CONTENT. You can change the strategy at any time if you require more complex ad position manipulation.

void insertOneRowAtTheEndOnTap() {
  myAdapter.setContentChangeStrategy(KEEP_ADS_FIXED);

  View actionView = // Create the view.

  // Implement addItemAtEnd to call notifyItemInserted()
  myOriginalAdapter.addItemAtEnd(actionView);

  // When other content is added at the end, ads can be inserted.
  myAdapter.setContentChangeStrategy(INSERT_AT_END);
}

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 July 10, 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.)