Custom Events

Kelcey edited this page Oct 23, 2015 · 4 revisions

Custom Event Classes for iOS

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 MPBannerCustomEvent in your application.

  2. Override the -requestAdWithSize:customEventInfo: method and implement code that requests an ad.

  3. When your ad loads successfully, you must notify MoPub of the event by calling the -bannerCustomEvent:didLoadAd: method on the custom event object’s delegate (accessible via the delegate property).

  4. Similarly, you must notify the delegate when your ad fails to load by calling -bannerCustomEvent:didFailToLoadAdWithError: method.

  5. (Optional) Notify the delegate of user interaction events via the corresponding delegate methods:

    -bannerCustomEventWillBeginAction:
    -bannerCustomEventDidFinishAction:

    NOTE: If your implementation calls -bannerCustomEventWillBeginAction:, it must also call -bannerCustomEventDidFinishAction:.

  6. (Optional) Notify the delegate if the user leaves the application from a banner via the -bannerCustomEventWillLeaveApplication: method.

  7. (Optional) Implement the -dealloc method 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 class name of your custom event (e.g. YourBannerCustomEvent) in the "Custom Class" column.

Once you've completed these steps, the MoPub SDK will be able to automatically instantiate your MPBannerCustomEvent subclass when your application is running. You do not need to instantiate any of these subclasses in your application code.

Note: the MoPub SDK will instantiate a new MPBannerCustomEvent object on every ad call, so you can safely make changes to the custom event object's internal state without affecting subsequent ad calls.

Quick Start for Interstitials

  1. Create a subclass of MPInterstitialCustomEvent in your application.

  2. Override the -requestInterstitialWithCustomEventInfo: method and implement code that requests an interstitial.

  3. Override the -showInterstitialFromRootViewController: and implement code that displays your interstitial.

  4. You must notify MoPub of all of the following interstitial lifecycle events, by calling the corresponding methods on the custom event object’s delegate (accessible via the delegate property):

    -interstitialCustomEvent:didLoadAd:
    -interstitialCustomEvent:didFailToLoadAdWithError:

    -interstitialCustomEventWillAppear:
    -interstitialCustomEventDidAppear:

    -interstitialCustomEventWillDisappear:
    -interstitialCustomEventDidDisappear:

    All of the methods above are required. If the ad network you are trying to use does not provide callbacks for one/more of these events, you should still call the custom event method at an appropriate time.

    For example, if an ad network only provides an adDidDisappear callback, your custom event should fire both -interstitialCustomEventWillDisappear: and -interstitialCustomEventDidDisappear: in response.

  5. (Optional) If the ad network is capable of notifying you when a user interacts or taps on an ad, you should forward this information to the MoPub SDK so that MoPub can provide accurate analytics. You can do so by calling the interstitialCustomEventDidReceiveTapEvent: method on the custom event delegate.

  6. (Optional) Implement the -dealloc method 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 class name of your custom event (e.g. YourInterstitialCustomEvent) in the "Custom Class" column.

Once you've completed these steps, the MoPub SDK will be able to automatically instantiate your MPInterstitialCustomEvent subclass when your application is running. You do not need to instantiate any of these subclasses in your application code.

Note: the MoPub SDK will instantiate a new MPInterstitialCustomEvent object on every ad call, so you can safely make changes to the custom event object's internal state without affecting subsequent ad calls.

