iOS Native Ad

AdFalcon SDK aims to make native ads implementation in your app a straightforward process where you control the look and feel, design and placement of the ad while AdFalcon SDK handles the rest of the operations needed to display the ad and process impressions and clicks successfully.

When loading native ads, AdFalcon SDK returns a native ad object with the ad’s assets, and the app itself is responsible for displaying the native ad by providing a template UIView that lays out the native ad assets in the desired design and look and feel. This process is achieved by mapping the different UIViews (icon, title, description…etc.) in the template to the native ad assets.

The sections below provide a step-by-step guide for native ad implementation.

Creating Native Ad Template View

In this step, you create your native ad template view, this template must extend UIView and adopt ADFNativeAdTemplate Protocol.

1. Create Native Ad Template View Layout

The native ad template view consists of multiple UIViews, these UIViews are mapped to the native ad assets. You should include in the template only the native ad assets that are needed as per the desired design.

Some examples for native ad templates are shown below.

image005

You can state what native ad assets are requested by including them in the native ad template view. AdFalcon will only return native ads that include the requested assets as per the below rules:

  • Required Assets

Your native ad must display AdChoices view and at least one of the assets below otherwise it will be considered as invalid template:

  • Icon
  • Title
  • MainAsset

AdFalcon will only return ads which contain all the required assets included in the native ad template

  • Optional Assets

All remaining native ad asset types are optional.

The template may include one or more of the optional assets or none at all as per the desired design.

The returned native ad may or may not include any of the requested optional assets; i.e. the optional native ad assets will only be returned when available.

If a native ad response does not contain any of the optional assets, the SDK will hide its associated view.

The below table illustrates all the supported native ad assets which can be included in the template view:

Asset Required View Type Description
AdChoices Yes UIView An AdChoices icon must be displayed in your ad to enable the user to learn about interest-based advertising.

The SDK will decide when it is needed to display the icon and will also handle the tap event on the view by opening an opt-out page in the browser.

Parameters: The size of the view: 20×20.

You must place the view in any one of the four corners of the ad template; upper right hand corner is recommended.

Title At least one of Title, Icon or MainAsset must be included UILabel String representation of the native ad, which could be the name of the product or the service being advertised.
Parameters: Maximum title length. The Title UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.It is recommended that the UILabel is laid out to display at least 25 characters.Only native ads with title assets whose length is less than the requested maximum title length will be returned.
Icon At least one of Title, Icon or MainAsset must be us included UIImageView A squared image that shows the icon of the product, service, brand, … etc.
Parameters: Minimum width and height. The Icon UIImageView is used to infer the minimum width and height, unless it is explicitly set while binding the template view to the native ad assetRecommended minimum width and height of the Icon UIImageView is 50×50.Only native ads with icon assets whose width and height is less than the requested minimum icon width and height will be returned.
MainAsset At least one of Title, Icon or MainAsset must be included UIView The Native Ad main asset can be one of the below types:

·         Image

·         XHTML (HTML+JavaScript)

·         Video

The MainAsset is a UIView which is used as a container view for the actual native ad main asset. The SDK will automatically create the adequate UIView type that match the native ad main asset.

Parameters: Minimum width and height. The Main Asset UIView is used to infer the minimum width and height, unless it is explicitly set while binding the template view to the native ad asset

The main asset UIView width and height aspect ratio should always be W/H=1.91. It is recommended to use 320×167 points.

Only native ads with main assets whose width and height is greater than the requested minimum main asset width and height will be returned.

Sponsored No UILabel “Sponsored By” message where the response should contain the brand name of the sponsor.

Parameters: Maximum sponsored length. The Sponsored UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 10 characters.

Description No UILabel Descriptive text associated with the product or the service being advertised.

Parameters: Maximum description length. The Description UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 100 characters.

Star Rating No UIImageView Consists of five stars, which represents the rating of an app.

Parameters: Minimum width and height. The Star Rating UIImageView is used to infer the minimum width and height, unless it is explicitly set while binding the template view to the native ad asset

Recommended minimum width and height for the Star Rating UIImageView is to follow aspect ratio of W/H=5 such as 100×20.

Likes No UILabel Number of social ratings or “likes” of the product being offered to the user.

Parameters: Maximum likes length. The Likes UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 20 characters.

Downloads No UILabel Number of downloads of the product being offered to the user.

Parameters: Maximum downloads length. The Downloads UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 25 characters.

Price No UILabel Price for product / app / in-app purchase. Value should include currency symbol in localized format.

Parameters: Maximum   Price length. The Price UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 20 characters.

Sale price No UILabel Sale price that can be used together with price to indicate a discounted price compared to a regular price. Value should include currency symbol in localized format.

Parameters: Maximum Sale price length. The Sale price UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 15 characters.

Phone No UILabel Formatted string that represents the phone number.

Parameters: Maximum phone length. The Phone UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 20 characters.

Address No UILabel Address data.

Parameters: Maximum Address length. The Address UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 100 characters.

Description 2 No UILabel Additional descriptive text associated with the product or service being advertised.

Parameters: Maximum Address 2 length. The Address 2 UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 100 characters.

Display URL No UILabel Display URL data.

Parameters: Maximum display URL length. The Display URL UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 50 characters.

