Feb 12, 2017
A complete guide to MoPub native ads mediation on Android (Part 1)
Writing custom native ad adapters, the 9GAG way
(Two months after this article is published, MoPub has released adapters for Facebook, Flurry and AdMob. You are encouraged to use the official ones.)
This article shows you how to create custom adapters for MoPub native ads mediation:
- Part 1: The basics of MoPub SDK integration
- Part 2: Adapters for Facebook, Flurry and AppLovin
- Part 3: Adapter for AdMob and common problems
All snippets shown in this article are available on my GitHub. It is an Android library ready for most use cases. You can take my library and start getting working ads right away.
Introduction
At 9GAG we aim to serve our users the most entertaining contents, free of charge. Showing ads on 9GAG Android app is a way to monetize (and survive). Native ads, as you may have guessed, look the same as the real contents and therefore, improve the revenue potential.
MoPub is an ad mediation platform which provides its own ads as well as its ad partners. You will need to provide your adapter classes to serve ads from MoPub mediated ad networks. MoPub officially offers you a few adapters, mostly for banner and interstitial ads though. They do offer an adapter for Facebook Audience Network native ads, which proves to be useful as a starting point for creating your own adapters for other ad networks.
A few ad networks, such as Flurry, also offer custom adapters for MoPub. Some ad networks, on the other hand, such as Google, make this game much more difficult to play. I know how hard it is to find these adapters on the Internet and, most importantly, make them work together because of the lack of official documentation. I know it because I did it myself and rolled out my custom implementation in our 9GAG Android app.
The basics
Before we proceed, you will need a registered account on MoPub. Please create here if you haven’t got one. Follow their official documentation to set up your application, ad units, orders, marketplace, etc., using MoPub Administrator Console.
MoPub SDK setup
You can find MoPub’s official wiki on how to setup their SDK. But you don’t need everything they mentioned if you are going to integrate native ads only.
In your application project (or root project if you prefer) build.gradle, make sure you have jcenter repository added:
Add MoPub SDK dependency to your application project build.gradle:
Note: MoPub SDK 4.12.0 supports Android API 16 or later. If you need to support API 11 or later, use 4.11.0 instead.
Add the following permission to your application AndroidManifest.xml:
INTERNET is a required permission for all ad networks, of course. You will also need ACCESS_NETWORK_STATE and WRITE_EXTERNAL_STORAGE if you want to mediate ads from Facebook, Flurry and AppLovin, as described in Part 2 of this article.
Add the following activities to the same AndroidManifest.xml file:
MoPubActivity and MoPubBrowser are required for MoPub SDK integration. If you want to integrate Facebook, Flurry and AppLovin, you also need to add the corresponding activities as illustrated above.
Native ad view layout design
A typical 9GAG post looks something like this:
The native ad view layout design should look almost the same as a 9GAG post. I said “almost” because sometimes it is impossible to look exactly the same. A native ad that contains elements that do not appear in a post, such as the ad description text, the privacy information icon, etc., would make it a bit different but that’s okay in our case.
The complete view layout XML file can be found here. Yours must contains view elements such as the ad title TextView, ad description TextView, main image ImageView, call-to-action TextView, etc. It is your choice to decide what view elements to be shown.
MoPub SDK initialization
Assuming that your native ad view layout file is view_native_ad.xml, this is how you initialize MoPub SDK:
You need a Context to initialize MoPub SDK. An Activity Context will do. You also need the ID of the ad unit you have created on MoPub Administrator Console in the steps mentioned above. I use moPubNativeNetworkListener to listen for callbacks after requesting native ads in later steps.
MoPub SDK offers a renderer to help you render native ads of any ad networks if you specify a ViewBinder to it. The ViewBinder binds the view layout you have designed in the previous step, view_native_ad.xml, with the view ID specified. It will use findViewById to grab your views and automatically set text or image to your views.
Request native ads
You can make native ad requests by using the same MoPubNative instance you have initialized before. There are many types of information you can request, but here I only need the title text, body text, main image and call-to-action text. Requesting less information means a faster response and processing time. So don’t request unnecessary information from MoPub server.
Handling native ad request response
If MoPub server finds a suitable native ad that fulfill your request, you will need some further processing before showing it.
setMoPubNativeEventListener registers 2 callbacks, onImpression and onClick. onImpression is called when the ad is rendered and visible to the user. onClick is called when the user taps on the ad. You are not required to register the callbacks because the impression and click events are already handled by MoPub SDK. But if you want to, say, track impressions and clicks for your own purpose, you can do it in these callbacks.
Passing the view inflated using the view layout designed in the previous steps, native_ad_view.xml, to renderAdView will let MoPub SDK render all the native ad fields to your view automatically. You don’t need to call setText or setImageBitmap yourself.
The final step before displaying the ad view is to call prepare. It is for registering impression and click tracking for your ad view. Without it, it is useless to display the ad because you won’t get any revenue without the ad server knowing your ad click rate.
Now you should see your native ad if MoPub responses one to you. For any reason you cannot see it, do check the error code inside onNativeFail callback.
Re-use native ad view for multiple ads
If you need to display another native ads using the same view instance, you must call NativeAd.clear(view) before calling NativeAd.renderAdView(view) again. So you definitely need this if you want to display ads in a RecyclerView.
Clean up
When you are done with the native ad, such as closing an Activity or quitting your application, you must call destroy to clean up those resources used by MoPub SDK. Otherwise you may experience memory leak. You can do it in your Activity’s onDestroy or your view container’s onDetachedFromWindow method, whatever is most suitable for your case.
You need to destroy both the NativeAd instance you received in onNativeLoad callback, and the MoPubNative instance you have initialized in the above step.
What’s next?
Now you have got native ads serving from MoPub successfully. You are ready to mediate other ad networks to enhance your ad revenue potential.
