Native

Native ad is a flexible type of advertising. You can adapt the display for your UI by preparing a template.

You can use our demo app as a reference project.

Demo App

Integration

Native AdQueue is the native ad implementation and management tool in Appodeal SDK. You no longer need to load Native Ads manually. All you have to do is to set the AdQueue object, and it will load new items automatically.

Be careful when using AdQueue: if your app loads too many ads, but is not able to use them, the ad network can either lower the cost of each impression for you or limit your ability to load native ads.

Swift

import Appodeal
class ViewController: UIViewController {
    var adQueue : APDNativeAdQueue!
}

Objective C

#import <Appodeal/Appodeal.h>
@interface YourViewController : UIViewController
@property (nonatomic, strong) APDNativeAdQueue* nativeAdQueue;
@end

---

Native ads requirements

• All of the native ad fields marked as mandatory must be displayed.
• Every ad should have a sign that clearly indicates that it is an ad. For example "Ad" or "Sponsored".
• Provided images can be resized to fit your ad space but should not be significantly distorted or cropped.

Configure Native Ad Settings

In adQueue.settings you can set the following parameters for the native ads displayed in your app:

adQueue.settings setting name	Type	Appointment	Possible values
type	APDNativeAdType	Native Ad Type	APDNativeAdTypeAuto APDNativeAdTypeVideo APDNativeAdTypeVideo
adViewClass	Class APDNativeAdView	Template class	Default template APDDefaultNativeAdView.class
autocacheMask	APDNativeResourceAutocacheMask	Mask for caching media files	Icon caching: (APDNativeResourceAutocacheIcon): 1, Image and Video caching (APDNativeResourceAutocacheMedia): 2, Caching all media files: 3

Initialize A Specific Native Ad Type

Appodeal SDK provides both static and video types of native ads.

To implement static native ads in your app, use the following code:

Swift

class ViewController: UIViewController {
    var adQueue : APDNativeAdQueue!
    override func viewDidLoad() {
        super.viewDidLoad()
        adQueue.settings.adViewClass = TemplateClass.self
        adQueue.settings.autocacheMask = [.icon, .media]
        adQueue.settings.type = .novideo
        
        adQueue.loadAd()
  }
}

Objective C

- (void)viewDidLoad {
   self.nativeAdQueue = [APDNativeAdQueue new];
   self.nativeAdQueue.settings.type = APDNativeAdTypeNoVideo;
   self.nativeAdQueue.settings.adViewClass = APDDefaultNativeAdView.class;
   self.nativeAdQueue.settings.autocacheMask = APDNativeResourceAutocacheIcon | APDNativeResourceAutocacheMedia;
   [adQueue loadAd];
}

---

To implement native video ads, use the following code:

Swift

class ViewController: UIViewController {
    var adQueue : APDNativeAdQueue!
    override func viewDidLoad() {
        super.viewDidLoad()
        adQueue.settings.adViewClass = TemplateClass.self
        adQueue.settings.autocacheMask = [.icon, .media]
        adQueue.settings.type = .video
        
        adQueue.loadAd()
  }
}

Objective C

#import <Appodeal/Appodeal.h>

@interface YourViewController : UIViewController

@property (nonatomic, strong) APDNativeAdQueue* nativeAdQueue;
@property (nonatomic, strong) UIView * nativeAdView;

@end 

@implementation YourViewController

- (void)viewDidLoad {
     self.nativeAdQueue = [[APDNativeAdQueue alloc] init];
     self.nativeAdQueue.settings.type = APDNativeAdTypeVideo;
     self.nativeAdQueue.settings.adViewClass = APDDefaultNativeAdView.class;
     self.nativeAdQueue.delegate = self;
     self.nativeAdQueue.settings.autocacheMask = APDNativeResourceAutocacheIcon | APDNativeResourceAutocacheMedia;
 
     [self.nativeAdQueue loadAd];
 }

 @end

---

The aspect ratio of native video ads in Appodeal SDK is 16:9, the file size is about 1-3 Mb.

There are two types of native video ads in Appodeal SDK:

• skippable - if “skippable” flag is stated, the video can be skipped after 5 seconds;
• muted - if “muted” flag is stated, the video will be played with no sound.

Caching

Native ads will start downloading when a native ad queue instance is created. You don't need to control the loading lifecycle. But if you bring some ad from ad queue, you need to have strong reference to it during the whole native ad presentation time. Native ad doesn't have a strong reference to view and view doesn't have a strong reference on the native ad. If application loses reference to the native ad after the impression, the native ad won't be tracking any events.

Callbacks

Callbacks are used to track different events in the lifecycle of an ad, e.g., when an ad was clicked on or closed. To get them, you need to set the delegate as follows:

1. Add APDNativeAdQueueDelegate and APDNativeAdPresentationDelegate to the header file:

Swift

class YourViewController: APDNativeAdQueueDelegate, APDNativeAdPresentationDelegate { }

Objective C

@interface YourViewController : UIViewController <APDNativeAdQueueDelegate, APDNativeAdPresentationDelegate>

---

2. Set the delegate:

Swift

// Loading callbacks delegate
self.adQueue.delegate = self
// Presentation callbacks delegate
self.currentAd.delegate = self

Objective C

// Loading callbacks delegate
self.adQueue.delegate = self;
// Presentation callbacks delegate
self.currentAd.delegate = self;

---

3. Implement the following functions:

Swift

extension MainViewController : APDNativeAdPresentationDelegate {
    func nativeAdWillLogImpression(_ nativeAd: APDNativeAd!) {}
    func nativeAdWillLogUserInteraction(_ nativeAd: APDNativeAd!) {}
}

extension MainViewController : APDNativeAdQueueDelegate {
    func adQueue(_ adQueue: APDNativeAdQueue!, failedWithError error: Error!) {}
    func adQueueAdIsAvailable(_ adQueue: APDNativeAdQueue!, ofCount count: UInt) {}
}

Objective C

- (void)adQueueAdIsAvailable:(APDNativeAdQueue *)adQueue ofCount:(NSUInteger)count {
}
- (void)adQueue:(APDNativeAdQueue *)adQueue failedWithError:(NSError *)error {
}
- (void)nativeAdWillLogImpression:(APDNativeAd *)nativeAd {
}
- (void)nativeAdWillLogUserInteraction:(APDNativeAd *)nativeAd {
}

---

tip

All callbacks are called on the main thread.

Use Custom Native Ad Templates

To use your custom templates for native ads, simply state your template class in adQueue.setting.adViewClass as follows:

Swift

adQueue.settings.adViewClass = YourNativeAdViewTemplate.self

Objective C

adQueue.settings.adViewClass = YourNativeAdViewTemplate.class;

---

Your template class should conform to the following protocol:

Swift

protocol APDNativeAdView {
    func titleLabel() -> UILabel
    func callToActionLabel() -> UILabel
    // Optional
    func descriptionLabel() -> UILabel
    func iconView() -> UIImageView
    func mediaContainerView() -> UIView
    func contentRatingLabel() -> UILabel
    func adChoicesView() -> UIView
    func setRating(_ rating: NSNumber)
    static func nib() -> UINib
}

Objective C

@protocol APDNativeAdView <NSObject>
- (nonnull UILabel *)titleLabel;
- (nonnull UILabel *)callToActionLabel;
@optional
- (nonnull UILabel *)descriptionLabel;
- (nonnull UIImageView *)iconView;
- (nonnull UIView *)mediaContainerView;
- (nonnull UILabel *)contentRatingLabel;
- (nonnull UIView *)adChoicesView;
- (void)setRating:(nonnull NSNumber *)rating;
+ (nonnull UINib *)nib;
@end

---

The objects mentioned in this protocol are:

• titleLabel - container for title text;
• callToActionLabel - container for call-to-action text;
• descriptionLabel - container for description text;
• iconView - container for icon image;
• mediaContainerView - container for media files (images and video files);
• contentRatingLabel - container for showing rating of the content;
• adChoicesView - container for showing adChoice;
• rating - container for showing rating of the app;
• nib - nib-file for template.

note

All views should be enclosed in a single superview. If YourNativeAdViewTemplate inherits from UITableViewCell(UICollectionViewCell), these views should be contained in the hierarchy of contentView.

Get All Native Ads From Native AdQueue

Swift

import UIKit
import Appodeal

class ViewController: UIViewController {
    
    @IBOutlet weak var nativeAdView: UIView!
    var nativeAdQueue: APDNativeAdQueue!
    var nativeArray: [APDNativeAd] = []
    
    override func viewDidLoad() {
        super.viewDidLoad()
        nativeAdQueue = APDNativeAdQueue()
        nativeAdQueue.settings = APDNativeAdSettings.default()
        nativeAdQueue.settings.adViewClass = CustomNativeAdView.self
        nativeAdQueue.delegate = self
        nativeAdQueue.settings.autocacheMask = [.icon, .media]
        
        nativeAdQueue.loadAd()
    }
    
    @IBAction func presentNativeAd(_ sender: Any) {
        let nativeAd = nativeArray.first
        if let nativeAd = nativeAd {
            nativeAd.delegate = self
            do {
                let adView = try nativeAd.getViewForPlacement("default", withRootViewController: self)
                adView.frame = nativeAdView.bounds
                nativeAdView.addSubview(adView)
            } catch {
                print("error")
            }
        }
    }
}

