Migration guide

From 28th January 2022, Ogury released a new API specially refactored to improve the onboarding experience. In this guide, you will learn how to switch from the old API to the new one.

The old API is now deprecated. To remove warning generated by the old API, please update to the latest API following this guide.

If you are using the method Ogury.getSDKVersion from the old API, you must change the import from OguryAds to OgurySDK.

Import the Ogury SDK

In order to import the latest version of the new Ogury SDK, you must update the Cocoapods dependency in the Podfile of your application. Now, you have to change the name of the framework from OguryAds to OgurySDK and request the 3.+ version instead of the 2.+.

If the version is not hardcoded into your Podfile, you only need to replace the name of the dependency:

pod "OgurySdk"

If the version is hardcoded into your Podfile, you can change it to match the new version:

pod "OgurySdk", "~> 2.1.0"

Initialize the Ogury SDK

Before initializing the Ogury SDK, you will need to add the import of the new name of the framework:

Old API

import OguryAds

New API

import OgurySdk
import OguryAds

The way to initialize the Ogury SDK is a bit different. Replace the old API by the new one:

Old API

OguryAds.shared().setup(withAssetKey: "OGY-XXXXXXXXXXXX")

New API

let configuration = OguryConfigurationBuilder(assetKey: "OGY-XXXXXXXXXXXX").build()

Ogury.start(with: configuration)

In the new API, the Ogury.start() must be called before you use any of the Ogury SDK's functionalities including the Ogury Choice Manager.

If you use the Ogury Choice Manager, you no longer have to initialize the Ogury Choice Manager SDK. It is now initialized by performing the start() method.

Old API

import UIKit
import OguryChoiceManager

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        let configuration = OguryChoiceManagerConfig.defaultConfiguration()
        
        OguryChoiceManager.shared().setup(withAssetKey: "OGY-XXXXXXXXXXXX", andConfig: configuration)
        
        // Get user consent
        OguryChoiceManager.shared().ask(with: self) { (error, response) in
            ...
        }
    }
}

New API

import UIKit
import OgurySdk
import OguryChoiceManager

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        let configuration = OguryConfigurationBuilder(assetKey: "OGY-XXXXXXXXXXXX").build()

        Ogury.start(with: configuration)
        
        // Get user consent
        OguryChoiceManager.shared().ask(with: self) { (error, response) in
            ...
        }
    }
}

Note the OguryChoiceManager.setupWithAssetKey() method is not required anymore. It is replaced by the Ogury.start().

The Ogury Choice Manager and the Ogury ad formats are synchronized. So you can start loading the ads while requesting user consent. You do not need to wait for the user response. Indeed, the ad will be loaded once the user's consent response is obtained. Just pay attention to call ask method before loading ads.

Integrate Ogury ad formats

The way Ogury ads are loaded and displayed has not really changed. Ogury has just refactored a little bit the API in order to have a more consistent and smoother API. Let's take a look at the changes, format by format.

Interstitial Ad

The OguryAdsInterstitial class becomes OguryInterstitialAd.

The method to show the ad is now showAdInViewController: instead of showInViewController:.

The OguryAdsInterstitialDelegate protocol becomes OguryInterstitialAdDelegate and the methods to implement are now:

Methods

Definition

didLoadOguryInterstitialAd:interstitial

The SDK is ready to display the ad provided by the ad server.

didDisplayOguryInterstitialAd:interstitial

The ad has been displayed on the screen.

didClickOguryInterstitialAd:interstitial

The as has been clicked by the user.

didCloseOguryInterstitialAd:interstitial

The ad has been closed by the user.

didFailOguryInterstitialAdWithError:error:interstitial

The ad failed to load or display.

didTriggerImpressionOguryInterstitialAd:interstitial

The ad has triggered an impression.

The oguryAdsInterstitialAdAvailable, oguryAdsInterstitialAdNotAvailable, oguryAdsInterstitialAdNotLoaded methods have been removed. They are now replaced by the didFailOguryInterstitialAdWithError:error:interstitial callback.

Now, the didFailOguryInterstitialAdWithError:error:interstitial callback provides an OguryError object instead of an error code integer. The OguryError parameter contains the reason of the failure.

In practice

Old API

import UIKit
import OguryAds

class ViewController: UIViewController {

