Skip to content

Cookbook

This cookbook does not describe how to use ADvantage nor how to program in Objective-c. It only contains suggestions and explanations for some common use cases.

How to enable/disable sensitive targeting parameters?

To enable/disable the semi-sensitive targeting parameters such as, device network type and device advertising identifier use the following code snippet:

//Disable the semi-sensitive targeting parameters!
advantage.permissions.setSensitiveTargetingParametersAllowed(false)

//Disable the semi-sensitive targeting parameters!
[advantage.permissions setSensitiveTargetingParametersAllowed:NO];

Note

Please note that sending sensitive targeting parameters is true by default.

How to enable/disable sensitive targeting parameters?

To enable/disable the semi-sensitive targeting parameters such as, device network type and device advertising identifier use the following code snippet:

//Disable the semi-sensitive targeting parameters by setting
advantage.permissions.sensitiveTargetingParametersAllowed = false

//Disable the semi-sensitive targeting parameters by setting
[advantage.permissions setSensitiveTargetingParametersAllowed:false];

Note

Please note that sending sensitive targeting parameters are enabled by default.

How to change cornerAd margins

Corner ad margin can be set using the following code snippet:

//Disable the semi-sensitive targeting parameters by setting
advantage.setCornerAdVerticalMargin(100)
advantage.setCornerAdHorizontalMargin(100)

//Disable the semi-sensitive targeting parameters by setting
[advantage setCornerAdVerticalMargin:100];
[advantage setCornerAdHorizontalMargin:100];
How to set the maximum dimension for the inline banner?

You can easily set maximum ad space size that they want to show inside your app using the following code snippet:

//Advantage maximum ad space size set up which goes inside of the
//desired view controller initialization method(s), e.g. viewDidLoad()
let bannerSize = CGSize(CGFloat width, CGFloat height)
advantage.setMaxDimensionForBanner(bannerSize)

//Advantage maximum ad space size set up which goes inside of the
//desired view controller initialization method(s), e.g. - (void)viewDidLoad
CGSize dimension = CGSizeMake(CGFloat width, CGFloat height)
[self.banner setMaxDimensionForBanner:dimension];
How to use social advertisements (P2P)?

Bob 

//Initialize the ADvantage instance as usual
let advantage = ADvantage(bannerWithLicenseKey: "...")

// Set frame for your ad view
advantage.view.frame = CGRect(0, 0, 320, 50)

// Set delegate
advantage.delegate = self

// Implement the delegate method to receive a social ad
func advantage(_ advantage: ADvantage, didReceiveSocialAd target: String) {
    // Pass the given target to Alice...
}

Alice 

//Initialize the ADvantage instance...
let advantage = ADvantage(bannerWithLicenseKey: "...", siteId: "...", position: "...")

// Set frame for your ad view
advantage.view.frame = CGRect(0, 0, 320, 50)

// Set delegate
advantage.delegate = self

//Pass the Social target which is received from Bob's
//device to ADvantage instance and show the ad...
advantage.requestAd(withTarget: "...")

Bob 

//Initialize the ADvantage instance as usual
self.advantage = [[ADvantage alloc] initBannerWithLicenseKey:@"..."];

// Set frame for your ad view
[self.advantage.view setFrame:CGRectMake(0, 0, 320, 50)];

// Set delegate
[self.advantage setDelegate:self];

// Implement the delegate method to receive a social ad
- (void)advantage:(ADvantage *)advantage didReceiveSocialAd:(NSString *)target
{
// Pass the given target to Alice...
}

note

Please contact our sales team first, in order to enable the social advertising for your application.

How to integrate Banner with a specific ratio and percentage with height?

For having a solution based on ratio we need to first define the ratio parameters and we set the frame of ADvantage object based on our new CGRect property: 

//YourViewController.swift
let ADWidthRatio = 3
let ADHeightRatio = 1
let controllerView = self.view.frame

// Ratio Dimension
let adRect = CGRect(0, 0, controllerView.width, (controllerView..width*ADHeightRatio)/ADWidthRatio);
advantage.view.frame = adRect

If you are looking for a solution to use % of main view for width and height, you can easily use these codes: 

//YourViewController.swift
let ADWidthPercent = 1.0
let ADHeightPercent = 0.8
let controllerView = self.view.frame

// % width dimension
let adRect = CGRect(0, 0, controllerView.size.width*ADWidthPercent, controllerView.size.height*ADHeightPercent);
Please be aware that if your view is supporting landscape as well then you need to calculate it each time that your view is rotating, there are several solutions for that and here is a simple one. 
//YourViewController.swift

