iOS SDK - Native Mediation

Native Ads allow you to seamlessly embed ads into your application. Native Mediation provides a common interface between AdMob, AppLovin, Facebook Audience Network, Heyzap, and InMobi native ads.

Because of the inherent complexity of native mediation, it is recommended that you read our header files in Xcode or see the Cocoadocs related to native mediation, in addition to reading this documentation.

Class Overview

  • HZMediatedNativeAdManager: Responsible for fetching and returning native ads.
  • HZMediatedNativeAd: An native ad object providing a common interface between the mediated networks.
  • HZNativeAdImage: A model representing an image. It includes properties like the URL of the image and its size. The size is not available for AdMob's images.

We also offer a non-mediated native ads product. When using our mediated ads product, you can ignore these Heyzap-only native ad classes:

  • HZNativeAdController
  • HZNativeAdCollection
  • HZNativeAd

Step 1. Integrate the SDK

Follow our documentation on integrating the Heyzap SDK and third-party SDKs before continuing.

Step 2. Fetch Native Ads

HZFetchOptions *options = [[HZFetchOptions alloc] init];
options.presentingViewController = self; // Setting this property is required to request AdMob ads.
options.tag = @"optional_tag";
options.completion = ^(BOOL success, NSError *error) {
    if (success) {
        NSLog(@"Native ad was fetched");
    } else {
        NSLog(@"Error fetching native ad: %@",error);
    }
};
[HZMediatedNativeAdManager fetchNativeAdWithOptions:options];

Step 3. Show Native Ads

NSError *error;
HZMediatedNativeAd *nativeAd = [HZMediatedNativeAdManager getNextNativeAdForTag:@"optional_tag" error:&error];
if (nativeAd) {
    // Perform final configuration of the native ad
    ad.presentingViewController = self; // This must be set for all ad networks.
    ad.facebookAdChoicesViewCorner = UIRectCornerTopLeft; // Optional; defaults to UIRectCornerTopRight

    /// All views you use to display native ad properties must be subviews of the nativeAd.wrapperView property

    // Step 1. Configure the wrapper view:
    UIView *wrapperView = nativeAd.wrapperView;
    wrapperView.frame = self.view.bounds;
    [self.view addSubview:wrapperView];

    // Step 2. Configure views based on the native ad properties
    self.titleLabel.text = self.nativeAd.title;
    self.bodyTextView.text = self.nativeAd.body;
    self.ctaLabel.text = self.nativeAd.callToAction;
    [self.iconView setImageWithURL:self.nativeAd.iconImage.url]; // Use a library like AFNetworking or SDWebImage to load the UIImage from a URL.
    [self.coverImageView setImageWithURL:[self.nativeAd coverImageWithPreferredOrientation:HZPreferredImageOrientationLandscape].url];

    // Step 3. Add the views as subviews of the wrapper view
    [wrapperView addSubview:self.titleLabel];
    [wrapperView addSubview:self.bodyTextView];
    [wrapperView addSubview:self.ctaLabel];
    [wrapperView addSubview:self.iconView];
    [wrapperView addSubview:self.coverImageView];

    // Step 4. Specify which views display which native ad properties
    [self.nativeAd registerViews:^(id<HZMediatedNativeAdViewRegisterer>registerer) {
        // If tappable is NO, clicks on that view will be ignored for Heyzap and Facebook Audience Network
        [registerer registerTitleView:self.titleLabel tappable:YES];
        [registerer registerBodyView:self.bodyTextView tappable:YES];
        [registerer registerCallToActionView:self.ctaLabel];
        [registerer registerIconView:self.iconView tappable:YES];
        [registerer registerCoverImageView:self.coverImageView tappable:YES];
    }];
} else {
    NSLog("Error getting next available native ad: %@", error);
}

Required Properties

Some networks require certain properties to be displayed on the native ad view. There are three approaches you can use to display the required properties:

  1. Display a superset of all the required properties between ad types.
  2. Use the adType property of HZMediatedNativeAd to determine the ad type, and thus the required properties, dynamically.
  3. Limit the type of ads you request (You can e.g. not request AdMob Content Ads by configuring the HZFetchOptions object).
Network Ad Type Required Properties
AdMob (App Install) HZMediatedNativeAdTypeAdMobAppInstall title, callToAction, iconImage
AdMob (Content) HZMediatedNativeAdTypeAdMobContent title, body
AppLovin HZMediatedNativeAdTypeAppLovin None
Facebook Audience Network HZMediatedNativeAdTypeFacebook title, callToAction
Heyzap HZMediatedNativeAdTypeHeyzap None
Heyzap Cross Promotion HZMediatedNativeAdTypeHeyzapCrossPromo None
InMobi HZMediatedNativeAdTypeInMobi None

Appendix

API Documentation

For complete, API-level documentation, refer to our header files in Xcode or see the Cocoadocs related to Native Mediation.

NSNotifications

You can be notified of impressions and clicks for native ads using NSNotificationCenter. You can limit the notifications you receive to be about a single native ad by passing it as the object when registering for the NSNotification. Otherwise, passing nil to the object param will notify you about every native ad.

[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(nativeAdHadImpression:)
                                             name:HZMediatedNativeAdImpressionNotification
                                           object:self.nativeAd];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(nativeAdWasClicked:)
                                             name:HZMediatedNativeAdClickNotification
                                           object:self.nativeAd];

Displaying Mediated Native Ads in UITableViewCell / UICollectionViewCell

UITableViewCell and UICollectionViewCells are typically taken from a reuse pool and restyled to show new content. If you're reusing cells displaying native ad content, you'll want to disassociate the current native ad from the cell in prepareForReuse to accomodate a new native ad:

- (void)prepareForReuse {
    // Remove your subviews from the wrapper view
    [self.titleLabel removeFromSuperview];
    [self.bodyTextView removeFromSuperview];
    [self.ctaLabel removeFromSuperview];
    [self.iconView removeFromSuperview];
    [self.coverImageView removeFromSuperview];

    // Remove the wrapperView from the view hierarchy
    [self.wrapperView removeFromSuperview];

    // If necessary, unregister for any notifications related to the native view
    [[NSNotificationCenter defaultCenter] removeObserver:self
                                                    name:HZMediatedNativeAdImpressionNotification
                                                  object:self.nativeAd];
    [[NSNotificationCenter defaultCenter] removeObserver:self
                                                    name:HZMediatedNativeAdClickNotification
                                                  object:self.nativeAd];

    // Recommended: nil out properties referencing the native ad 
    self.wrapperView = nil;
    self.nativeAd = nil;

    [super prepareForReuse];
}

Alternatively, because ads will only be rarely shown relative to your actual content, for simplicity you may wish to not re-use cells showing ads.