    var interstitialAd: OguryAdsInterstitial?

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        OguryAds.shared().setup(withAssetKey: "OGY-XXXXXXXXXXXX")
        
        interstitialAd = OguryAdsInterstitial(adUnitId: "AD_UNIT_ID")
        interstitialAd?.delegate = self
        interstitialAd?.load()
    }
}

extension ViewController: OguryAdsInterstitialDelegate {
    
    func oguryAdsInterstitialAdAvailable() {
        ...
    }

    func oguryAdsInterstitialAdNotAvailable() {
        ...
    }

    func oguryAdsInterstitialAdLoaded() {
        ...
    }

    func oguryAdsInterstitialAdNotLoaded() {
        ...
    }

    func oguryAdsInterstitialAdDisplayed() {
        ...
    }

    func oguryAdsInterstitialAdClosed() {
        ...
    }

    func oguryAdsInterstitialAdError(_ errorType: OguryAdsErrorType) {
        ...
    }
}

New API

import UIKit
import OgurySdk
import OguryAds

class ViewController: UIViewController {

    var interstitialAd: OguryInterstitialAd?

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        let configuration = OguryConfigurationBuilder(assetKey: "OGY-XXXXXXXXXXXX").build()

        Ogury.start(with: configuration)
        
        interstitialAd = OguryInterstitialAd(adUnitId: "AD_UNIT_ID")
        interstitialAd?.delegate = self
        interstitialAd?.load()
    }
}

extension ViewController: OguryInterstitialAdDelegate {

    func didLoad(_ interstitial: OguryInterstitialAd) {
        ...
    }

    func didFailOguryInterstitialAdWithError(_ error: OguryError, for interstitial: OguryInterstitialAd) {
        ...
    }

    func didDisplay(_ interstitial: OguryInterstitialAd) {
        ...
    }

    func didClick(_ interstitial: OguryInterstitialAd) {
        ...
    }

    func didClose(_ interstitial: OguryInterstitialAd) {
        ...
    }
    
    func didTriggerImpressionOguryInterstitialAd(_ interstitial: OguryInterstitialAd) {
        ...
    }
}

Opt-in Video Ad

The OguryAdsOptinVideo class becomes OguryOptinVideoAd.

The method to show the ad is now showAdInViewController: instead of showInViewController:.

The OguryAdsOptinVideoDelegate protocol becomes OguryOptinVideoAdDelegate and the methods to implement are now:

Methods

Definition

didLoadOguryOptinVideoAd:optinVideo

The SDK is ready to display the ad provided by the ad server.

didDisplayOguryOptinVideoAd:optinVideo

The ad has been displayed on the screen.

didClickOguryOptinVideoAd:optinVideo

The as has been clicked by the user.

didCloseOguryOptinVideoAd:optinVideo

The ad has been closed by the user.

didFailOguryOptinVideoAdWithError:error:optinVideo

The ad failed to load or display.

didRewardOguryOptinVideoAdWithItem:forAd:optinVideo

The user must be rewarded, as they have watched the Opt-in Video Ad.

didTriggerImpressionOguryOptinVideoAd:optinVideo

The ad has triggered an impression.

The oguryAdsOptinVideoAdAvailable, oguryAdsOptinVideoAdNotAvailable, oguryAdsOptinVideoAdNotLoaded methods have been removed. They are now replaced by the didFailOguryOptinVideoAdWithError:error:optinVideo callback.

Now, the didFailOguryOptinVideoAdWithError:error:optinVideo callback provides an OguryError object instead of an error code integer. The OguryError parameter contains the reason of the failure.

In practice

Old API

import UIKit
import OguryAds

class ViewController: UIViewController {

    var optinVideoAd: OguryAdsOptinVideo?

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        OguryAds.shared().setup(withAssetKey: "OGY-XXXXXXXXXXXX")
        
        optinVideoAd = OguryAdsOptinVideo(adUnitId: "AD_UNIT_ID")
        optinVideoAd?.delegate = self
        optinVideoAd?.load()
    }
}

extension ViewController: OguryAdsOptinVideoDelegate {
    
    func oguryAdsOptinVideoAdAvailable() {
        ...
    }

    func oguryAdsOptinVideoAdNotAvailable() {
        ...
    }

