Custom events allow you to support native ad networks not bundled with the MoPub SDK, or to execute any of your application code from the MoPub web interface.

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 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 Native Network" type. Place the fully-qualified class name of your custom event (e.g. com.mopub.mobileads.YourCustomEventBanner) in the "Custom 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 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 Native Network" type. Place the fully-qualified class name of your custom event (e.g. com.mopub.mobileads.YourCustomEventInterstitial) in the "Custom 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 Native Ads

Note Advanced instructions available: Native Custom Event Development

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 Native 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.

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 Native Network edit page, you can select the "Custom Class" 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.