Native Ads (Manual Integration)

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.


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.

  3. Be sure to initialize the MoPub SDK before loading an ad.

Integrate Native Ads Manually

This option is best for cases where you want to insert an ad into something other than a TableView or CollectionView. With the manual integration, you have to manually request and receive ads, handle caching and handle not showing empty spaces in case the ad request doesn’t fill.

The foundation of the MoPub native ad lies in these four classes:

  • MPNativeAdRequest - provides a simple, block-based interface for asynchronously fetching ads.
  • MPNativeAd - provides an interface for retrieving a rendered native ad view.
  • MPNativeAdRenderer - the base class for all types of renderers that instruct the SDK on how it should render a given native ad format.
  • MPNativeAdRendererConfiguration - links a renderer and its settings to specific ad formats.

Manual integration consists of these high-level steps:

  1. Define the layout of your ad.
  2. Prepare to render your native ad.
  3. Request a native ad.
  4. Display the native ad.
  5. Optionally receive delegate callbacks.

Important: Please do not use publisher-provided overlays (such as close buttons) that are located with the ad placement and that subsequently cover the ad creative. Doing so is against MoPub Policy. If you have questions, please visit the Support Center and file a ticket for additional assistance.

Step 1. Define the Layout of Your Ad

Advertising content can be displayed in any new or existing UIView subclass that implements the MPNativeAdRendering protocol. This protocol allows you to specify what elements of your UI should be used for each native ad element.

The native ad renderer associated with your ad asks your view for a UI element via protocol methods for each native ad element. Typically, a native ad has a base set of assets (as configured on the MoPub website):

  • title
  • main text
  • call-to-action text
  • sponsored text (new starting with MoPub SDK v5.11+)
  • icon image URL
  • main image URL

A MoPub native ad also contains an asset for privacy information icons. The MoPub SDK automatically handles tap events on the privacy information icon. You are required to display a privacy information icon in your view.

// YourNativeAdView.h

@interface YourNativeAdView : UIView <MPNativeAdRendering>

@property (strong, nonatomic) UILabel *titleLabel;
@property (strong, nonatomic) UILabel *mainTextLabel;
@property (strong, nonatomic) UILabel *callToActionLabel;
@property (strong, nonatomic) UILabel *sponsoredByLabel;
@property (strong, nonatomic) UIImageView *iconImageView;
@property (strong, nonatomic) UIImageView *mainImageView;
@property (strong, nonatomic) UIImageView *privacyInformationIconImageView;


// YourNativeAdView.m

@implementation YourNativeAdView


- (void)layoutSubviews
    [super layoutSubviews];
    // layout your views

- (UILabel *)nativeMainTextLabel
    return self.mainTextLabel;

- (UILabel *)nativeTitleTextLabel
    return self.titleLabel;

- (UILabel *)nativeCallToActionTextLabel
    return self.callToActionLabel;

- (UILabel *)nativeSponsoredByCompanyTextLabel
    return self.sponsoredByLabel;

- (UIImageView *)nativeIconImageView
    return self.iconImageView;

- (UIImageView *)nativeMainImageView
    return self.mainImageView;

- (UIImageView *)nativePrivacyInformationIconImageView
    return self.privacyInformationIconImageView;


Optionally Render Custom Assets for Direct Serve Ads

When creating a Direct Serve ad creative on the MoPub website, you can add custom assets to supplement the pre-defined ones assets above. The SDK calls layoutCustomAssetsWithProperties:imageLoader: on your view, which implements MPNativeAdRendering, giving you an opportunity to display custom assets within your view.

The example below demonstrates how to layout custom text and a custom image:

- (void)layoutCustomAssetsWithProperties:(NSDictionary *)customProperties imageLoader:(MPNativeAdRenderingImageLoader *)imageLoader
    self.customTextLabel.text = customProperties[@"customText"];

    // To load custom images, you can use the imageLoader's convenience method -loadImageForURL:intoImageView:.
    [imageLoader loadImageForURL:[NSURL URLWithString:customProperties[@"customImage"]] intoImageView:self.customImageView];