    func oguryAdsOptinVideoAdLoaded() {
        ...
    }

    func oguryAdsOptinVideoAdNotLoaded() {
        ...
    }

    func oguryAdsOptinVideoAdDisplayed() {
        ...
    }

    func oguryAdsOptinVideoAdClosed() {
        ...
    }

    func oguryAdsOptinVideoAdError(_ errorType: OguryAdsErrorType) {
        ...
    }
    
    func oguryAdsOptinVideoAdRewarded(item: OGARewardItem) {
        ...
    }
}

New API

import UIKit
import OgurySdk
import OguryAds

class ViewController: UIViewController {

    var optinVideoAd: OguryOptinVideoAd?

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        let configuration = OguryConfigurationBuilder(assetKey: "OGY-XXXXXXXXXXXX").build()

        Ogury.start(with: configuration)
        
        optinVideoAd = OguryOptinVideoAd(adUnitId: "AD_UNIT_ID")
        optinVideoAd?.delegate = self
        optinVideoAd?.load()
    }
}

extension ViewController: OguryOptinVideoAdDelegate {

    func didLoad(_ optinVideo: OguryOptinVideoAd) {
        ...
    }

    func didFailOguryOptinVideoAdWithError(_ error: OguryError, for optinVideo: OguryOptinVideoAd) {
        ...
    }

    func didDisplay(_ optinVideo: OguryOptinVideoAd) {
        ...
    }

    func didClick(_ optinVideo: OguryOptinVideoAd) {
        ...
    }

    func didClose(_ optinVideo: OguryOptinVideoAd) {
        ...
    }
    
    func didRewardOguryOptinVideoAd(with item: OGARewardItem, for optinVideo: OguryOptinVideoAd) {
        ...
    }
    
    func didTriggerImpressionOguryOptinVideoAd(_ optinVideo: OguryOptinVideoAd) {
        ...
    }
}

The OguryAdsBanner class becomes OguryBannerAd.

The method to remove the ad is now destroy instead of close.

The OguryAdsBannerDelegate protocol becomes OguryBannerAdDelegate and the methods to implement are now:

Methods

Definition

didLoadOguryBannerAd:banner

The SDK is ready to display the ad provided by the ad server.

didDisplayOguryBannerAd:banner

The ad has been displayed on the screen.

didClickOguryBannerAd:banner

The as has been clicked by the user.

didCloseOguryBannerAd:banner

The ad has been closed by the user.

didFailOguryBannerAdWithError:error:banner

The ad failed to load or display.

didTriggerImpressionOguryBannerAd:banner

The ad has triggered an impression.

The oguryAdsBannerAdAvailable, oguryAdsBannerAdNotAvailable, oguryAdsBannerAdNotLoaded methods have been removed. They are now replaced by the didFailOguryBannerAdWithError:error:banner callback.

Now, the didFailOguryBannerAdWithError:error:banner callback provides an OguryError object instead of an error code integer. The OguryError parameter contains the reason of the failure.

In practice

Old API

import UIKit
import OguryAds

class ViewController: UIViewController {

    var bannerAd: OguryAdsBanner?

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        OguryAds.shared().setup(withAssetKey: "OGY-XXXXXXXXXXXX")
        
        bannerAd = OguryAdsBanner(adUnitId: "AD_UNIT_ID")
        bannerAd?.delegate = self
        bannerAd?.loadWithSize(...)
    }
}

extension ViewController: OguryAdsBannerDelegate {
    
    func oguryAdsBannerAdAvailable() {
        ...
    }

    func oguryAdsBannerAdNotAvailable() {
        ...
    }

    func oguryAdsBannerAdLoaded() {
        ...
    }

    func oguryAdsBannerAdNotLoaded() {
        ...
    }

    func oguryAdsBannerAdDisplayed() {
        ...
    }

    func oguryAdsBannerAdClosed() {
        ...
    }

    func oguryAdsBannerAdError(_ errorType: OguryAdsErrorType) {
        ...
    }
}

New API

import UIKit
import OgurySdk
import OguryAds

class ViewController: UIViewController {

    var bannerAd: OguryBannerAd?

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        let configuration = OguryConfigurationBuilder(assetKey: "OGY-XXXXXXXXXXXX").build()

        Ogury.start(with: configuration)
        