Quick Start For Native Ads

  1. Create a class that implements the MPNativeAdAdapter protocol. This class will act as an adapter between the MPNativeAd interface and your custom native ad.

  2. Create an initialization method that takes in the your network’s native ad as a parameter. In addition to retaining this in a property, you also need to map its content to a dictionary properties. The keys you need to use can be found in MPNativeAdConstants.h, and include:

    • kAdTitleKey for a title string
    • kAdTextKey for a description or body text
    • kAdIconImageKey for an icon-sized image
    • kAdMainImageKey for a larger image
    • kAdCTATextKey for a call to action string
    • kAdStarRatingKey for a star rating (that needs to be normalized to a 0-5 scale).

      Another necessary property to implement is the defaultActionURL -- the URL the user is taken to when they interact with the ad. If the native ad automatically opens it then this can be nil.

      Any additional content can be placed in the properties dicitonary at your discretion, which will allow you to access it through the MPNativeAd interface.

  3. Implement the method displayContentForURL:rootViewController:completion:. This method is called when the user interacts with your ad, and can either forward the call to a corresponding method on the mediated ad, or you can implement URL-opening yourself. You do not need to implement this method if your ad network automatically handles taps on your ad.

  4. (Optional) The MPNativeAdAdapter protocol also has a number of optional methods that can be implemented to allow for further customization and passing behavior back to the mediated ad.

    • willAttachToView: is called when the ad content is loaded into its container view, and passes back that view. Native ads that automatically track impressions should implement this method.
    • trackClick is called when the user interacts with an ad, and allows for manual click tracking for the mediated ad.
  5. Create a class that conforms to the MPNativeAdRendererSettings protocol.

  6. Expose the viewSizeHandler property on your class so the ad can be properly sized when used with an ad placer product.

    @property (nonatomic, readonly) MPNativeViewSizeHandler viewSizeHandler;

    Add any additional properties to the class that can be configured by the application.

  7. Create a class that conforms to the MPNativeAdRenderer protocol. Expose the viewSizeHandler property on this object as well.

  8. Implement rendererConfigurationWithRendererSettings:.

    + (MPNativeAdRendererConfiguration *)rendererConfigurationWithRendererSettings:(id<MPNativeAdRendererSettings>)rendererSettings

    Create an MPNativeAdRendererConfiguration object by setting the rendering class to your class that conforms to the MPNativeAdRenderer protocol. Set the configuration object's rendererSettings property to the rendererSettings parameter. Finally, specify which custom events your renderer supports by setting the supportedCustomEvents property to an array that contains the name of your class that is a subclass of MPNativeCustomEvent outlined in step 11.

  9. Implement initWithRendererSettings:. Set your object's viewSizeHandler to the viewSizeHandler in the rendererSettings parameter. Extract any custom settings properties from your rendererSettings here or simply keep a reference to the renderer settings in your class if you need them to render your ad view.

  10. Implement retrieveViewWithAdapter:. Return a view that contains the rendered ad elements using the data contained in your adapter class. You should recreate the view each time this is called if possible.

  11. Create a subclass of MPNativeCustomEvent.

  12. Override the requestAdWithCustomEventInfo: method and implement code that requests an ad. The info NSDictionary passed to this method is defined in the custom native network set up on app.mopub.com under Custom Event Class Data. It should include any necessary information for requesting an ad on your network such as ad unit ID.

  13. When the ad returns, you need to create a corresponding object that adheres to the MPNativeAdAdapter protocol (as described in previous steps), and use that to create an MPNativeAd with the initWithAdAdapter: initializer.

  14. Before calling customNativeEvent:didLoadAd: on the custom event's delegate, call the superclass's precacheImagesWithURLs:completionBlock: method to download and cache the images that will be shown in the ad (typically the icon and main image). At that point, the delegate can receive the MPNativeAd object.

  15. If at any point an error occurs loading the mediated ad or its images, call nativeCustomEvent:didFailToLoadAdWithError: on the inherited delegate.

Passing Extra Data To Custom Events

In both the banner and interstitial custom event subclasses, the methods called to load an ad include an NSDictionary parameter (called info) that you may use to provide your custom event with any additional data it needs.

The info object 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.

Impression and Click Tracking

Banner and Interstitial Ads

The MoPub SDK will automatically record impressions and clicks for custom events in response to certain delegate callbacks.

For banner custom events, impressions are recorded on -bannerCustomEvent:didLoadAd:, and clicks are recorded on -bannerCustomEventWillBeginAction: or -bannerCustomEventWillLeaveApplication:.

For interstitial custom events, impressions are recorded on -interstitialCustomEventDidAppear:, and clicks are recorded on -interstitialCustomEventDidReceiveTapEvent:.

If you require more control over when impressions and clicks are recorded, you may override the default behavior in your custom event by overriding -(BOOL)enableAutomaticImpressionAndClickTracking and returning NO. You can then manually report impressions and clicks by calling -trackImpression and -trackClick on the custom event delegate.

Native Ads

The MPNativeAdAdapter protocol provides flexible methods that allow for easy click and impression tracking.

If the mediated ad requires manual click tracking, provide an implementation for trackClick. The MPNativeAd will call this method automatically when appropriate.

If the mediated ad automatically handles clicks, implement -enableThirdPartyClickTracking and return NO. When your ad does track a click, you must call -nativeAdDidClick on your adapter's delegate.

If the mediated ad requires manual impression tracking, you must determine when your adapter tracks an impression and call -nativeAdWillLogImpression: on your adapter's delegate.

If the mediated ad already provides automatic impression tracking, the willAttachToView: method allows the adapter to pass the corresponding UIView to the mediated ad. You must call -nativeAdWillLogImpression: on your adapter's delegate when your adapter is notified that an impression has been tracked by the 3rd party SDK.