override func viewDidLayoutSubviews() {
    // % width dimension
    let adRect = CGRect(0, 0, self.view.frame.size.width*ADWidthPercent, self.view.frame.size.height*ADHeightPercent)

    // Ratio Dimension
    // let adRect = CGRect(0, 0, self.view.frame.size.width, (self.view.frame.size.width*ADHeightRatio)/ADWidthRatio)

    advantage.view.frame = adRect
}

For having a solution based on ratio we need to first define the ratio parameters and we set the frame of ADvantage object based on our new CGRect property: 

//YourViewController.m
#define ADWidthRatio 3
#define ADHeightRatio 1

// Ratio Dimension
self.adRect = CGRectMake(0, 0, self.view.frame.size.width, (self.view.frame.size.width*ADHeightRatio)/ADWidthRatio);
[self.ad.view setFrame:self.adRect];
If you are looking for a solution to use % of main view for width and height, you can easily use these codes: 
//YourViewController.m
#define ADWidthPercent 1.0
#define ADHeightPercent 0.8

// % width dimension
self.adRect = CGRectMake(0, 0, self.view.frame.size.width*ADWidthPercent, self.view.frame.size.height*ADHeightPercent);
[self.ad.view setFrame:self.adRect];

Please be aware that if your view is supporting landscape as well then you need to calculate it each time that your view is rotating, there are several solutions for that and here is a simple one. 

//YourViewController.m

- (void)viewDidLayoutSubviews{
    // % width dimension
    self.adRect = CGRectMake(0, 0, self.view.frame.size.width*ADWidthPercent, self.view.frame.size.height*ADHeightPercent);

    // Ratio Dimension
    // self.adRect = CGRectMake(0, 0, self.view.frame.size.width, (self.view.frame.size.width*ADHeightRatio)/ADWidthRatio);

    [self.ad.view setFrame:self.adRect];
}

How to integrate a sticky banner with variable height (dynamic banner)?

ADvantageLayoutType will be deprecated in the future iOS versions of ADvantage (current version before depreciation is 2.5.3.7) and later removed: 

typedef enum ADvantageLayoutType : NSUInteger {
    kADResponsiveLayout,
    kADDefaultLayout
} ADvantageLayoutType;
Before we complettely remove ADvantageLayoutType with it's values kADDefaultLayout and kADResponsiveLayout, we will have kADResponsiveLayout as default, which will be the case from the major version 2.5.5 . When you set a specific height for a banner, let's say 50px, some ads have the ability to update their height by calling updateLayout to show more content, which will also update the height of the native ad container automatically, which is your ADvantage instance. In these cases you can be informed by implementing the didUpdateLayoutTo delegate method. For example if you have a tab bar under your ADvantage view you need to move ADvantage up to avoid covering your tab bar with the ad.

func advantage(_ advantage: ADvantage, didUpdateLayoutTo rect: CGRect) {
    print("didUpdateLayoutTo \(NSStringFromCGRect(rect))")
}

- (void)advantage:(ADvantage *)advantage didUpdateLayoutTo:(CGRect)rect {
    NSLog(@"didUpdateLayoutTo %@",NSStringFromCGRect(rect));
}

Feature added in ADvantage 2.5.0 that will update the height automatically without the ad having to call didUpdateLayoutTo delegate method, however it will still be called to inform you. This feature can be controlled by setting the layoutType property of your ADvantage object, before requesting the ad. kADResponsiveLayout will be set by default from the SDK version 2.5.5 . It will retrieve the computed height of its ad creative and update the native ad container height once it's loaded and it will continue to monitor it and adapt if there are any changes.

The responsive layout will only affect ads in default state. In other words if the ad expands to fullscreen or a pop up, it will not be affected, as the ad itself should control its size in those cases.

This feature also supports the use of NSLayoutConstraints.

Possible use cases for kADResponsiveLayout:

1) init banner with 0 height

  • You can set the height of your container to 0px and add it to your view
  • Call requestAd
  • Ad loads, now you don't need to worry about setting the correct ad height, the SDK will calculate it and set it automatically
  • You will be notified by the didUpdateLayoutTo delegate

2) device rotation

  • You set the ad container width to the maximum width of the screen in portrait mode
  • Height is adjusted automatically when the ad has loaded like in the first use case
  • (You will be notified by the didUpdateLayoutTo delegate)
  • User rotates the device, you update the width to the landscape width (or let an NSLayoutConstraint handle it)
  • New ad height is calculated and set automatically
  • You will be notified by the didUpdateLayoutTo delegate
How to integrate an attention ad?

