The AdButler iOS SDK allows you to serve ads to your app through AdButler. This includes banner ads, interstitial ads, and VAST/VPAID video ads. AdButler supports MRAID 2.0 banner ads and interstitials.

You can download the iOS SDK from our GitHub page.

The SDK includes a tester app that you can use to see an example of implementation, as well as test your AdButler ads in the SDK.

This iOS SDK guide contains information about:

1. Installation requirements.
2. Required permissions.
3. Initialization.
4. Serving banner ads.
5. Serving interstitial ads.
6. Serving VAST video ads.

Installation requirements

• iOS 10.1+

• Xcode 11+

• Swift 5

Install the SDK by building and copying the framework into your project. A Cocoapod will be available soon.

Required permissions

If you plan to use advanced ad types such as MRAID, your app will need permissions for certain features:

• Telephony - Permission to send SMS.

• Photo Library - Permission to save images to gallery.

• Calendar Access - Permission to create reminders.

• You will also need to allow Arbitrary Loads for certain resources. In your info.plist add:

App Transport Security Settings > Allow Arbitrary Loads > YES

Initialization

In your main view controller, inside viewDidLoad(), initialize the AdButler class using the main view for the app.

override func viewDidLoad() {
    AdButler.initialize(mainView: self.view)
}

Serving banner ads

Banner ads are rectangular ads that often redirect users to a destination URL when tapped or clicked. They can be horizontal or vertical. Banner ads will be displayed as soon as they are returned from AdButler’s ad server. The response functions are included in a closure passed to the placement request.

Creating PlacementRequestConfig

After AdButler is initialized, you must create an object called PlacementRequestConfig before you can start requesting ads. This is an object where you supply any information you want to pass to the ad server.

The required fields are accountId (your adbutler account ID) and zoneId (the zone from which you are requesting the ad).

Optionally, you can also pass the width, height, and other custom parameters, and use member functions of this object to set things like keywords for targeting and other customization options.

Once you've created PlacementRequestConfig, you can start requesting ads by passing the object to AdButler.requestPlacement(). The response will contain your placement along with information that the ad needs.

ABBanner constructor parameters

With the placement, you can create the banner ad by creating an instance of ABBanner, and passing it the following parameters:

• placement - Currently, AdButler will return only one placement. We will make it possible to return a list as well in the future, but for now only placement[0] is used.

• parentViewController - This is the view controller that will contain the banner. This is typically the view controller doing the banner request.

• position - A string constant indicating where the banner should appear onscreen. Positions values can be found in AdButler.MRAIDConstants.

• respectSafeAreaLayoutGuide - Some apps may choose to have their layout take into account the safe area layout guide to keep the status bar visible. If your app does this, this setting will tell the interstitial ad to do the same.

• placementRequestConfig - The object that contains information about the placement to request.

Retrieving a banner ad

Width and height values are optional when requesting for banner ads. Most of the time these values will come from the zone in your AdButler configuration. If that is not set, you may want to set a fallback here. For more information on zones, read About zones.

Example

    let config = PlacementRequestConfig(accountId: 50088, zoneId: 354134, width:320, height:50, customExtras:nil)
    AdButler.requestPlacement(with: config) { response in
        switch response {
        case .success(_ , let placements):
            guard placements.count == 1 else {
                // error
                return
            }
            guard placements[0].isValid else {
                // error
                return
            }
            self.banner?.destroy()
            self.banner = ABBanner(placement:placements[0], parentViewController:self, position:self.Positions.BOTTOM_CENTER, respectSafeAreaLayoutGuide:false, placementRequestConfig:config)
        case .badRequest(let statusCode, let responseBody):
            return
        case .invalidJson(let responseBody):
            return
        case .requestError(let error):
            return
        }
    }

You can also pass a container UIView to ABBanner() instead of position to make the ad take on the size and location of the container.

Serving interstitial ads

Interstitial ads are full screen ads that are usually configured to appear between content, such as at the end of a game's level or when moving from one game mode to another. Your view controller must implement the ABInterstitialDelegate interface to retrieve event information.

The interstitial ad delegate functions are:

func interstitialReady(_ interstitial: ABInterstitial) {}

func interstitialFailedToLoad(_ interstitial: ABInterstitial) {}

func interstitialClosed(_ interstitial: ABInterstitial) {}

func interstitialStartLoad(_ interstitial: ABInterstitial) {}