extension ViewController: APDNativeAdQueueDelegate, APDNativeAdPresentationDelegate {
    func adQueueAdIsAvailable(_ adQueue: APDNativeAdQueue, ofCount count: UInt) {
        if nativeArray.count > 0 {
            return
        } else {
            nativeArray.append(contentsOf: adQueue.getNativeAds(ofCount: 1))
            nativeArray.map{( $0.delegate = self )}
        }
    }
}

Objective C

#import "ViewController.h"
#import <Appodeal/Appodeal.h>
#import <Appodeal/APDNativeAdQueue.h>
#import "CustomNativeAdView.h"

@interface ViewController ()<APDNativeAdQueueDelegate, APDNativeAdPresentationDelegate>

@property (strong, nonatomic) IBOutlet UIView *nativeAdView;
@property (nonatomic, strong) APDNativeAdQueue* nativeAdQueue;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.nativeAdQueue = [[APDNativeAdQueue alloc] init];

    self.nativeAdQueue.settings = [APDNativeAdSettings defaultSettings];
    self.nativeAdQueue.settings.adViewClass = [CustomNativeAdView class];
    self.nativeAdQueue.delegate = self;
    self.nativeAdQueue.settings.autocacheMask = APDNativeResourceAutocacheIcon | APDNativeResourceAutocacheMedia;

    [self.nativeAdQueue loadAd];
    [Appodeal setLogLevel:APDLogLevelVerbose];
}

- (void)presentNative:(id)sender {
    APDNativeAd * nativeAd = [[self.nativeAdQueue getNativeAdsOfCount:1] firstObject];
    nativeAd.delegate = self;
    CustomNativeAdView * adview = [nativeAd getAdViewForController:self];
    [self.nativeAdView addSubview:adview];
    adview.frame = self.nativeAdView.bounds;
}

@end

---

Native Ad Object

NativeAd objects have the following characteristics in Appodeal SDK. All of the fields marked as “Mandatory” must be displayed:

Name of field	Required?	Description
*NSString title	Mandatory	Native ad title. At least 25 characters of the title should always be displayed. You can add ellipsis at the end if the title is longer.
*NSString subtitle	Optional	Native ad subtitle
*NSString descriptionText	Optional	Text description of the native ad. If you choose to display the description, you should display ate least 75 characters. You can add ellipsis at the end.
*NSString callToActionText	Mandatory	The call to action text. Should be displayed on a visible button without truncation.
*NSString contentRating	Optional	Rating of the content.
*NSNumber starRating	Optional	App in the [0-5] range.
*APDImage mainImage	Optional	Bitmap of an image. An ad object contains both icon and image. It's mandatory to use at least one of these elements. Deprecated method. NativeMediaView should be used instead to show images or videos.
*APDImage iconImage	Mandatory	Bitmap of an icon. An ad object contains both icon and image. It's mandatory to use at least one of these elements.
*UIView adChoicesView	Mandatory	View. If it doesn't return null, it's mandatory to display the provider icon in any corner of the native ad. Used by some networks to display AdChoices or the privacy icon.

Common Mistakes With Native Ads

• No ad attribution or AdChoices icon

  The majority of ad networks require publishers to add a special mark to native ads, so users don't mistake them for content. That's why you always need to make sure, that native ads in your app have the ad attribution (e.g., “Ad”) or the AdChoices icon.

• Absence of the required native ad elements

  Every native must contain:

  • title;
  • call-to-action button;
  • ad attribution or AdChoices icon;
  • icon, image or video.

• Native ad elements alteration

  Advertisers expect that their ads will be displayed clearly and without any alteration. You can scale buttons and images, but you shouldn't crop, cover or distort them.

• Overlapping native ad elements

  Make sure that all native ad elements are visible and do not overlap.

Get Predicted eCPM

This method returns the expected eCPM for the cached ad. The amount is calculated based on historical data for the current ad unit.

Swift

Appodeal.predictedEcpm(for: .nativeAd)

Objective C

[Appodeal isInitalizedForAdType: AppodealAdTypeNativeAd];

---

Check If Native Ad Is Initialized

Swift

Appodeal.isInitialized(for: .nativeAd)

Objective C

[Appodeal isInitalizedForAdType: AppodealAdTypeNativeAd];

---

Returns true, if the Native has been initialized.

Check Viewability

You can always check in logs if show was tracked and your ad is visible.

You will see the following log if show was tracked successfully.

[Appodeal *.*.*] [debug] [impression] Impression <APDImpression: 0x600002953b10> succesfully tracked