iOS SDK

This page describes how to integrate our iOS SDK with your project.

Follow the instructions in this section to set up our SDK to show ads in your app.

1 Requirements
2 Installation
- 2.1 Get the SDK
  - 2.1.1 Clone the repo
3 Show Banners on iOS
4 Show video ads on iOS

Requirements

This SDK requires Xcode version 15.0 or higher and your app should target iOS 12.0 or higher.
Configure App Transport Security (ATS).

Installation

Get the SDK

Clone the repo

Run this command in your terminal:

git clone https://github.com/e-planning/mobile-sdk-ios.git

Note: The SDK is a standalone library

Then add the source to your project

Show Banners on iOS

This page has instructions and code samples for showing banner ads. To show banner ads:

Include banner ad view header file of mobile SDK.
Create a banner ad view object.
Pass in a frame, placement ID, and size.
Add it as a subview of the current view.

Following the steps mentioned above you should start seeing ads.

import UIKit
import EplanningSDK

class BannerAdViewController: UIViewController , EPLBannerAdViewDelegate{
    var banner: EPLBannerAdView?
    
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        EPLLogManager.setANLogLevel(EPLLogLevel.all)
        

        self.title = "Banner Ad EPL"
    
        let adWidth: Int = 300
        let adHeight: Int = 250
        let adID = "17058950"
        
        // We want to center our ad on the screen.
        let screenRect: CGRect = UIScreen.main.bounds
        let originX: CGFloat = (screenRect.size.width / 2) - CGFloat((adWidth / 2))
        let originY: CGFloat = (screenRect.size.height / 2) - CGFloat((adHeight / 2))
        // Needed for when we create our ad view.
        
        let rect = CGRect(origin: CGPoint(x: originX,y :originY), size: CGSize(width: adWidth, height: adHeight))
        
        let size = CGSize(width: adWidth, height: adHeight)
        
        // Make a banner ad view.
        let banner = EPLBannerAdView(frame: rect, placementId: adID, adSize: size)
        banner.rootViewController = self
        banner.delegate = self
        banner.publisherId = 123456
        
        view.addSubview(banner)
        // Load an ad.
        banner.loadAd()
        
    }
    
    func adDidReceiveAd(_ ad: Any) {
        print("Ad did receive ad")
    }
  
    func ad(_ ad: Any, requestFailedWithError error: Error) {
        print("Ad request Failed With Error")
    }
}

Show video ads on iOS

A video ad can be fetched and displayed with as few as three methods initWithPlacementId:, loadAdWithDelegate: and playAdWithContainer:withDelegate:. Defining the delegates for loading and playback will provide granular feedback for the video ad lifecycle.

In this step, initialize ANInstreamVideoAd with the placement ID.

ANInstreamVideoAd *videoAd = [[ANInstreamVideoAd alloc] initWithPlacementId:@"MY-PLACEMENT-ID"];

Load the video ad and (optionally) define the ANInstreamVideoAdLoadDelegate.

Using the ANInstreamVideoAdLoadDelegate is highly recommended. It indicates when the load is complete or, alternatively, whether an error occurred during load.

The delegates return the instance of ANInstreamVideoAd, expressed as a reference to its superclass ANAdProtocol. It is shared with other Mobile SDK ad formats. The video ad object retains state that may be useful to refer during the lifecycle of the video ad.

Video ad state includes the placement ID, whether the video ad was clicked or skipped, and error feedback in the case of failure. (For complete details, see ANInstreamVideoAd.h .)

import UIKit
import EplanningSDK

class VideoAdViewController: UIViewController , EPLInstreamVideoAdLoadDelegate, EPLInstreamVideoAdPlayDelegate {
    
    
    @IBOutlet weak var videoView: UIView!
    @IBOutlet weak var logTextView: UITextView!
    /// Frame for video view in portrait mode.
    var portraitVideoViewFrame = CGRect.zero
    /// Frame for video player in fullscreen mode.
    var fullscreenVideoFrame = CGRect.zero
    var videoAd: EPLInstreamVideoAd?
    var videoContentPlayer: AVPlayer?
    @IBOutlet weak var playButton: UIButton!
    var isvideoAdAvailable = false
    
    
    
    override func viewDidLoad() {
        super.viewDidLoad()
        self.title = "Video Ad"
        
        
        
        if UIDevice.current.orientation == .landscapeLeft || UIDevice.current.orientation == .landscapeRight {
            viewDidEnterLandscape()
        }
        
        setupContentPlayer()
        videoAd = EPLInstreamVideoAd(placementId: "17058950")
        videoAd?.load(with: self)
        videoAd?.clickThroughAction = EPLClickThroughAction.openSDKBrowser
        videoAd?.publisherId = 123456
        
        playButton.layer.zPosition = CGFloat(MAXFLOAT)
        isvideoAdAvailable = false
        // Fix iPhone issue of log text starting in the middle of the UITextView
        automaticallyAdjustsScrollViewInsets = false
        portraitVideoViewFrame = videoView.frame
        
        // Do any additional setup after loading the view.
    }
    
