iOS SDK for in-app advertising with SmartyAds SSP

This is a free Software Development Kit for the iOS application developers and publishers to monetize digital mobile inventory faster than the blink of an eye. SmartyAds integrates with SmartyAds SSP, one single source of offerings tailored to publishers' needs.

Supported Ad formats

SmartyAdsSDK supports five Banner Sizes. Your should choose size to pass in initialization( your_banner_size_here) accordingly to selected placement type on SSP platform:

Banner and rich media ads:

Size, DPI Type SmartyAdsSDK Size Constant
320x50 Standard Banner kStandartSizeBanner
320x100 Large Banner kLargeSizeBanner
300x250 IAB Medium Rectangle kIABMediumRectangelSizeBanner
468x60 IAB Full-Size Banner kIABFullSizeBanner
728x90 IAB Leaderboard kIABLeaderboardSizeBanner

Video ads:

Orientation: Landscape or Portrait

Native ads

Currently SDK supports native ads for UITableView only. We are going to add some more options in future

Interstitial ads:

Size, DPI Type
Custom size Full screen

Getting Started

Just a few steps to start (to understand how user works with inventory):

  1. Register your account on SmartyAds Supply Side Platform

  2. Confirm your registration by following the confirmation link sent via email

  3. Create your first mobile inventory by clicking Add Inventory. Select iOS Application in pop up.

    create inventory for iOS implementation
  4. Fill all required fields in Add Inventory form. Inventory should be reviewed and approved before presenting ads. Click Save changes for proceeding next

    Add Inventory
  5. After this, you will be granted access to create placements for your inventory, +Banner button should become clickable

    Add Inventory Summary
  6. Click on +Banner, add the targeting options, floor price and size of your placement, then click Save changes

    Add Placement
  7. Please, note the Placement ID(e.g., ID#12) below it's title. It will be used later in your code to initialize the ad container

    Placement Summary

Requirements

SmartyAdsSDK in-app advertising framework requires iOS 9 and up .

Manualy installation

Important

SmartyAdsSDK.framework don't support iOS Simulator. Use real device for testing.

  • Download SmartyAdsSDK Cocoa Touch framework

  • Place SmartyAdsSDK.framework in project's folder

  • In Xcode, choose your App Target: General -> Embedded Binaries -> Add SmartyAdsSDK.framework from the folder where it was placed on the previous step

  • In Xcode, choose your App Target:Build Settings -> Architectures -> Build Active Architecture Only set YES

  • In Xcode, choose your App Target:Build Settings -> Build Options -> Enable Bitcode set NO

Setup App Permissions

  • Edit your Info.plist file to include the following properties: * Add ADBundleIsPaid property and its Boolean value: - YES - if your App is paid, or you have in-app purchases - NO - if your App is distributed free of any charges

  • To allow SmartyAdsSDK geo ad targeting: Add Privacy - Location When In Use Usage Description property with a String value:your_app_name would like to use your geoposition

        
        <?xml version="1.0" encoding="utf-8"?>
        <!doctype plist public "-//apple//dtd plist 1.0//en" "http://www.apple.com/dtds/propertylist-1.0.dtd">
        <plist version="1.0">
            <dict>
                ...
                <key>NSLocationWhenInUseUsageDescription</key>
                <string>your_app_name would like to use your geoposition</string>
                ...
            </dict>
        </plist>
                                
  • TURN ON App Transport Security - Allows Arbitrary Loads property - this option will allow ad content loading via HTTPprotocol. In order to turn turn on this property do the following:

        <?xml version="1.0" encoding="utf-8"?>
        <!doctype plist public "-//apple//dtd plist 1.0//en" "http://www.apple.com/dtds/propertylist-1.0.dtd">
        <plist version="1.0">
            <dict>
                ...
                <key>NSAppTransportSecurity</key>
                <dict>
                    <key>NSAllowsArbitraryLoads</key>
                    <true/>
                </dict>
                ...
            </dict>
        </plist>
                                
  • ALTERNATIVELY, you can use App Transport Security - Allows Arbitrary Loads In Web Content property - this option will allow web content loading via HTTP protocol. Also add ssp-nj.webtradehub.com to Exception Domains dictionary:

        <?xml version="1.0" encoding="utf-8"?>
        <!doctype plist public "-//apple//dtd plist 1.0//en" "http://www.apple.com/dtds/propertylist-1.0.dtd">
        <plist version="1.0">
        <dict>
            ...
            <key>NSAppTransportSecurity</key>
            <dict>
                <key>NSExceptionDomains</key>
                <dict>
                    <key>ssp-nj.webtradehub.com</key>
                <dict/>
                <key>NSExceptionAllowsInsecureHTTPLoads</key>
                <true/>
                <key>NSIncludesSubdomains</key>
                <true/>
            </dict>
            <key>NSAllowsArbitraryLoadsInWebContent</key>
            <true/>
            ...
        </dict>
        </plist>
                                

Initializing SmartyAdsSDK

In AppDelegate.m, -application:didFinishLaunchingWithOptions: method add following initializing code:

    
    #import <SmartyAdsSDK/SmartyAdsSDK.h>
    
    ...
                        
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        [MonetizationSDK start];
        [MonetizationSDK GDPRconsentFlag:YES];
    
        return YES;
    }
                    

