Custom Events for Android

Custom events allow you to support custom ad networks not listed on our Supported Mediation Partners page.

Disclaimer: MoPub cautions usage of non-supported network adapters and does not provide testing or technical support for issues arising from usage. Support network adatpers can be found at the link above.

Quick Start for Banners

  1. Create a subclass of CustomEventBanner in the com.mopub.mobileads package of your application.

  2. Override the loadBanner(Context, CustomEventBannerListener, Map<String, Object>, Map<String, String>) method and implement code that requests an ad.

  3. When your ad loads successfully, you must notify MoPub of the event and display your ad by calling the onBannerLoaded(View) method on the CustomEventBannerListener object (passed in loadAd).

  4. Similarly, you must notify the CustomEventBannerListener object when your ad fails to load by calling the onBannerFailed(MoPubErrorCode) method on the listener object. You should pass a suitable MoPubErrorCode constant (see MoPubErrorCode.java).

  5. (Optional) Notify the listener object of other ad lifecycle events via the corresponding methods on CustomEventBannerListener.

    public void onBannerClicked(); public void onBannerImpression() public void onLeaveApplication();

  6. (Optional) Override the onInvalidate() method of CustomEventBanner if your custom event requires any sort of cleanup.

  7. Finally, on the MoPub web interface, create a network with the “Custom SDK Network” type. Place the fully-qualified class name of your custom event (e.g. com.mopub.mobileads.YourCustomEventBanner) in the “Custom Event Class” column.

Once you’ve completed these steps, the MoPub SDK will be able to cause your CustomEventBanner subclass to be instantiated at the proper time while your application is running. You do not need to instantiate any of these subclasses in your application code.

Note: the MoPub SDK will cause a new CustomEventBanner object to be instantiated on every ad call, so you can safely make changes to the custom event object’s internal state between calls.

Quick Start for Interstitials

  1. Create a subclass of CustomEventInterstitial in the com.mopub.mobileads package of your application.

  2. Override the loadInterstitial(Context, CustomEventInterstitialListener, Map<String, Object>, Map<String, String>) method and implement code that requests an interstitial.

  3. Override the showInterstitial() method and implement code that displays your interstitial.

  4. When your ad loads successfully, you must notify MoPub of the event and display your ad by calling the onInterstitialLoaded() method on the CustomEventInterstitialListener object (passed in loadAd).

  5. Similarly, you must notify the CustomEventInterstitialListener object when your ad fails to load by calling the onInterstitialFailed(MoPubErrorCode) method on the listener object.

  6. (Optional) Notify the listener object of other ad lifecycle events via the corresponding methods on CustomEventInterstitialListener.

    public void onInterstitialShown(); public void onInterstitialImpression(); public void onInterstitialDismissed(); public void onInterstitialClicked(); public void onLeaveApplication();

  7. (Optional) Override the onInvalidate() method of CustomEventInterstitial if your custom event requires any sort of cleanup.

  8. Finally, on the MoPub web interface, create a network with the “Custom SDK Network” type. Place the fully-qualified class name of your custom event (e.g. com.mopub.mobileads.YourCustomEventInterstitial) in the “Custom Event Class” column.

Once you’ve completed these steps, the MoPub SDK will be able to cause your CustomEventInterstitial subclass to be instantiated at the proper time while your application is running. You do not need to instantiate any of these subclasses in your application code.

Note: the MoPub SDK will cause a new CustomEventInterstitial object to be instantiated on every ad call, so you can safely make changes to the custom event object’s internal state between calls.

Quick Start for Rewarded Video

1.  Create a subclass of CustomEventRewardedVideo in the com.mopub.mobileads package of your application.

2.  Use checkAndInitializeSdk(Context, Map<String, Object>, Map<String, String>) method to initialize the network SDK

3.  Override the loadWithSdkInitialized(Context, Map<String, Object>, Map<String, String>) method and implement code that requests a rewarded interstitial.

4.  Override hasVideoAvailable() method to return whether there is a video available from the network SDK

5.  Override the showVideo() method and implement code that displays your rewarded interstitial.

6.  Notify the listener object of all the ad lifecycle events via the corresponding methods on MoPubRewardedVideoManager.

public void onRewardedVideoLoadSuccess
public void onRewardedVideoLoadFailure
public void onRewardedVideoStarted
public void onRewardedVideoPlaybackError
public void onRewardedVideoClicked
public void onRewardedVideoClosed
public void onRewardedVideoCompleted

7.  (Optional) Override the onInvalidate() method of CustomEventRewardedVideo if your custom event requires any sort of cleanup.

8.  (Optional) Implement MediationSettings marker interface if you want to enable to publishers to pass any network specific additional parameters during the initialization.