The attention ad was developed for interactive campaigns and to surprise the user in a positive way! This type of banner is usually fullscreen and transparent. While implementing you need to treat attention ad slightly different from other ads.

  • It's better to set the size of ADvantage object to 0, because after loading the ad, creative will call resize function automatically and will resize it to fullscreen.
  • You need to add an ADvantage object to the rootViewController, so the adttention ad can cover the whole view.

You can find some code sample here:

let advantage = ADvantage(bannerWithLicenseKey: "", siteId: "", position: "")
override func viewDidLoad() {
    super.viewDidLoad()
    advantage.view.frame = CGRect.zero
    advantage.delegate = self

    // Get rootViewController
    guard let rootVC = UIApplication.shared.keyWindow?.rootViewController else {
        //something went wrong
        return
    }

    rootVC.view.addSubview(advantage)

    advantage.requestAd()
}

- (void)viewDidLoad
{
    [super viewDidLoad];

    self.ad = [[ADvantage alloc] initBannerWithLicenseKey:self.licenseKey];
    [self.ad setSiteId: self.siteId];
    [self.ad setPosition: self.position];
    [self.ad.view setFrame: CGRectMake(0, 0, 0, 0)];

    self.ad.delegate = self;


    // Get rootViewController
    UIViewController *rootVC = [[[UIApplication sharedApplication] keyWindow] rootViewController];

    if (rootVC != nil) {
        UIViewController *vc = (UIViewController *)rootVC;
        [vc.view addSubview:self.ad.view];
    }

    [self.ad.permissions setInlineVideoAllowed:FALSE];

    [self.ad requestAd];
}
How to use dynamic banners inside of a tableview cell?

Showing an ADvantage object inside of a tableview cell is easy. If the ad needs to update its layout then the cell container also needs to adapt. Therefore you need to take care of the cell resize by implementing didUpdateLayoutTo callback delegate.

let advantage = ADvantage(bannerWithLicenseKey: "...", siteId: "...", position: "...")

func advantage(_ advantage: ADvantage, didUpdateLayoutTo rect: CGRect) {
    //Resize the cell number 2
    print("didUpdateLayoutTo \(NSStringFromCGRect(rect))")
    self.tableView.reloadRows(at: IndexPath(row: 2, section: 0), with: .fade)
}

-(CGFloat)tableView:(UITableView *)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath
{
    //Standard Height
    let height = 44;

    // Row 2 has ADvantage object and need to be set to the ADvantage height
    if(indexPath.row == 2)
    {
       height = advantage.view.frame.height;
        //Flag for relading set
       heightModified = true;
    }
    return height;
}

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{


    if(indexPath.row == 2)
    {
        let cell = tableView.dequeueReusableCell(withIdentifier: "adCell", for: indexPath)

        //check if cell is reloaded or loading for first time, if not don't need to add advantage to cell again.
        if (heightModified) {
            advantage.view.removeFromSuperview()
            cell.addSubview(advantage.view)
            heightModified = false;
        }
        return cell
    }
    else{
        let cell = tableView.dequeueReusableCell(withIdentifier: "cell", for: indexPath)
        return cell
    }
}

ADvantage *advantage = [[ADvantage alloc] initBannerWithLicenseKey:@"..." SiteId:@"..." Position:@"..."];

- (void)advantage:(ADvantage *)advantage didUpdateLayoutTo:(CGRect)rect {
    //Resize the cell number 2
    NSLog(@"didUpdateLayoutTo %@",NSStringFromCGRect(rect));
    [self.tableView reloadRowsAtIndexPaths:[NSArray arrayWithObject:[NSIndexPath indexPathForRow:2 inSection:0]] withRowAnimation:UITableViewRowAnimationFade];
}

-(CGFloat)tableView:(UITableView *)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath
{
    //Standard Height
    CGFloat height = 44;

    // Row 2 has ADvantage object and need to be set to the ADvantage height
    if(indexPath.row == 2)
    {
       height = self.advantage.view.frame.size.height;
        //Flag for relading set
       heightModified = TRUE;
    }
    return height;
}

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    UITableViewCell *cell ;

    if(indexPath.row == 2)
    {
        cell = [tableView dequeueReusableCellWithIdentifier:@"adCell" forIndexPath:indexPath];

        //check if the cell is reloaded or loading for first time, if not, you don't need to add advantage to cell again.
        if (heightModified) {
            [self.advantage.view removeFromSuperview];
            [cell addSubview:self.advantage.view];
            heightModified = FALSE;
        }


    }
    else{
        cell = [tableView dequeueReusableCellWithIdentifier:@"Cell" forIndexPath:indexPath];
    }

    return cell;
}
How to pre-fetching banners and removing from superView?