    @IBAction func playButton_Touch(_ sender: Any) {
        playButton.isHidden = true
        if isvideoAdAvailable == false {
            videoContentPlayer!.play()
        } else {
            videoContentPlayer!.pause()
            videoAd?.play(withContainer: videoView, with: self)
            isvideoAdAvailable = false
        }
    }
    override func didRotate(from interfaceOrientation: UIInterfaceOrientation) {
        switch interfaceOrientation {
        case .landscapeLeft, .landscapeRight:
            viewDidEnterPortrait()
        case .portrait, .portraitUpsideDown:
            viewDidEnterLandscape()
        case .unknown:
            break
        @unknown default:
            break
        }
    }
    
    func setupContentPlayer() {
        let contentURL = URL(string: "https://acdn.adnxs.com/mobile/video_test/content/Scenario.mp4")
        if let contentURL = contentURL {
            videoContentPlayer = AVPlayer(url: contentURL)
        }
        if let contentURL = contentURL {
            videoContentPlayer = AVPlayer(url: contentURL)
        }
        let playerLayer = AVPlayerLayer(player: videoContentPlayer)
        playerLayer.frame = videoView.bounds
        videoView.layer.addSublayer(playerLayer)
        videoView.setNeedsLayout()
        videoView.translatesAutoresizingMaskIntoConstraints = true
        NotificationCenter.default.addObserver(self, selector: #selector(self.itemDidFinishPlaying(_:)), name: .AVPlayerItemDidPlayToEndTime, object: videoContentPlayer?.currentItem)
    }
    
    func viewDidEnterLandscape() {
        let screenRect: CGRect = UIScreen.main.bounds
        fullscreenVideoFrame = CGRect(x: 0, y: 0, width: screenRect.size.width, height: screenRect.size.height)
        videoView.frame = fullscreenVideoFrame
    }
    
    func viewDidEnterPortrait() {
        videoView.frame = portraitVideoViewFrame
    }
    
    
    override func viewDidDisappear(_ animated: Bool) {
        videoContentPlayer!.pause()
        videoAd!.remove()
        videoAd = nil
        super.viewWillDisappear(animated)
        
    }
    @objc func itemDidFinishPlaying(_ notification: Notification?) {
        print("finished playing content")
        //cleanup the player & start again
        videoContentPlayer = nil
        setupContentPlayer()
        playButton.isHidden = false
        isvideoAdAvailable = false
    }
    
    func getAdPlayElapsedTime() {
        // To get AdPlayElapsedTime
        let getAdPlayElapsedTime = videoAd!.getPlayElapsedTime()
        logMessage("getAdPlayElapsedTime \(getAdPlayElapsedTime)")
        
    }
    
    // MARK: - EPLInstreamVideoAdDelegate.
    func adDidReceiveAd(_ ad: Any) {
        // To get AdDuration
        let getAdDuration = videoAd!.getDuration()
        logMessage("getAdDuration \(getAdDuration)")
        
        // To get CreativeURL
        let getCreativeURL = videoAd!.getCreativeURL()
        logMessage("getCreativeURL \(String(describing: getCreativeURL))")
        
        // To get VastURL
        let getVastURL = videoAd!.getVastURL()
        logMessage("getVastURL \(String(describing: getVastURL))")
        
        // To get VastXML
        let getVastXML = videoAd!.getVastXML()
        logMessage("getVastXML \(String(describing: getVastXML))")
        
        // To get AdPlayElapsedTime
        getAdPlayElapsedTime()
        isvideoAdAvailable = true
        
        logMessage("adDidReceiveAd")
        
    }
    
    func ad(_ ad: EPLAdProtocol?) throws {
        isvideoAdAvailable = false
    }
    
    //----------------------------- -o-
    func adCompletedFirstQuartile(_ ad: EPLAdProtocol) {
        getAdPlayElapsedTime()
    }
    
    func adCompletedMidQuartile(_ ad: EPLAdProtocol) {
        getAdPlayElapsedTime()
        
    }
    //----------------------------- -o-
    func adPlayStarted(_ ad: EPLAdProtocol) {
        getAdPlayElapsedTime()
        
    }
    
    func adCompletedThirdQuartile(_ ad: EPLAdProtocol) {
        getAdPlayElapsedTime()
    }
    
    
    func adWasClicked(_ ad: EPLAdProtocol) {
        
    }
    
    func adMute(_ ad: EPLAdProtocol, withStatus muteStatus: Bool) {
        if muteStatus == true {
            logMessage("adMuteOn")
        } else {
            logMessage("adMuteOff")
        }
    }
    
    func adDidComplete(_ ad: EPLAdProtocol, with state: EPLInstreamVideoPlaybackStateType) {
        if state == EPLInstreamVideoPlaybackStateType.skipped {
            logMessage("adWasSkipped")
        } else if state == EPLInstreamVideoPlaybackStateType.error {
            logMessage("adplaybackFailedWithError")
        } else if state == EPLInstreamVideoPlaybackStateType.completed {
            logMessage("adPlayCompleted")
            getAdPlayElapsedTime()
        }
        isvideoAdAvailable = false
        videoContentPlayer!.play()
        
    }
    
    
    func logMessage(_ log: String?) {
        let logString = "\(log ?? "")\n"
        logTextView.text = logTextView.text + (logString)
        if logTextView.text.count > 0 {
            let bottom = NSRange(location: logTextView.text.count - 1, length: 1)
            logTextView.scrollRangeToVisible(bottom)
        }
    }
    
}

English