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

1. Basic integration

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

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

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

Native ads requirements

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

2. Configure settings for native ads

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

adQueue.settings setting name

Type

Appointment

Possible values

type

APDNativeAdType

Native Ad Type

APDNativeAdTypeAuto

APDNativeAdTypeVideo

APDNativeAdTypeNoVideo

adViewClass

Class <APDNativeAdView>

Template class

Default template: APDDefaultNativeAdView.class

autocacheMask

APDNativeResourceAutocacheMask

Mask for caching media files

Icons caching: (APDNativeResourceAutocacheIcon): 1

Image and Video caching (APDNativeResourceAutocacheMedia): 2

Cache all media files: 3

3. Initialize a specific type of native ads

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

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

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()
  }
}
To implement native video ads, use the following code:
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()
  }
}
The aspect ratio of native video ads in the Appodeal SDK is 16:9, the file size is about 1-3 Mb.

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

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

4. Cache native ads

Native ads will start download when native ad queue instance is created. You don't need to control loading lifecycle. But if you bring some ad from ad queue you need to have strong reference on it during whole native ads presentation time.  Native ad doesn't have strong reference on view and view doesn't have strong reference on native ad. If application lost reference on native ad after presenting on screen native ad won't tracks any events.

5. Use native ads callbacks

The 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:

class YourViewController: APDNativeAdQueueDelegate, APDNativeAdPresentationDelegate { }
2. Set the delegate:
// Loading callbacks delegate
self.adQueue.delegate = self
// Presentation callbacks delegate
self.currentAd.delegate = self
3. Implement the following functions:
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) {}
}

All callbacks are called on the main thread.

6. Use custom templates for native ads

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

adQueue.settings.adViewClass = YourNativeAdViewTemplate.self
Your template class should conform the following protocol:
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
}

extension APDNativeAdView {
 func descriptionLabel() -> UILabel {}
 func iconView() -> UIImageView {}
 func mediaContainerView() -> UIView {}
 func contentRatingLabel() -> UILabel {}
 func adChoicesView() -> UIView {}
 func setRating(_ rating: NSNumber) {}
}
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.

7. Get all native ads from Native AdQueue

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 )}
        }
    }
}

8. Native Ad object

The NativeAd object has the following characteristics in the Appodeal SDK. All of the fields, marked as “Mandatory”, must be displayed:

Name of fieldRequired?Description
NSString *title;MandatoryThe title of the native ad. Minimum 25 symbols of the title should always be displayed. You can add ellipsis at the end if the title is longer.
NSString *subtitleOptionalThe subtitle of the native ad.
NSString *descriptionTextOptionalThe text description of the native ad. If you choose to display the description, you should display minimum 75 characters. You can add ellipsis at the end.
NSString *callToActionTextMandatoryThe call to action text. Should be displayed without truncation on a visible button.
NSString *contentRatingOptionalRating of the content.
NSNumber *starRatingOptionalRating of the app in [0-5] range.
APDImage *mainImageOptionalBitmap 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 of it to show images or videos.
APDImage *iconImageMandatoryBitmap of an icon. An ad object contains both icon and image. It’s mandatory to use at least one of these elements.
UIView *adChoicesViewMandatoryView. 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.

9. Common mistakes with native ads

  • No ad attribution or AdChoices icon

The majority of ad networks require from publishers to add a special mark to a native ad, 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 ad should 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.

  • Overlaying elements of native ads on each other

Make sure, that all elements of a native ad are visible and not overlaid.

10. Get Predicted eCPM

This method return expected eCPM for cached ad. Amount is calculated based on historical data for the current ad unit.

Appodeal.predictedEcpm(for: .nativeAd)

11. Check if Native was initialized

Appodeal.isInitialized(for: .nativeAd)

Returns true, if Native was initialized.