Step 2. Prepare to Render Your Native Ad

  1. Create and configure an MPStaticNativeAdRendererSettings object with a rendering view class that adheres to the MPNativeAdRendering protocol:

     MPStaticNativeAdRendererSettings *settings = [[MPStaticNativeAdRendererSettings alloc] init];
     settings.renderingViewClass = [YourNativeAdView class];
  2. Call rendererConfigurationWithRendererSettings: on the renderer you are using with your settings to create an MPNativeAdRendererConfiguration object:

     MPNativeAdRendererConfiguration *config = [MPStaticNativeAdRenderer rendererConfigurationWithRendererSettings:settings];

Step 3. Request a Native Ad

  1. Create an MPNativeAdRequest object using the +requestWithAdUnitIdentifier:rendererConfigurations: method:

     MPNativeAdRequest *adRequest = [MPNativeAdRequest requestWithAdUnitIdentifier:@"YOUR_AD_UNIT_ID" rendererConfigurations:@[config]];
  2. Import MPNativeAdConstants.h to enable native ads targeting and set an MPNativeAdRequestTargeting object on the request in order to provide targeting information, such as location and the native ad elements you would like to receive:

     MPNativeAdRequestTargeting *targeting = [MPNativeAdRequestTargeting targeting];

    Choose which native ad elements you want to receive from the Marketplace to conserve device bandwidth and provide information about your ad to the Marketplace:

     targeting.desiredAssets = [NSSet setWithObjects:kAdTitleKey, kAdTextKey, kAdCTATextKey, kAdIconImageKey, kAdMainImageKey, kAdStarRatingKey, nil]; //The constants correspond to the 6 elements of MoPub native ads

    Optionally, provide the geo-location to the advertiser:

     targeting.location = [self getCurrentLocation]; // developer-provided location. Note that, starting in v5.9.0 of the MoPub SDK, GPS location is prioritized over location data you supply from the app (i.e. when both are available, the MoPub SDK will utilize GPS location).
     adRequest.targeting = targeting;
  3. Start the request via -startWithCompletionHandler:, providing a completion block to handle the results of the request. If the request is successful, the completion block’s MPNativeAd parameter represents an object that contains the ad’s assets. You must store a reference to the MPNativeAd object in your view controller. Set your current view controller as the native ad’s delegate and call retrieveAdViewWithError: to get a rendered native ad view. Finally, add the rendered view to your view hierarchy:

     [adRequest startWithCompletionHandler:^(MPNativeAdRequest *request, MPNativeAd *response, NSError *error) {
         if (error) {
             // Handle error.
         } else {
             self.nativeAd = response;
             self.nativeAd.delegate = self;
             UIView *nativeAdView = [response retrieveAdViewWithError:nil];
             nativeAdView.frame = self.yourNativeAdViewContainer.bounds;
             [self.yourNativeAdViewContainer addSubview:nativeAdView];

    Note: Ad requests must be made on the main thread.

Step 4. Display the Native Ad

Implement the MPNativeAd delegate method - (UIViewController *)viewControllerForPresentingModalView and return the view controller that you wish to use to present ad modals (typically self).

Note: Ensure that you are using the provided APIs to automatically track impressions and clicks.

Step 5. Optionally Receive Delegate Callbacks

MPNativeAdDelegate includes optional delegate callbacks that you can use to be notified of events such as when an ad will present a modal, an ad modal dismisses, and when the app will background due to user interaction with an ad.

Best Practices

Hide Blank Ad Views

Avoid displaying ad views in your app that have not yet been configured with assets. In addition, make sure your app adapts gracefully when ad requests fail due to lack of inventory or connectivity issues.

For example, if your application displays ads in a table view, ensure that failed ad requests do not cause unnecessary blank cells or gaps in the table.

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.

Last updated August 28, 2021

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.

© 2021 MoPub (a division of Twitter, Inc.)