Integrate a native Ad
 into your project
 (Native ads are available starting version 2.61.0)

Index:

1. Project Setup
2. AATKit Initialisation
3. Banner Integration
4. Fullscreen Integration
5. Native Ads Integration
6. Native Ads Integration - special ad network characteristics
7. Promo Screen
8. Sample
9. Disable App Transport Security (ATS)
10. Advanced Features
11. Targeting
12. Rewarded Video
13. Frequency Capping
14. Header documentation
15. Important Remarks
16. AATKit's Size within your app
17. What is an AdSpace?
18. Network-specific Information
19. Statistics Delegate
20. Listen to impression level information
21. AATKit AdMob custom events adapter (>= 2.77.x)

AATKit Changelogs

Ad network native guidelines

Each app needs to conform to the respective ad network guidelines. AddApptr only provides native assets, whose layout is determined by the publisher.

Flurry native ads guidelines

Facebook native ads guidelines

InMobi guidelines are currently not available.

AdMob native ad guidelines

MoPub native ad guidelines

Code Sample

General information

1. Create a native placement

A native placement is created like this:

#!objective-c
+ (id)createNativeAdPlacement:(NSString *) placementName supportsMainImage:(BOOL) supportsMainImage;

Example:

Objective-C:

#!objective-c
[AATKit createNativeAdPlacement:@"NativeAdPlacement" supportsMainImage: YES];

#!swift
AATKit.createNativeAdPlacement(@"NativeAdPlacement", supportsMainImage: true)

In order to work with the AddApptr backend, placement names must be constant at runtime, i.e. they shouldn't change on each app start. Note that any placement instance is supposed to be reused. Do not create a placement instance for each fullscreen ad you want to display. We've encountered issues where publisher did create hundredths of placements at runtime, each with an auto generated name. KEEP THE AMOUNT OF PLACEMENTS LOW. Each location where fullscreen ads should be displayed, can be handled by a single placement instance.

The fullscreen name must not match to the following regular expression:

#!regex

/[^()0-9a-z-_\.\/]/i

2. Start loading native ads

Native ads have to be loaded via:

#!objective-c
+ (bool) reloadPlacement:(id) placement;

Example:

Objective-C:

#!objective-c
[AATKit reloadPlacement:self.nativePlacement];

#!swift
AATKit.reload(nativePlacement)

3. Retrieve a 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.

#!objective-c
+ (id)getNativeAdForPlacement:(id)placement;

Objective-C: Example:

#!objective-c
[AATKit getNativeAdForPlacement:placement]

#!swift
AATKit.getNativeAd(for: placement)

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. Each native ad is autoreleased when retrieving it from the AATKit. The native ad has to be retained by your application, even after extracting the assets. This is, because after the native ad has been displayed, it's tracking view must be removed from the container.

4. Retrieve the native assets from the AATKit and assemble your native ad

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

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.

native Banner example

Objective-C:

#!objective-c
self.nativeTitleLabel.text = [AATKit getNativeAdTitle:ad];
self.nativeBodyLabel.text = [AATKit getNativeAdDescription:ad];

#!swift
nativeTitleLabel.text = AATKit.getNativeAdTitle(nativeAd)
nativeBodyLabel.text = AATKit.getNativeAdDescription(nativeAd)

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

Example:

Objective-C:

#!objective-c
NSString *mainImageURL   = [AATKit getNativeAdImageURL:nativeAd];
NSData  *mainImageData   = [[[NSData alloc] initWithContentsOfURL:[NSURL URLWithString:mainImageURL]] autorelease];
UIImage *mainImage       = [UIImage imageWithData:mainImageData];

#!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
}

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:

5. Displaying an ad and Tracking view + ViewController

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

View controller:

#!objective-c
+ (void) setViewController:(UIViewController*) con forNativeAd:(id) nativeAd;

Example:

Objective-C:

#!objective-c
[AATKit setViewController:self forNativeAd:nativeAd];

#!swift
AATKit.setViewController(self, for: nativeAd)

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.

#!objective-c
+ (void) setTrackingView: (UIView*) trackingView forNativeAd: (id) nativeAd mainImageView: (UIView*) mainImageView iconView:(UIView*) iconView;

Example:

Objective-C:

#!objective-c
[AATKit setTrackingView:adView forNativeAd:nativeAd mainImageView:imageView iconView:iconView];

#!swift
AATKit.setTrackingView(adView, for: nativeAd, mainImageView: imageView, iconView: iconView)

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

#!objective-c
+ (void) removeTrackingViewForNativeAd:(id) nativeAd;