Setting GDPR (Requirement)

To make your iOS SDK GDPR compliant please set one of the following options:
  
    + (void)GDPRconsentFlag:(BOOL)flag; - set a new value for GDPR user consent. GDPR user consent is a boolean value, where YES = user consent given & NO = user consent denied or no information provided.
    
    + (BOOL)getGDPRconsentFlag; - get current GDPR value
                    

Add Banner

In ViewViewController where you want to show Banner, add BannerAdView property as a class var:

    
    #import <SmartyAdsSDK/SmartyAdsSDK.h>
    
    @interface ViewController ()<BannerAdViewDelegate>
    @property (nonatomic, strong) BannerAdView *adview;
    
    @end
                    

Use -init-initWithFrame:, or -viewDidLoad as a place for adView initialization:

    
    - (instancetype)init {
        self = [super init];
        self.adView = [[BannerAdView alloc] initWithPlacementId:**your_banner_id_here** size:**your_banner_size_here**];
        self.adView.delegate = self;
        [self.view addsubview:self.adview];
        return self;
    }
                    
Important

Do not forget to replace the your_banner_id_here with the placement ID from the Platform(Step 6 of the Getting Started section, e.g. @"5884") and your_banner_size_here (e.g. kStandartSizeBanner) accordingly.

Driving BannerAdView

BannerAdView serves the following methods for Ad View management:

  • -loadBannerAd - loads Banner Ad from server

  • -showBannerAdView - shows Banner Ad View

  • -startAutomaticallyRefreshingContents - starts refreshing Ad View periodically. Minimal refresh interval is 30 seconds. You can set new interval in method -autoRefreshInterval

  • -stopAutomaticallyRefreshingContents - stops previously initiated auto refresh process

Driving BannerAdViewDelegate

Required methods:

  • -bannerAdDidLoad - fires when Banner AD is successfully loaded and ready for showing

  • -bannerAdDidFailLoadingWithError: - fires when Banner Ad failed to load from server

  • -viewControllerForPresentingModalView - the BannerAdView will use the view controller returned by this method to present modals when tapped. Typically your controller can simply return self.

  • -bannerAdCacheDidFailLoadingWithError: - fires when Banner Ad failed to load from local cache

Optional methods:

  • -bannerAdViewClicked - fires when user clicked on Banner Ad View

  • -shouldRequestPreciseLocation - asks if Ad View can request geo location, by using device location services, YES by default

  • -autoRefreshInterval - method for overriding time interval for auto refreshing

Add Interstitial Ad

In ViewController where you want to show Interstitial, add InterstitialAdViewController property:

    
    #import <SmartyAdsSDK/SmartyAdsSDK.h>
    
    @interface ViewController ()<InterstitialAdDelegate>
    
    @property (nonatomic, strong) InterstitialAdViewController *interstitialad;
    
    @end
                    

Use -init-viewDidLoad as a place for interstitialAd initialization:

 
    - (void)viewDidLoad {
        [super viewDidLoad];
        
        self.interstitialAd = [[InterstitialAdViewController alloc] initWithPlacementId:**your_interstitial_id_here**];
        self.interstitialAd.delegate = self;
    }
                    
Important

Don't use -viewDidAppear:-viewWillAppear: methods for initialization InterstitialAdViewController

Interstitial Ad Load and Presentation

In order to load Interstitial Ad, you should call -loadInterstitialAd method.

    - (void)someMethod {
        ...your code there...
        
        [self.interstitialAd loadInterstitialAd];
    }
                    

For shows Interstitial Ad View just call -showInterstitialAd method.

    - (void)interstitialAdDidLoad {
        [self.interstitialAd showinterstitial];
    }
                    

Driving InterstitialAdDelegate

Required methods:
  • -interstitialAdDidLoad - fires when Interstitial Ad is successfully loaded

  • -interstitialAdDidFailLoadingWithError: - fires when Interstitial Ad failed to load from server

  • -interstitialAdCacheDidFailLoadingWithError: - fires when Interstitial Ad failed to load from local cache