Quick Start for Native Ads

  1. Create a subclass of com.mopub.nativeads.StaticNativeAd in the com.mopub.nativeads package. This class will implement a MoPub Native Ad using a native ad from another network.

  2. After loading the native ad from the network, initialize your object using the following setter methods:

    • setTitle for a title string
    • setText for a text string
    • setIconImageUrl for an icon-size image
    • setMainImageUrl for a larger image
    • setCallToAction for a call to action string
    • setStarRating for a star rating between 0 and 5 (optional)
    • setClickDestinationUrl for a click destination URL
    • addExtra for any additional fields. A string key is required to store and retrieve them.
    • addImpressionTracker for any additional impression tracking urls you want fired
    • setImpressionMinTimeViewed for the minimum amount of time the view is required to be on the screen before recording an impression. This value should be set according to how the network records their impression. The default value is 500ms.
  3. Implement lifecycle methods for handling events with your native ad:

    • prepare is called before an ad is displayed in the app. You should set up impression tracking in this method. See com.mopub.nativeads.MoPubCustomEventNative.MoPubStaticNativeAd#prepare for an example of setting up impression tracking using the com.mopub.nativeads.ImpressionTracker class.
    • handleClick should be implemented if the network requires you to explicitly handle click events of views rendered to screen.
    • clear is called when an ad is no longer displayed to a user. After this, the View used for the ad may be deleted or recycled. You should implement this to clear an viewability tracking code you are using. If using an ImpressionTracker instance, you should remove the view here.
    • destroy is called when the ad will never be displayed again. You should implement it if the network requires you to destroy or cleanup their native ad when you are finished with it.
  4. Impression Tracking Details: All Native Custom Events must implement their own impression tracking and call #notifyAdImpressed when the impression is recorded. MoPub provides utility classes to provide automatic impression tracking. StaticNativeAd implements ImpressionInterface, so you can instantiate an ImpressionTracker in your object’s construction. You should add your ad’s View to an ImpressionTracker instance in prepare and remove it from the ImpressionTracker in clear. In destroy you should call ImpressionTracker#destroy. See com.mopub.nativeads.MoPubCustomEventNative.MoPubStaticNativeAd for an example following this pattern.

  5. Click Tracking Details: All Native Custom Events are responsible for firing click trackers when sending the user to the destination URL. You can easily do this by calling #notifyAdClicked immediately before opening the destination URL. You can also delegate Click URL handling to the MoPub SDK. Implement ClickInterface in your BaseNativeAd subclass and create an instance of com.mopub.nativeads.NativeClickHandler in your class construction. In prepare, add your ad’s View to the NativeClickHandler and remove it from the click handler in clear. See com.mopub.nativeads.MoPubCustomEventNative.MoPubStaticNativeAd for an example following this pattern.

  6. If the network exposes impression or click callbacks, have them call the following methods to notify the SDK to record an impression or click. This is an alternative to using the MoPub ImpressionTracker, ImpressionInterface, NativeClickHandler and ClickInterface classes.

    • notifyAdImpressed should be called from the network’s impression callback to notify the SDK to record an impression.
    • notifyAdClicked should be called from the network’s click callback to notify the SDK to record a click event.
  7. Create a subclass of CustomEventNative in the com.mopub.nativeads package. This class should override the loadNativeAd method and requests a native ad from the network. The serverExtras map will contain any values that were entered into the “Custom Event Class Data” field when youcreated your Custom SDK Network in the MoPub web UI, such as the placement id.

  8. Once the ad is loaded, you need to create an instance of the StaticNativeAd or BaseNativeAd class as described above. If the ad fails to load, you should call customEventNativeListener.onNativeAdFailed with a NativeErrorCode.

  9. Before calling customEventNativeListener.onAdLoaded, call the superclass’s preCacheImages method to ensure that images are displayed immediately when your native ad renders. If images fail to download, you should call customEventNativeListener.onNativeAdFailed.

Advanced: Native Ads

Since Native Ads inflate ViewGroup and View subclasses, developing a Native Ad custom event can be more complicated than developing custom events for banners or interstitials.

A full implementation of Native Ads Mediation for the MoPub Android SDK requires three classes:

  1. Subclass of CustomEventNative. This class will be instantiated by the MoPub SDK when the MoPub ad server indicates returns a result saying the third-party network should load a native ad. This class is responsible for requesting a native ad from the third-party SDK and notifying the MoPub SDK when the ad has loaded or failed to load by calling the corresponding methods on CustomEventNativeListener.

  2. Subclass of BaseNativeAd. This class represents the state of the ad and is responsible for

  3. Implementation of MoPubAdRenderer. This class is related to the NativeAd subclass.