Call to action “CTA” No UIButton Descriptive text describing a ‘call to action’ button for the destination URL such as open, register, install.

Parameters: Maximum CTA length. The CTA UIButton is used to infer the maximum label length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the label of button is laid out to display at least 20 characters.

Views No UILabel Number of times the ad has been viewed.

Parameters: Maximum Views length. The Views UILabel is used to infer the maximum title length, unless it is explicitly set while binding the template view to the native ad asset.

It is recommended that the UILabel is laid out to display at least 20 characters.

2. Adopting ADFNativeAdTemplate Protocol

ADFNativeAdTemplate protocol is defined as:

@class ADFNativeAdBinder;
@protocol ADFNativeAdTemplate 

 @required
 -(void) bindViews:(ADFNativeAdBinder*) binder;
 -(CGSize) sizeForWidth:(CGFloat) width;

 @optional
 -(void) renderExtraData:(NSMutableArray*) extraData;
 @end

Below is a description of ADFNativeAdTemplate protocol’s required methods:

  • bindViews: (ADFNativeAdBinder*) binder:

This method is used to connect your native ad template’s views to their corresponding native ad assets (title view, main image, icon, etc.).

You should at minimum bind one of the mandatory native ad assets (icon, title or MainAsset) depending on the native ad template design in-place.

Optionally, the binder allows setting additional parameters of the native ad assets such as the width and height of the icon and image, the maximum length of the title otherwise the binder will infer this information from the UIView’s properties.

Binding views to native ad assets is achieved using the binder object of ADFNativeAdBinder class by calling the appropriate binding method (setIconImageView, setTitleLabel, setMainAssetView and setExtraDataView).

It is important to note that optional native assets are bound using the setExtraData method where each asset is represented by a Data ID such as:

  • ADF_DATA_ID_DESC for native ad description
  • ADF_DATA_ID_CTA for native ad click-through action label (install, open…etc.)
  • ADF_DATA_ID_RATING for native ad product rating

Please refer to Appendix 6 ADFNativeAdBinder for more details.

Below is a sample bindViews method implementation:

-(void) bindViews:(ADFNativeAdBinder*) binder
{
[binder setIconImageView:self.iconImageView];
[binder setAdChoicesView:self.daaView];
[binder setTitleLabel:self.titleLabel];
[binder setMainAssetView:self.adImage];
[binder setExtraDataView:self.sponsoredLabel dataID:ADF_DATA_ID_SPONSORED];
[binder setExtraDataView:self.descriptionLabel dataID:ADF_DATA_ID_DESC];
[binder setExtraDataView:self.ratingImage dataID: ADF_DATA_ID_RATING];
[binder setExtraDataView:self.actionButton dataID: ADF_DATA_ID_CTA];
}

  • sizeForWidth: (CGFloat) width:

This method is used to calculate the size of your native ad template view for the given parent view width or screen width.  This is used while inferring the different attributes of your native ad views such as maximum length of your text views, and width and height of your image views.

-(CGSize)sizeForWidth:(CGFloat)width
{
    return CGSizeMake(width, TEMPLATE_AD_HEIGHT);
}

Requesting a Native Ad

  1. Add ADFNativeAd to the view controller header file
    1. Import AdFalconSDK in your .h file .
    2. Declare ADFNativeAd instance.

Below is an example of how the header should look like:

@import "AdFalconSDK";

@interface AdFalcon_iOS_SDK_iPhone_SampleViewController: UIViewController{
     ADFNativeAd * nativeAd;
}

 

  1. Add the following code snippet to viewDidLoad method
	nativeAd = [[ADFNativeAd alloc] init ];

	//Enable or disable testing mode
	nativeAd.testing = NO;

	//Initialize native ad and pass your site ID, your template and view controller
	[nativeAd

	   initializeWithSiteID:@"Your Site ID"

             	adTemplateClass:[your_ad_template class]

             	viewController:self

	];

	//Add AdFalcon view
	[self.view addSubview:nativeAd];

	//Load ad from the AdFalcon service
	[nativeAd loadAdWithParams:nil];

Note 1: It is highly recommended that you provide all available targeting information such as gender, location, content category to your ad request in order to receive the best ad that meets the criteria of your audience and maximize your return. This can be done by filling the params object in loadAdWithParams method. Please refer to Appendix 6 ADFTargetingParams for all the available targeting parameters.

Note 2: In case you are overriding the [UIViewController loadView] to programmatically draw your view, ensure that AdFalcon view is initialized after completing loading the UIViewController’s view.

Note 3: Ensure testing parameter is set to No before uploading your app to Apple store.

(Optional) Tracking Ad Lifecycle Events – ADFNativeAdDelegate Protocol

AdFalcon iOS SDK provides ability to track Ad lifecycle events. Follow the procedure below to subscribe to the various Ad lifecycle events

  • Import the ADFADViewDelegate.h protocol to your header as the below:
@interface viewController: UIViewController {
}
  • Add the below ADFADViewDelegate’s methods to your source file as the below
-(void) nativeAdDidLoad:(ADFNativeAd*) nativeAd
{
//Do something here
}

-(void) nativeAd:(ADFNativeAd*) nativeAd  didFailWithErrorCode:(int) code message:(NSString*) message
{
//Do something here
}

Assign your delegate object to ADFAdView object as the below:

nativeAd.delegate = self;