1. Addapptr
  2. AATKit iOS
  3. Native Ads Sample

Wiki

Clone wiki

Native Ads Sample / NativeAd AATKit 3 migration (beta)

View History

NativeAd AATKit 3 migration (beta)

Index:

  1. NativeAd Integration
  2. Check the sample app

Create a native placement

to create a Native placement call the following:

Instead of:

Objective-C: 

[AATKit createNativeAdPlacement:@"NativeAdPlacement" supportsMainImage: YES];
Swift: 
AATKit.createNativeAdPlacement(@"NativeAdPlacement", supportsMainImage: true)

use

Objective-C: 

[AATSDK createNativeAdPlacementWithName:placementName supportsMainImage:YES statisticsListener:self];
Swift: 
AATSDK.createNativeAdPlacement(name: "NativeAdPlacement", supportsMainImage: true)

Start loading native ads

Native ads have to be loaded via: 

func reloadPlacement(placement: AATPlacement, forceLoad: Bool = false) -> Bool
Provide the placement reference for load one or even multiple native ads. This is different from banner and fullscreen ads, where only one ad could be loaded. Since native ads can occur in large numbers, it's possible to preload and cache multiple native ads via one native placement. Due to the fact that preloading of multiple ads is possible, plus the requested amount may vary a lot, automatic reloading is NOT available. The logic of loading a native ad has to be handled by the programmer.

Example: Instead of:

Objective-C: 

[AATKit reloadPlacement:self.nativePlacement];
Swift: 
AATKit.reload(nativePlacement)

use:

Objective-C: 

[AATSDK reloadPlacementWithPlacement:self.nativeAdPlacement forceLoad:YES];
Swift: 
AATSDK.reloadPlacement(placement: nativeAdPlacement)

Retrieve the native ad

(after callback [AATKit haveAd:])

Since multiple native ads can be retrieved from a native placement, the placement can be asked multiple times for a native ad.

Instead of:

Objective-C: 

[AATKit getNativeAdForPlacement:placement]
Swift: 
AATKit.getNativeAd(for: placement)

use:

Objective-C: 

[AATSDK getNativeAdWithPlacement:self.nativeAdPlacement];
Swift: 
AATSDK.getNativeAd(placement: nativeAdPlacement)

NativeAdFromPlacement.png

The method returns a native ad, which contains all the assets of a native ad. This object represents a native ad from a certain ad network.

Retrieve the native assets from the AATKit

These so called native assets can be used to assemble your native ad, according to your app's look and feel. The following image shows an example native ad and the corresponding AATKit methods for retrieving each asset.

native In-Feed example

AATKit_native_ad_interface.png

In order to assemble your native ad, it's common to create one or more xib files that contains graphical elements like a UIImageView, UILabels, and a UIButton. These elements are filled with the native assets at runtime.

Xib_Example.png

native Banner example

AATKit_native_ad_interface_banner.png

Instead of:

Objective-C: 

#!objective-c
self.nativeTitleLabel.text = [AATKit getNativeAdTitle:ad];
self.nativeBodyLabel.text = [AATKit getNativeAdDescription:ad];
Swift: 
#!swift
nativeTitleLabel.text = AATKit.getNativeAdTitle(nativeAd)
nativeBodyLabel.text = AATKit.getNativeAdDescription(nativeAd)

use:

Objective-C: 

#!objective-c
self.nativeTitleLabel.text = [AATSDK getNativeAdTitleWithNativeAd:self.nativeAd];
self.nativeBodyLabel.text = [AATSDK getNativeAdDescriptionWithNativeAd:self.nativeAd];
Swift: 
#!swift
nativeTitleLabel.text = AATSDK.getNativeAdTitle(nativeAd: nativeAd)
nativeBodyLabel.text = AATKit.getNativeAdDescription(nativeAd)

Instances of UIImages have to created by using the URL provided by the AATKit.

Example:

Instead Of:

Objective-C: 

#!objective-c
NSString *mainImageURL   = [AATKit getNativeAdImageURL:nativeAd];
NSData  *mainImageData   = [[NSData alloc] initWithContentsOfURL:[NSURL URLWithString:mainImageURL]];
UIImage *mainImage       = [UIImage imageWithData:mainImageData];
Swift: 
#!swift
let mainImageURL = AATKit.getNativeAdIconURL(nativeAd)
guard let urlString = mainImageURL,
    let url = URL(string: urlString) else {
        return
}
guard let data = try? Data(contentsOf: url),
    let image = UIImage(data: data) else {
    return
}
DispatchQueue.main.async {
    imageView.image = image
}