        bannerAd = OguryBannerAd(adUnitId: "AD_UNIT_ID")
        bannerAd?.delegate = self
        bannerAd?.loadWithSize(...)
    }
}

extension ViewController: OguryBannerAdDelegate {

    func didLoad(_ banner: OguryBannerAd) {
        ...
    }

    func didFailOguryBannerAdWithError(_ error: OguryError, for banner: OguryBannerAd) {
        ...
    }

    func didDisplay(_ banner: OguryBannerAd) {
        ...
    }

    func didClick(_ banner: OguryBannerAd) {
        ...
    }

    func didClose(_ banner: OguryBannerAd) {
        ...
    }
    
    func didTriggerImpressionOguryBannerAd(_ banner: OguryBannerAd) {
        ...
    }
}

Thumbnail Ad

The OguryAdsThumbnailAd class becomes OguryThumbnailAd.

The OguryAdsThumbnailAdDelegate protocol becomes OguryThumbnailAdDelegate and the methods to implement are now:

Methods

Definition

didLoadOguryThumbnailAd:thumbnail

The SDK is ready to display the ad provided by the ad server.

didDisplayOguryThumbnailAd:thumbnail

The ad has been displayed on the screen.

didClickOguryThumbnailAd:thumbnail

The as has been clicked by the user.

didCloseOguryThumbnailAd:thumbnail

The ad has been closed by the user.

didFailOguryThumbnailAdWithError:error:thumbnail

The ad failed to load or display.

didTriggerImpressionOguryThumbnailAd:thumbnail

The ad has triggered an impression.

The oguryAdsThumbnailAdAvailable, oguryAdsThumbnailAdNotAvailable, oguryAdsThumbnailAdNotLoaded methods have been removed. They are now replaced by the didFailOguryThumbnailAdWithError:error:thumbnail callback.

Now, the didFailOguryThumbnailAdWithError:error:thumbnail callback provides an OguryError object instead of an error code integer. The OguryError parameter contains the reason of the failure.

In practice

Old API

import UIKit
import OguryAds

class ViewController: UIViewController {

    var thumbnailAd: OguryAdsThumbnailAd?

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        OguryAds.shared().setup(withAssetKey: "OGY-XXXXXXXXXXXX")
        
        thumbnailAd = OguryAdsThumbnailAd(adUnitId: "AD_UNIT_ID")
        thumbnailAd?.delegate = self
        thumbnailAd?.load()
    }
}

extension ViewController: OguryAdsThumbnailAdDelegate {
    
    func oguryAdsThumbnailAdAdAvailable() {
        ...
    }

    func oguryAdsThumbnailAdAdNotAvailable() {
        ...
    }

    func oguryAdsThumbnailAdAdLoaded() {
        ...
    }

    func oguryAdsThumbnailAdAdNotLoaded() {
        ...
    }

    func oguryAdsThumbnailAdAdDisplayed() {
        ...
    }

    func oguryAdsThumbnailAdAdClosed() {
        ...
    }

    func oguryAdsThumbnailAdAdError(_ errorType: OguryAdsErrorType) {
        ...
    }
}

New API

import UIKit
import OgurySdk
import OguryAds

class ViewController: UIViewController {

    var thumbnailAd: OguryThumbnailAd?

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup SDK
        let configuration = OguryConfigurationBuilder(assetKey: "OGY-XXXXXXXXXXXX").build()

        Ogury.start(with: configuration)
        
        thumbnailAd = OguryThumbnailAd(adUnitId: "AD_UNIT_ID")
        thumbnailAd?.delegate = self
        thumbnailAd?.load()
    }
}

extension ViewController: OguryThumbnailAdDelegate {

    func didLoad(_ thumbnail: OguryThumbnailAd) {
        ...
    }

    func didFailOguryThumbnailAdWithError(_ error: OguryError, for thumbnail: OguryThumbnailAd) {
        ...
    }

    func didDisplay(_ thumbnail: OguryThumbnailAd) {
        ...
    }

    func didClick(_ thumbnail: OguryThumbnailAd) {
        ...
    }

    func didClose(_ thumbnail: OguryThumbnailAd) {
        ...
    }
    
    func didTriggerImpressionOguryThumbnailAd(_ thumbnail: OguryThumbnailAd) {
        ...
    }
}

Last updated