You may want to display or remove the ad depending on whether the ad has content or not. In some cases the "advantage:(ADvantage *)advantage didLoad:(AVLoadedState)state" delegate can be called without an ad being present like when the ad server doesn't deliver one. In these cases you can check the and react accordingly.

Here is a sample:

// Declare an Advantage instance
let advantage = ADvantage(bannerWithLicenseKey: "...", siteId: "...", position: "...")

override func viewDidLoad() {
    super.viewDidLoad()

    // Set frame for your Ad view
    advantage.view.setFrame(CGRect(0,0,320,50))

    // Set delegate
    advantage.delegate = self

    // Request for loading ad
    advantage.requestAd()
}

func advantage(_ advantage: ADvantage, didLoad state: AVLoadedState) {
    if (state == AVLoadedWithAd){
        // Add banner to the UI
        view.addSubview(advantage.view)
    } else {
        // Do something
        advantage.view.removeFromSuperview()
    }
}

// Declare an Advantage instance
ADvantage *advantage = [[ADvantage alloc] initBannerWithLicenseKey:@"..." SiteId:@"..." Position:@"..."];

- (void)viewDidLoad
{
    [super viewDidLoad];

    // Set frame for your Ad view
    [self.advantage.view setFrame:CGRectMake(0, 0, 320, 50)];

    // Set delegate
    [self.advantage setDelegate:self];

    // Request for loading ad
    [self.advantage requestAd];
}



- (void)advantage:(ADvantage *)advantage didLoad:(AVLoadedState)state{
    if( state == AVLoadedWithAd ){
        // Add banner to the UI
        [self.view addSubview: self.advantage.view];
    }
    if( state == AVLoadedWithoutAd ){
        NSLog(@"ADvantage Loaded without Ad" );
        [self.advantage.view removeFromSuperview];
    }
}
Pre-fetching interstitials

First load the interstitial, then display it. If a loadingPicture is set, it will be displayed until you call showInterstitial. You could use the splash screen of your app as the loadingPicture while the interstitial (or in this case the "preload") is loading.

let advantage = ADvantage(bannerWithLicenseKey: "...", siteId: "...", position: "...")

override func viewDidLoad() {
    super.viewDidLoad()

    // Set frame for your Ad view
    advantage.loadingPicture = "Default.png"

    // Set delegate
    advantage.delegate = self

    // Request for loading ad
    advantage.requestAd()
}

func advantage(_ advantage: ADvantage, didLoad state: AVLoadedState) {
    if (state == AVLoadedWithAd){
        view.showInterstitial()
    } else {
        //loaded without ad
    }
}

ADvantage *advantage = [[ADvantage alloc] initBannerWithLicenseKey:@"..." SiteId:@"..." Position:@"..."];

//YourViewController.m
- (void)viewDidLoad {
    [super viewDidLoad];
    // Set Loading Picture
    [self.advantage setLoadingPicture:@"Default.png"];

    // Set delegate
    [self.advantage setDelegate:self];

    // Request for loading ad
    [self.advantage requestAd];
}

- (void)advantage:(ADvantage *)advantage didLoad:(AVLoadedState)state {
    if( state == AVLoadedWithAd ){
        [self.advantage showInterstitial];
    } else {
        //loaded without ad
    }
}
Add and remove targeting for the advertisement

Important Note

Before you add targeting parameters please contact first your ad-serving partner. All of the keyword targeting parameters must be added to your ad server before you can use it and in some cases they must be in a special format like the profile targeting on the Adition ad server.

Add targeting to an ad request To target advertisement for specific user groups (i.e. age, sex,...) it is possible to transmit additional parameters to the ad server. The corresponding method has to be called before requesting an ad. The name and the value can be defined by you.

let advantage = ADvantage(bannerWithLicenseKey: "...", siteId: "...", position: "...")
.
.
advantage.addParameter("age", withValue: "20")
advantage.addParameter("sex", withValue: "male")
.
.
advantage.requestAd()

ADvantage *advantage = [[ADvantage alloc] initBannerWithLicenseKey:@"..." SiteId:@"..." Position:@"..."];
.
.
[advantage addParameter:@"age" withValue:@"20"];
[advantage addParameter:@"sex" withValue:@"male"];
.
.
[advantage requestAd];

For a working targeting it is required to send the ad provider a list of the key-value-pairs.

** Remove targeting from an ad request ** In some cases you maybe want to remove some targeting parameters which are sent to the ad server. Especially when you are reusing the ADvantage object.

advantage.removeParameter("sex")
.
.
advantage.requestAd()

[advantage addParameter:@"age"];
.
.
[advantage requestAd];

