IOS SDK Integration

SDK

iOS SDK for in-app advertising with Motionspots 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. CollectcentSDK integrates with Motionspots SSP, one single source of offerings tailored to publishers' needs.

Supported Ad formats

CollectcentSDK 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 CollectcentSDK 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

In accordance with the IAB specification:

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 Motionspots 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.

  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 Summaryt
  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#5884) below it's title. It will be used later in your code to initialize the ad container

    Placement Summary

Requirements

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

Manualy installation

  • Download CollectcentSDK Cocoa Touch framework

  • Place CollectcentSDK.framework in project's folder

  • In Xcode, choose your App Target: General -> Embedded Binaries -> Add CollectcentSDK.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

    SMABundleIsPaid
  • OPTIONAL Add Privacy - Location When In Use Usage Description property with a String value: CollectcentSDK and/or the SDKs mediated by Motionspots would like to access your location information to allow CollectcentSDK use Device location for geo ad targeting:

    • IN Xcode:

      Location When In Use Description
    • OR by opening Info.plist and adding following properties:

          <?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>CollectcentSDK and/or the sdks mediated by Motionspots would like to access your location information.</string>
                  ...
                </dict>
            </plist>
                                              
  • Turn on App Transport Security flag. This is needed for receiving Ad View content via HTTP protocol. Although this step is not required, without it, you won't be able to receive Ad View content from advertisers which use HTTP references for resources in its content:

    • TURN ON App Transport Security - Allows Arbitrary Loads property - this option will allow ad content loading via HTTP protocol. In order to turn turn on this property do the following:

      • IN Xcode:

      • OR by opening Info.plist and adding following properties:

            <?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 publishers.motionspots.com to Exception Domains dictionary:

      • IN Xcode:

        Allow Arbitrary Web Content
      • OR by opening Info.plist and adding following properties:

            <?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>publishers.motionspots.com</key>
                      <dict/>
                          <key>NSExceptionAllowsInsecureHTTPLoads</key>
                          <true/>
                          <key>NSIncludesSubdomains</key>
                          <true/>
                      </dict>
                      <key>NSAllowsArbitraryLoadsInWebContent</key>
                      <true/>
                      ...
                  </dict>
              </plist>
                                                        

Initializing CollectcentSDK

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

    #import <CollectcentSDK/CollectcentSDK.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 View/ ViewController where you want to show Banner, add BannerAdView property as a class var:

    #import <CollectcentSDK/CollectcentSDK.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. See the sample code below:

    [[BannerAdView alloc] initWithPlacementId:**your_banner_id_here** size:**your_banner_size_here**];
                        

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:
  • -bannerAdViewDidAppear - fires when Banner Ad View appear on View Controller

  • -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 Video Ad

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

    #import <CollectcentSDK/CollectcentSDK.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

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

  • -videoAdComplete - fires when Video Ad fully watched

  • -videoAdSkipped - fires when Video Ad skipped

  • -userDidClickOnVideo - fires when user clicked on video and was redirected to browser

Add Interstitial Ad

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

    #import <CollectcentSDK/CollectcentSDK.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