Optional methods:
  • -interstitialAdViewWillAppear - fires when Interstitial Ad View will appear on View Controller

  • -interstitialAdViewDidAppear - fires when Interstitial Ad View did appear on View Controller

  • -interstitialAdViewWIllDisappear - fires when Interstitial Ad View will disappear from View Controller

  • -interstitialAdViewDidDisappear - fires when Interstitial Ad View did disappear from View Controller

  • -userClickedOnInterstitialAdView - fires when user click on Interstitial Ad View

Add Video Ad

In ViewController where you want to show Video, add VideoAdController property.

   
    #import <SmartyAdsSDK/SmartyAdsSDK.h>
    
    @interface ViewController () <VideoAdDelegate>
    
    @property (nonatomic, strong) VideoAdController *videoAd;
    
    @end
                    

Use -viewDidLoad-init as a place for adVideo initialization:

    
    - (void)viewDidLoad {
        [super viewDidLoad];
    
        self.videoAd = [[VideoAdController alloc] initWithPlacementId:**your_video_id_here**];
        self.videoAd.delegate = self;
    }
                    
Important

Don't use -viewDidAppear:-viewWillAppear: methods for initialization VideoAdController

Video Ad Load and Presentation

In order to load Video Ad, you should call -loadVideoAd method.

    
    - (void)somemethod {
        ...code there...
    
        [self.videoAd loadVideoAd];
    }
                    

For shows Video Ad View just call -showVideoAd method.

    
    - (void)videoAdDidLoad {
        [self.videoAd showVideoAd];
    }
                    

Driving VideoAdViewDelegate

Required methods:
  • -videoAdDidLoad - fires when Video Ad is successfully loaded

  • -videoAdDidFailLoadingWithError: - fires when Video Ad failed to load from server

  • -videoAdCacheDidFailLoadingWithError: - fires when Video Ad failed to load from local cache

Optional methods:
  • -videoAdViewControllerDidAppear - fires when Video Ad View appear on View Controller

  • -videoAdViewControllerDidDisappear - fires when Video Ad View disappear from View Controller

  • -videoAdViewControllerDidFailToLoading - fires when Video Ad View failed to load video file

  • -userDidClickOnVideo - fires when user click on Video Ad View

  • -videoAdComplete - fires when Video Ad fully watched

  • -videoAdSkipped - fires when Video Ad skipped

Additional params

  • -setRewardedMacros: - override this method if you set reward params in your inventory

  • -setAmountMacros: - override this method if you set amount params in your inventory

To enable custom macros please follow the steps below:

1. Inventory is supposed to be created on UI.

2. Please toggle rewarded video when creating Video Placement in that inventory.

3. The fields to fill in URLs appear to distinguish video events.

Initializing Native Ad

Currently SDK supports native ads for UITableView only. We are going to add some more options in future.

To use native ads in your app you should take some simple steps:

  1. To define the layout of native advertisement

  2. To implement the classes needed for native ads served in UITableView

  3. To call the method for automatic loading and serving native ads.

How to define the layout of native advertisement

Every native ad requires UIVIew subclass which realizes NativeAdRenderingProtocol for NativeAdViewConfigurator settings object. NativeAdRenderingProtocol allows you to point out which UI elements of native ad you want to use. Typical assets for native ad according to IAB specification:

  • Title

  • Sponsored

  • Icon

  • Main image

  • Desription

  • Call-to-action button

Sample implementation for native ad

    
//NativeAdView.h
                        
@interface NativeAdView : UIView

@end
        

//NativeView.m
@interface NativeAdView ()<NativeAdRenderingProtocol>

@property (weak, nonatomic) IBOutlet UIImageView *iconImageView;
@property (weak, nonatomic) IBOutlet UIImageView *mainImageView;
@property (weak, nonatomic) IBOutlet UILabel *titleLabel;
@property (weak, nonatomic) IBOutlet UILabel *sponsoredLabel;
@property (weak, nonatomic) IBOutlet UIButton *ctaButton;
@property (weak, nonatomic) IBOutlet UILabel *description2Label;

@end

@implementation NativeAdView

- (void)awakeFromNib
{
    [super awakeFromNib];
}

+ (UINib *)nibForAd
{
    return [UINib nibWithNibName:@"NativeAdView" bundle:[NSBundle bundleForClass:[self class]]];
}

- (void)layoutSubviews
{
    [super layoutSubviews];
}

- (UILabel *)nativeTitleTextLabel
{
    return self.titleLabel;
}

- (UIImageView *)nativeIconImageView
{
    return self.iconImageView;
}

- (UIImageView *)nativeMainImageView
{
    return self.mainImageView;
}

- (UIButton *)nativeCallToActionButton
{
    return self.ctaButton;
}