Use:

Objective-C: 

#!objective-c
NSString *mainImageURL   = [AATSDK getNativeAdImageUrlWithNativeAd:self.nativeAd];
NSData  *mainImageData   = [[NSData alloc] initWithContentsOfURL:[NSURL URLWithString:mainImageURL]];
UIImage *mainImage       = [UIImage imageWithData:mainImageData];
Swift: 
#!swift
let mainImageURL = AATSDK.getNativeAdImageUrl(nativeAd: nativeAd)
guard let urlString = mainImageURL,
    let url = URL(string: urlString) else {
        return
}
guard let data = try? Data(contentsOf: url),
    let image = UIImage(data: data) else {
    return
}
DispatchQueue.main.async {
    imageView.image = image
}

Please note: When using a UITextView instead of a UILabel, make sure that editing is disabled on this element. Otherwise, a click on the UITextView instance might not be recognised by the ad network SDKs. You can do this in your interface builder:

Screen Shot 2016-06-29 at 15.12.35.png

Displaying an ad and Tracking view and ViewController

When assembling your native ad, it's also necessary to provide a tracking view to the native ad and a view controller.

Instead of:

Objective-C: 

#!objective-c
[AATKit setViewController:self forNativeAd:nativeAd];
Swift: 
#!swift
AATKit.setViewController(self, for: nativeAd)

Use:

Objective-C: 

#!objective-c
  // call this method to notify AATKit that a new controller will appear
 [AATSDK controllerViewWillAppearWithController:self];

// call this method to notify AATKit that a controller will disappear
 [AATSDK controllerViewWillDisappearWithController:self];
Swift: 
#!swift
    // call this method to notify AATKit that a new controller will appear
    AATSDK.controllerViewWillAppear(controller: self)

    // call this method to notify AATKit that a controller will disappear
    AATSDK.controllerViewWillDisappear(controller: self)

A view controller is used by the different ad networks in order to show a larger ad, or something alike when a click is registered on the native ad.

Tracking view: A tracking view is a UIView instance that is used by the ad network to track impressions and clicks. This means, the instance is checked on runtime whether it's visible on the screen and an impression is counted accordingly. A click is also registered on the instance provided, but doesn't have to be a UIButton (sub class of UIView) in order for the click to be registered. It's up to you to decide whether the tracking is big (the whole UIView) or small (a small button). Keep in mind that the ad networks track impressions based on a few conditions being met. A tracking view has to be visible for at least a few seconds on the screen (usually 1-2 seconds), plus a larger portion of the UIView instance has to be visible (usually ~50% of the view has to be visible). Tracking an impression and registering clicks is thus completely dependent on a tracking view being assigned to the native ad that has been provided by the AATKit.

#!Swift
static func attachNativeAdToLayout(nativeAd: AATNativeAdData, layout: UIView,  mainImageView: UIView?, iconView: UIView?, ctaView: UIView?)

Example:

Instead of:

Objective-C: 

#!objective-c
[AATKit setTrackingView:adView forNativeAd:nativeAd mainImageView:imageView iconView:iconView];
Swift: 
#!swift
AATKit.setTrackingView(adView, for: nativeAd, mainImageView: imageView, iconView: iconView)

Use:

Objective-C: 

#!objective-c
     [AATSDK attachNativeAdToLayoutWithNativeAd:self.nativeAd
                                                layout:self.containerView
                                        mainImageView:self.mainImageView
                                             iconView:self.iconImageView
                                              ctaView:self.ctaLabel];
Swift: 
#!swift
AATSDK.attachNativeAdToLayout(nativeAd: nativeAd,
                                             layout: nativeAdContainerView,
                                             mainImageView: self.adMainImageView,
                                             iconView: self.adIconImageView,
                                             ctaView: self.adCTALabel)

The tracking view also must be removed from the native ad, when the native ad isn't needed anymore or replaced. 

#!swift
func detachNativeAdFromLayout(nativeAd: AATNativeAdData)

Example:

Instead of:

Objective-C: 

#!objective-c
[AATKit removeTrackingViewForNativeAd:self.nativeAd];
Swift: 
#!swift
AATKit.removeTrackingView(for: nativeAd)

Use:

Objective-C: 