Creating PlacementRequestConfig

After AdButler is initialized, you must create an object called PlacementRequestConfig before you can start requesting ads. This is an object where you supply any information you want to pass to the ad server.

The required fields are accountId (your adbutler account ID) and zoneId (the zone from which you are requesting the ad).

Optionally, you can also pass the width, height, and other custom parameters, and use member functions of this object to set things like keywords for targeting and other customization options.

Once you've created PlacementRequestConfig, you can start requesting ads by passing the object to AdButler.requestPlacement(). The response will contain your placement along with information that the ad needs.

ABInterstitial constructor parameters

With the placement, you can create the banner ad by creating an instance of ABInterstitial, and passing it the following parameters:

• placement - Currently, AdButler will return only one placement. We will make it possible to return a list as well in the future, but for now only placement[0] is used.

• parentViewController - The view controller that will contain the interstitial. This is typically the same controller that retrieves the interstitial placement.

• delegate - A class that implements the ABInterstitialDelegate interface. This is typically also the view controller that retrieves the interstitial.

• respectSafeAreaLayoutGuide - Some apps may choose to have their layout take into account the safe area layout guide to keep the status bar visible. If your app does this, this setting will tell the interstitial ad to do the same.

• placementRequestConfig - The object that contains information about the placement to request.

Retrieving an interstitial

Example

    let config = PlacementRequestConfig(accountId: 50088, zoneId: 354135, width:nil, height:nil, customExtras:nil)
    AdButler.requestPlacement(with: config) { response in
        switch response {
        case .success(_ , let placements):
            guard placements.count == 1 else {
                return  // interstitials should currently only return a single ad
            }
            guard placements[0].isValid else {
                return
            }
            if(placements[0].body != nil && placements[0].body != ""){
                self.interstitial = ABInterstitial(placement:placements[0], parentViewController:self, delegate:self, respectSafeAreaLayoutGuide:true)
            }
        default:
            return
        }
    }

Once the ad is retrieved, the interstitialReady function will be called. After this point you can display the interstitial at any time using interstitial.display();. The interstitial ad will be displayed only once, after which you must retrieve another one.

Serving VAST video ads

Video Ad Serving Template (VAST) ads are video ads that are usually configured to appear immediately before (pre-roll), immediately after (post-roll), or at certain points in the actual video content's playback (mid-roll). They require a delegate (ABVASTDelegate) to listen for VAST events.

For more information on VAST ads, read How to create a VAST ad item.

The VAST video delegate functions are:

func onMute() {}

func onUnmute() {}

func onPause() {}

func onResume() {}

func onRewind() {}

func onSkip() {}

func onPlayerExpand() {}

func onPlayerCollapse() {}

func onNotUsed() {}

func onLoaded() {}

func onStart() {}

func onFirstQuartile() {}

func onMidpoint() {}

func onThirdQuartile() {}

func onComplete() {}

func onCloseLinear() {}

func onBrowserOpening(){}

func onBrowserClosing(){}

func onReady(){}

func onError(){}

VAST ads must be preloaded. After the ad is loaded and prepared, the onReady() function will be called. You will notice that the play() and pause() functions will be called first. This is because the web view, in which the video will be played, is loaded off screen. This makes for a smoother transition to the ad.

After the onReady() function is called, you can call the display() function on the VAST object to display the ad.

How to display a VAST video ad

1. Create an ABVASTVideo object.

vast = ABVASTVideo()

2. Call initialize() on the ABVASTVideo object, providing your delegate. If the ad should be displayed in a specific orientation, provide an orientation mask as well. In the following example, the calling class implements ABVASTDelegate, allowing us to use self.view in preload, and self as the delegate parameter.

vast.initialize(accountID: accountID, zoneID:zoneID, publisherID:publisherID, delegate:self, orientationMask:nil)

3. Preload the VAST video ad, providing the parent view that will house a temporary WKWebView, which will be used to load the ad. Use your currently visible view. The web view will not have any size and will not be seen.

vast.preload(container:self.view)

4. If the ad loads sucessfully, the onReady() event will be called on your ABVASTDelegate. At this point, you can display the ad.

vast.display()

You will need to do this process each time you want an ad to be displayed so that your impressions will be counted correctly. For more information on impressions and accurate tracking, read Requests vs. Impressions.

License

The AdButler iOS SDK is released under the Apache 2.0 license. See LICENSE for more information.