If your SDK contains text, images, and a call to action link, the MoPub SDK provides classes that will simplify development of you Custom Event. Follow the instructions in Quick Start for Native Ads for the simplest implementation of Native Ads mediation. You will not need to write a MoPubAdRenderer subclass, and you will subclass StaticNativeAd instead of BaseNativeAd.

Subclassing BaseNativeAd

NOTE You may subclass StaticNativeAd for simpler code. See the Quick Start for Native Ads

  1. You must extend BaseNativeAd to show native ads for the mediated ads SDK using MoPub.

  2. Implement the #prepare(View) method. This method is called just before an ad is displayed on-screen. It’s commonly used to initialize impression tracking.

  3. Implement the #clear(View) method. This is called when the ad is no longer visible to the user and may be recycled. You should stop any background tasks associated with this ad (for example, impression tracking).

  4. Implement the #destroy() method. This is called when the ad will never be displayed to the user again. Any state associated with the ad (downloaded image or video files, background tasks) can be cleaned up.

  5. When your SDK records an impression, you must call the method BaseNativeAd#notifyAdImpressed. You may also use MoPub-provided utility classes to provide automatic impression tracking. You may implement ImpressionInterface, and you can instantiate an ImpressionTracker in your object’s construction. You should add your ad’s View to an ImpressionTracker instance in prepare and remove it from the ImpressionTracker in clear. In destroy you should call ImpressionTracker#destroy. See com.mopub.nativeads.MoPubCustomEventNative.MoPubStaticNativeAd for an example following this pattern.

  6. When your SDK records an ad click, you must call the method BaseNativeAd#notifyAdClicked before opening the destination URL. You can also delegate Click URL handling to the MoPub SDK. Implement ClickInterface in your BaseNativeAd subclass and create an instance of com.mopub.nativeads.NativeClickHandler in your class construction. In prepare, add your ad’s View to the NativeClickHandler and remove it from the click handler in clear. See com.mopub.nativeads.MoPubCustomEventNative.MoPubStaticNativeAd for an example following this pattern.

Subclassing CustomEventNative

  1. Create a subclass of CustomEventNative in the com.mopub.nativeads package. This class should override the loadNativeAd method and requests a native ad from the network. The serverExtras map will contain any values that were entered into the “Custom Event Class Data” field when youcreated your Custom Native Network in the MoPub web UI, such as the placement id.

  2. Once the ad is loaded, you need to create an instance of the StaticNativeAd or BaseNativeAd class as described above, then call customEventNativeListener.onNativeAdLoaded. If the ad fails to load, you should call customEventNativeListener.onNativeAdFailed with a NativeErrorCode.

Implementing MoPubAdRenderer<T>

Each BaseNativeAd needs a corresponding renderer than understands the fields the BaseNativeAd provides, as well as how to construct and populate the View that shows the ad. MoPub provides the class MoPubStaticNativeAdRenderer that supports all subclasses of StaticNativeAd.

To create your own renderer for your BaseNativeAd (suppose your ad is of the class MyNativeAd):

  1. Implement MoPubAdRenderer:

     public class MyNativeAdRenderer implements MoPubAdRenderer<MyNativeAd> {
    
     }
    
  2. Implement the MoPubAdRenderer#supports method :

     @Override
     public boolean supports(@NonNull final BaseNativeAd nativeAd) {
       return nativeAd instanceOf MyNativeAd.class;
     }
    
  3. Implement #createAdView and #renderAdView methods. The #createAdView method should inflate a layout for the ad type that the renderer supports. #renderAdView should attach the ad creative to the View, setting text and drawable values. You should assume that the View provided to #renderAdView may have been used to show a different ad in the past.

Passing Extra Data To Custom Events

The loadAd() / loadInterstitial() method of your custom event subclass exposes two Map objects that you may use to provide your custom event with any additional data it needs: Map<String, Object> localExtras and Map<String, String> serverExtras.

The localExtras Map can be set anywhere in your application code by calling MoPubView.setLocalExtras(Map<String, Object>) or MoPubInterstitial.setLocalExtras(Map<String, Object>).

The serverExtras Map is populated with data entered in the MoPub web interface. Specifically, after navigating to the Custom SDK Network edit page, you can select the “Custom Event Class Data” column and enter a JSON object with String keys and values in the Data field (e.g. {"id": "12345", "foo": "bar"}). This is particularly useful for passing down third-party Network IDs without making changes to your application code.

Existing Custom Event Classes

We have implemented support for several third-party networks using the Custom Event framework. They can be found in the extras/src/com/mopub/mobileads directory and can be used as a starting point for your own Custom Event implementations.

Last updated October 10, 2018

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.

© 2018 MoPub Inc.