#!objective-c
[AATSDK detachNativeAdFromLayoutWithNativeAd:self.nativeAd];
Swift: 
#!swift
AATSDK.detachNativeAdFromLayout(nativeAd: nativeAd)

Ad space counting

Since the assembled native is now completely in the hands of the programmer, displaying also has to be done programmatically without involving the AATKit. Through this, the AATKit is NOT able to count ad spaces on it's own. Therefore, the programmer has to communicate when a native ad is supposed to be displayed. This desire to show an ad is called an ad space by AddApptr. Communicating and creating an ad space is done via: 

#!objective-c
func reportAdSpaceForPlacement(placement: AATPlacement)
Example:

Instead of:

Objective-C: 

#!objective-c
[AATKit appHasAdSpaceForNativePlacement: nativeAdPlacement];
Swift: 
#!swift
AATKit.appHasAdSpace(forNativePlacement: nativeAdPlacement)
Use:

Objective-C: 

#!objective-c
[AATSDK reportAdSpaceForPlacementWithPlacement:self.nativeAdPlacement];
Swift: 
#!swift
AATSDK.reportAdSpaceForPlacement(placement: placement)

WARNING If ad spaces are not communicated to the AATKit, the statistics for ad spaces can NOT be shown in the AddApptr dashboard.

Additional information

Retrieve the ad network that serves the native ad

In order to comply to the native ad guidelines of various ad networks, it is possible to retrieve the ad network that services a native ad. For this, the following method can be used. 

#!swift
func getNetwork() -> AATAdNetwork

The following is an excerpt of the enumeration 'enum AATAdNetwork' and shows only the ad networks that are currently supported for serving native ads. 

#!objective-c
enum AATAdNetwork {
    case ADMOB
    case APPLOVIN
    case APPNEXUS
    case FACEBOOK
   ...
};

Example:

Instead of:

Objective-C: 

#!objective-c
[AATKit getNativeAdNetwork: placement];
Swift: 
#!swift
AATKit.getNativeAdNetwork(nativeAd)

Use:

Objective-C: 

#!objective-c
[self.nativeAd getNetwork];
Swift: 
#!swift
nativeAd.getNetwork()

Sizes of the main image and icon

The programmer is supposed to create a UIImage instances, download the native images and get any image dimension through this instance.

Manual and automatic loading of a native ad

Loading a native ad has to be done manually by calling reloadPlacement on the AATKit class. Native ads do NOT support automatic loading. This is due to the fact that it's possible to load multiple native ads via one placement at the same time. This behaviour is new, compared to banner and fullscreen placement which can only hold one ad temporarily. A warning method is logged to the console if the method startAutoReload is called with a native placement on the AATKit.

Frequency capping of native ads

If you want to use frequency capping for native ads, it's necessary to use the method following method in order to ask the AATKit whether the frequency capping is currently reached and act accordingly. 

#!swift
 func isFrequencyCapReachedForPlacement(placement: AATPlacement) -> Bool
Frequency capping is supposed to limit the display of ads within certain boundaries, like 'per session', or 'once an hour'. Since the programmer can access the native ad before actually displaying it, he can also hold multiple native ads and display them as desired. The AATKit is unable to prevent displaying native ads, which is why the AATKit cannot ensure that the frequency capping is satisfied. In order to provide a solution, the programer has to ask the AATKit whether any, frequency capping is reached and prevent displaying a native ad accordingly.

Get the amount of native ads that are currently loading

In order monitor how many native ads are currently loading on a given placement the following method can be used:

#!swift
    func currentlyLoadingNativeAdsOnPlacement(placement: AATPlacement) -> Int
This method can be used in order to manage the request interval of native ads from a given placement.

Get the app rating if a native ad advertises an app

Some native ads do advertise apps on the app store. In that case they might come with a rating you want to display. In order to do that the rating value and scale is provided. The rating struct can be retrieved via: 

#!swift
func getNativeAdRating(nativeAd: AATNativeAdData) -> AATNativeAdRating?

The rating struct: 

#!swift
@objc
public class AATNativeAdRating: NSObject {
    let value: Double
    let scale: Double
}

Native Ad assets accessor methods

Native ads and their assets can be request via the AATKit header - AATKit.h. The following methods are available:

#!swift
func getNativeAd(placement: AATPlacement) -> AATNativeAdData?
* This method returns a native ad that has been loaded via the placement provided.