Example:

Objective-C:

#!objective-c
[AATKit removeTrackingViewForNativeAd:self.nativeAd];

#!swift
AATKit.removeTrackingView(for: nativeAd)

6. 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
+ (void) appHasAdSpaceForNativePlacement: (id) placement;

Objective-C:

#!objective-c
[AATKit appHasAdSpaceForNativePlacement: nativeAdPlacement];

#!swift
AATKit.appHasAdSpace(forNativePlacement: nativeAdPlacement)

7. Additional information

Retrieve the ad network that serves a 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.

#!objective-c
+ (enum AATKitAdNetwork) getNativeAdNetwork: (id) nativeAd;

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

#!objective-c
enum AATKitAdNetwork {
    AATFacebook,
    AATFlurry,
    AATInmobi,
   ...
};

Example:

Objective-C:

#!objective-c
[AATKit getNativeAdNetwork: placement];

#!swift
AATKit.getNativeAdNetwork(nativeAd)

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.

#!objective-c
+ (bool) isFrequencyCapReachedForNativePlacement: (id) placement;

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:

#!objective-c
+ (NSUInteger) currentlyLoadingNativeAdsOnPlacement:(id) 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:

#!objective-c
+ (struct AATKitNativeAdRating) getNativeAdRating: (id) nativeAd;

The rating struct:

#!objective-c
struct AATKitNativeAdRating {
    float value;
    int scale;
    bool hasRating;
};

Native ad type

The method + (enum AATKitNativeAdType) getNativeAdType: (id) nativeAd is currently not helpful. It's supposed to provide means to distinguish between various native ad types in future. However, based on the currently integrated ad networks this information is not present in each, and hence mainly implemented with default values.

Native Ad assets accessor methods

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

#!objective-c
+ (id) getNativeAdForPlacement: (id) placement;

#!objective-c
+ (NSString*)   getNativeAdTitle: (id) nativeAd;

#!objective-c
+ (NSString*)   getNativeAdDescription: (id) nativeAd;

#!objective-c
+ (NSString*)   getNativeAdImageURL: (id) nativeAd;

#!objective-c
+ (NSString*)   getNativeAdIconURL: (id) nativeAd;

#!objective-c
+ (NSString*)   getNativeAdCallToAction: (id) nativeAd;

• getNativeAdCallToAction get the call to action string

#!objective-c
+ (void) setTrackingView: (UIView*) trackingView forNativeAd: (id) nativeAd mainImageView: (UIView*) mainImageView iconView:(UIView*) iconView;

#!objective-c
+ (void) setViewController: (UIViewController*) con forNativeAd: (id) nativeAd;

• assign a viewController for the native ad in case it gets clicks. Some ad networks do push a viewController in that scenario.

#!objective-c
+ (enum AATKitAdNetwork) getNativeAdNetwork: (id) nativeAd;

• request the ad network enum of a certain container, i.e. of which ad network ad is contained in the container.

#!objective-c
+ (void) removeTrackingViewForNativeAd: (id) nativeAd;

#!objective-c
+ (NSString*)   getNativeAdBrandingLogo: (id) nativeAd;

#!objective-c
+ (NSString*)   getNativeAdAdvertiser: (id) nativeAd;

• returns the name of a certain advertiser. This field is mandatory in certain ad networks, like Flurry.

#!objective-c
+ (bool) isNativeAdExpired: (id) nativeAd;
+ (bool) isNativeAdReady: (id) nativeAd;

#!objective-c
+ (void) appHasAdSpaceForNativePlacement: (id) placement;

#!objective-c
+ (NSUInteger) currentlyLoadingNativeAdsOnPlacement:(id) placement;

#!objective-c
+ (struct AATKitNativeAdRating) getNativeAdRating: (id) nativeAd;

#!objective-c
+ (enum AATKitNativeAdType) getNativeAdType: (id) nativeAd;

#!objective-c
+ (enum AATKitAdNetwork) getNativeAdNetwork: (id) nativeAd;

Listening to statistics events

AATKitStatisticsDelegate 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

+ (nullable NSObject<AATKitPlacement>*)createNativeAdPlacement:(nonnull NSString*)placementName
                                             supportsMainImage:(BOOL)supportsMainImage
                                         andStatisticsDelegate:(nullable NSObject <AATKitStatisticsDelegate>*)statisticsDelegate

for more info about it please refer to AATKitStatisticsDelegate Guide

Click Here To Provide Feedback

back (Fullscreen Integration)

next (Native Ads Integration - special ad network characteristics)