- (UILabel *)nativeBrandLabel
{
    return self.sponsoredLabel;
}

- (UILabel *)nativeDescription2TextLabel
{
    return self.description2Label;
}
                                        
                                

Sample UI design for native ads

 
 

Native ad visualization management

If you want to add something special to your native ads, you can implement NativeAdViewLifeCycleDelegate for tracking the current state of each native ad on the screen (Added to the screen/Deleted from the screen)

- (void)nativeAdViewWillAppear
{
    //Start animation when NativeAdView appears
}

- (void)nativeAdViewDidDisappear
{
    //Stop animation when NativeAdView hide
}
                    

Implementation of the classes required for native ad served in UITableView

The Monetization SDK provides the axillary class, NativeAdTableViewPlacer, that helps request ads from SSP and insert it into your existing UITableView subclass

When the instance of NativeAdTableViewPlacer is initialized with a tableview, it wraps the tableview datasource and delegate in order to insert ads and adjust the positions of your regular content cells

  1. Create and configure NativeAdViewConfigurator object with implementation of classForRender/nativeViewCanProcessAllUserClicks and viewHeight:

    NativeAdViewConfigurator *configurator = [NativeAdViewConfigurator nativeConfigurator];
    configurator.classForRender = [YourNativeAdView class];
    configurator.nativeViewCanProcessAllUserClicks = NO;
    configurator.viewHeight = 200;
                                
  2. Set up your preferred ad positioning via AdPositioning object:

    AdPositioning *positioning = [AdPositioning positioning];
    [positioning addPositionIndexPath:[NSIndexPath indexPathForRow:0 inSection:0]];
    [positioning addPositionIndexPath:[NSIndexPath indexPathForRow:0 inSection:1]];
    [positioning addPositionIndexPath:[NSIndexPath indexPathForRow:0 inSection:2]];
    ...
    [positioning enableRepeatingPositionsWithInterval:10];
                                
  3. Initiate your NativeAdTableViewPlacer with your UITableView/NativeAdViewConfigurator and AdPositioning instances

    self.nativePlacer = [NativeAdTableViewPlacer placerWithTableView:self.nativeTableView adConfigurator:configurator adPositioning:positioning adPlacementId:_your_native_placementID_];
                                
  4. And just call loadNativeAd method

    [self.nativePlacer loadNativeAd];
                                
  5. Replace UITableView method calls to the following UITableView methods with the Monetization SDK category equivalents.

    Instead of:

    [self.tableView selectRowAtIndexPath:myIndexPath];
                                

    Use:

    [self.tableView nad_selectRowAtIndexPath:myIndexPath];
                                

    These methods work just like the regular UITableView methods, except that they make adjustments to the NSIndexPath parameters to handle the fact that your stream has extra ad rows.

UITableView category for native ad

ORIGINAL REPLACEMENT
reloadData nad_reloadData
beginUpdates nad_beginUpdates
endUpdates nad_endUpdates
insertRowsAtIndexPaths:withRowAnimation: nad_insertRowsAtIndexPaths:withRowAnimation:
deleteRowsAtIndexPaths:withRowAnimation: nad_deleteRowsAtIndexPaths:withRowAnimation:
reloadRowsAtIndexPaths:withRowAnimation: nad_reloadRowsAtIndexPaths:withRowAnimation:
moveRowAtIndexPath:toIndexPath: nad_moveRowAtIndexPath:toIndexPath:
insertSections:withRowAnimation: nad_insertSections:withRowAnimation:
deleteSections:withRowAnimation: nad_deleteSections:withRowAnimation:
reloadSections:withRowAnimation: nad_reloadSections:withRowAnimation:
moveSection:toSection: nad_moveSection:toSection:
cellForRowAtIndexPath: nad_cellForRowAtIndexPath:
selectRowAtIndexPath:animated:scrollPosition: nad_selectRowAtIndexPath:animated:scrollPosition:
deselectRowAtIndexPath:animated: nad_deselectRowAtIndexPath:animated:
indexPathForCell: nad_indexPathForCell:
indexPathsForVisibleRows: nad_indexPathsForVisibleRows:
indexPathForSelectedRow: nad_indexPathForSelectedRow:
indexPathsForSelectedRows: nad_indexPathsForSelectedRows:
indexPathForRowAtPoint: nad_indexPathForRowAtPoint:
indexPathsForRowsInRect: nad_indexPathsForRowsInRect:
rectForRowAtIndexPath: nad_rectForRowAtIndexPath:
scrollToRowAtIndexPath:atScrollPosition:animated: nad_scrollToRowAtIndexPath:atScrollPositions:animated:
visibleCells nad_visibleCells