** Pre-defined ad server Parameters ** Here you can find a list of all pre-defined ad server parameters which ADvantage is able to send per default.

Custom URL Schemes

Before requesting an ad, you should call registerCustomUrlSchemes on your ADvantage instance and pass an NSArray containing NSStrings with your custom URL schemes.

Length of each custom url scheme MUST be greater than 3. The url scheme SHOULD NOT be equal to the registered plugins' protocol name (MRAID & ADvantage)

self.banner.registerCustomUrlSchemes(["my-app-id1", "my-app-id2"])

[self.banner registerCustomUrlSchemes:[NSArray arrayWithObjects:@"my-app-id1", @"my-app-id2", nil]];

If your ad use href like my-app-id1://, mraid.adopen, advantage.open with your custom registered url scheme, you will be notified with the following ADvantage callback:

func advantage(_ advantage: ADvantage, didCallUrlWithCustomUrlScheme url: URL) {...}

- (void)advantage:(ADvantage *)advantage didCallUrlWithCustomUrlScheme:(NSURL *)url {...}
ADvantage Permissions

With version 2.0, ADvantage introduces a new permission system.

Additionally, since iOS 10 you need to add the following keys to your Info.plist file, otherwise Apple will reject your binary. If an ad needs to access e.g. the Calendar or needs to save a picture, iOS will first display your defined message as an alert to ask the user for permission.

  • NSCalendarsUsageDescription
  • NSContactsUsageDescription
  • NSLocationWhenInUseUsageDescription
  • NSMotionUsageDescription
  • NSPhotoLibraryUsageDescription
  • NSPhotoLibraryUsageDescription
  • NSBluetoothPeripheralUsageDescription

By default all permissions are granted (TRUE) and you can cancel any of them with only one line of code for the specific permission:

advantage.permissions.isSmsAllowed = false
advantage.permissions.isTelAllowed = false
advantage.permissions.isCalendarAllowed = false
advantage.permissions.isStorePictureAllowed = false
advantage.permissions.isInlineVideoAllowed = false
advantage.permissions.isUserLocationAllowed = false
advantage.permissions.isRotationAllowed = false
advantage.permissions.isContactAllowed = false
advantage.permissions.isBluetoothAllowed = false
advantage.permissions.sensorsAllowed = false // Compass, Accelerometer, Gyroscope, Proximity, Pedometer, Barometer

[self.advantage.permissions setSmsAllowed:FALSE];
[self.advantage.permissions setTelAllowed:FALSE];
[self.advantage.permissions setCalendarAllowed:FALSE];
[self.advantage.permissions setStorePictureAllowed:FALSE];
[self.advantage.permissions setInlineVideoAllowed:FALSE];
[self.advantage.permissions setUserLocationAllowed:FALSE];
[self.advantage.permissions setRotationAllowed:FALSE];
[self.advantage.permissions setContactAllowed:FALSE];
[self.advantage.permissions setBluetoothAllowed:FALSE];
[self.advantage.permissions setSensorsAllowed:FALSE]; // Compass, Accelerometer, Gyroscope, Proximity, Pedometer, Barometer
Using offline ad features

Another new feature of version 2.0 is using offline ads. So if there is any error in your license or ad server, you can request to show an offline ad which can be a html page in your bundle or an external url.

Tip

Offline ads don`t have any functionality of ADvantage or MRAID and it is a normal UIWebView.

func advantage(_ advantage: ADvantage, didFailWithError error: String?) {
    guard let offlineUrl = URL(string: "www.google.com") else {
        return
    }
    advantage.offlineURL = offlineUrl
    advantage.requestOfflineAd()
}

- (void)advantage:(ADvantage *)advantage didFailWithError:(NSString *)error {
    [self.advantage setOfflineURL:[NSURL URLWithString:@"http://www.google.com"]];
    [self.advantage requestOfflineAd];
}
Orientation Handling

Whether you're using constraints or simple frames, orientation changes need to be handled one way or another.

One solution is to reload an ad with a new position that you know is compatible with landscape or portrait.

Then in your rotation callback you can do the following:

advantage.position = "myLandscapePosition"
advantage.requestAd()

[self.ad setPosition: @"myLandscapePosition"];
[self.ad requestAd];

If your ad is responsive, you can set the ADvantage instance's layoutType to kADResponsiveLayout and just set the width of ADvantage to the fullscreen width. Then when the user rotates the device, ADvantage will set the new height based on the responsive create and notify you with the didUpdateLayout callback of ADvantage.

Another solution is to control the sizes of your ads manually by modifying the frame or constraints on rotations.