#!swift
func getNativeAdTitle(nativeAd: AATNativeAdData) -> String?
* get the title of a native ad

#!swift
func getNativeAdDescription(nativeAd: AATNativeAdData) -> String?
* getNativeAdDescription get the description body of a native ad

#!swift
func getNativeAdImageUrl(nativeAd: AATNativeAdData) -> String?
* getNativeAdImageURL get the url of the main ad image. Downloading the image have to be handled by the publisher. NOTE: The URL may be an HTTP URL, an HTTPS URL or a local File URL.

#!swift
 func getNativeAdIconUrl(nativeAd: AATNativeAdData) -> String?
* getNativeAdIconURL get the url of the ad icon image. Downloading the image have to be handled by the publisher. NOTE: The URL may be an HTTP URL, an HTTPS URL or a local File URL.

#!swift
func getNativeAdCallToAction(nativeAd: AATNativeAdData) -> String?
  • getNativeAdCallToAction get the call to action string

#!swift
func attachNativeAdToLayout(nativeAd: AATNativeAdData, layout: UIView, mainImageView: UIView?, iconView: UIView?, ctaView: UIView?)
* Each native ad have to get a tracking view assigned. This tracking view is necessary to detect impressions and clicks on the native ad. Passing of proper icon and main image views is necessary for native ads from some ad networks to work.

#!swift
func detachNativeAdFromLayout(nativeAd: AATNativeAdData)
* Remove the tracking view, which is required by some ad networks.

#!swift
func getNativeAdBrandingLogo(nativeAd: AATNativeAdData) -> UIView?
* returns a special logo (url string) that is required to be displayed by some ad networks. This logo is supposed to mark the respective native ad as being from a certain ad network. NOTE: The URL may be an HTTP URL, an HTTPS URL or a local File URL.

#!swift
func getNativeAdAdvertiser(nativeAd: AATNativeAdData) -> String?
  • returns the name of a certain advertiser. This field is mandatory in certain ad networks, like Flurry.

#!swift
func isNativeAdExpired(nativeAd: AATNativeAdData) -> Bool
func isNativeAdReady(nativeAd: AATNativeAdData) -> Bool
* check whether a native ad is ready or expired. Some ad networks do offer distinct methods. If they don't one is the inverse of the other.

#!swift
func reportAdSpaceForPlacement(placement: AATPlacement)
* This method is supposed to be called by the publisher when he intents to display a native ad. The intention of showing an ad is called an adSpace in AddApptr terms. For banner this is the case when the corresponding load method called, because loading leads to an inevitably display of this ad. For fullscreen ads, the intention of showing and interstitial is expressed by calling the showPlacement method (fullscreen only). When it comes to native ads, the intention of displaying an ad cannot be derived from the normal workflow of the ad. Even when the publisher prepares an ad, i.e. fill his UI - container with native assets, it doesn't mean that the native ad is going to be displayed. It can mean that, but it doesn't have to, it depends on how to publisher is going to use the native ad. Hence, for native ads we're in a very different scenario. Since we do want ad spaces to be counted for our statistics, we need some mechanism that allows the AATKit to count ad spaces. For that reason, we decided to offer a method (appHasAdSpaceForNativePlacement) to express and communicate that the app does now have "free" ad space available, which the publisher would like to have filled. Calling this method should be done as part of the normal workflow, independent of whether a native ad is actually available or not. This would express the intent to display an ad and whether the ad space can be filled is the responsibility of the AATKit. The method is currently built in such a way, that the it also accepts a reference to a container instance. When a container instance is passed in, the implementation figures out to which placement the container belongs and counts the ad space accordingly.

#!swift
func currentlyLoadingNativeAdsOnPlacement(placement: AATPlacement) -> Int
* returns the amount of native ads that are currently loading on a particular placement.

#!swift
 func getNativeAdRating(nativeAd: AATNativeAdData) -> AATNativeAdRating?
* this method returns the rating struct of a native ad. If no rating struct is available, an empty one is returned.

Listening to statistics events

AATStatisticsDelegate is an optional delegate you can implement if you need to get notified about statistics events. and pass it to placement while creating it using this method 

func createNativeAdPlacement(name: String,
                            supportsMainImage: Bool,
                            statisticsListener: AATStatisticsDelegate? = nil) -> AATPlacement?

for more info about it please refer to AATStatisticsDelegate Guide

SampleApp

Updated