Migration guide

This guide outlines the steps to migrate your app from Ogury SDK v4 to v5. The update introduces significant enhancements, including the removal of deprecated methods, a simplified initialization process, and improved ad format handling and privacy management.

Follow this guide to ensure a smooth transition, with clear comparisons between the legacy v4 API and the new v5 API, along with practical code examples.

Initialize the Ogury SDK

The latest version of the Ogury SDK introduces several key updates to streamline the initialization process.

API changes

The start() method now accepts two parameters:

the asset key as a String
an optional StartCompletionBlock for handling success or failure.

The OguryConfiguration and OguryConfigurationBuilder classes have been removed, and the asset key is passed directly.

The OguryStartErrorCode class offers predefined error codes for managing initialization.

Mediation details (name and version) are no longer passed at initialization but are set at the ad format level.

For more information on initializing the Ogury SDK, please refer to the Getting Started page.

Legacy API (v4) example

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

OguryConfigurationBuilder *configurationBuilder = [[OguryConfigurationBuilder alloc] initWithAssetKey:@"OGY-XXXXXXXXXXXX"];
[Ogury startWithConfiguration:[configurationBuilder build]];

New API (v5) example

Ogury.start(with: "OGY-XXXXXXXXXXXX") { success, error in
    guard error == nil, success else {
        // handle error here
        return
    }
    // handle start here
}

[Ogury startWith:@"OGY-XXXXXXXXXXXX" completionHandler:^(BOOL success, OguryError * _Nullable error) {
    if (error) {
        // handle the error
    } else if (success) {
        // handle start here
    }
}];

Integrate the Ogury ad formats

The version 5 introduces several changes across different ad formats. Below are the key modifications and improvements for each format.

The method isLoaded() was replaced by a property. You can now test that your ad is loaded with ad.isLoaded

Interstitial Ad

API changes

The didDisplayOguryInterstitialAd callback has been removed.

The delegates have been renamed as follows:

Legacy API (v4) example

extension MyViewController: 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) {
        // ...
    }
}

- (void)didLoadOguryInterstitialAd:(OguryInterstitialAd *)interstitial {
   // ...
}

- (void)didDisplayOguryInterstitialAd:(OguryInterstitialAd *)interstitial {
   // ...
}

- (void)didClickOguryInterstitialAd:(OguryInterstitialAd *)interstitial {
   // ...
}

- (void)didCloseOguryInterstitialAd:(OguryInterstitialAd *)interstitial {
   // ...
}

- (void)didFailOguryInterstitialAdWithError:(OguryError *)error forAd:(OguryInterstitialAd *)interstitial {
   // ...
}

- (void)didTriggerImpressionOguryInterstitialAd:(OguryInterstitialAd *)interstitial {
   // ...
}

New API (v5) example

extension MyViewController: OguryInterstitialAdDelegate {
    func interstitialAdDidLoad(_ interstitialAd: OguryInterstitialAd) {
        // ...
    }
    
    func interstitialAdDidClick(_ interstitialAd: OguryInterstitialAd) {
        // ...
    }
    
    func interstitialAdDidClose(_ interstitialAd: OguryInterstitialAd) {
        // ...
    }
    
    func interstitialAd(_ interstitialAd: OguryInterstitialAd, didFailWithError error: OguryAdError) {
        // ...
    }
    
    func interstitialAdDidTriggerImpression(_ interstitialAd: OguryInterstitialAd) {
        // ...ssion)
    }
}

- (void)interstitialAdDidLoad:(OguryInterstitialAd *)interstitialAd {
    // ...
}
 
- (void)interstitialAdDidClick:(OguryInterstitialAd *)interstitialAd {
    // ...
}
 
- (void)interstitialAdDidClose:(OguryInterstitialAd *)interstitialAd {
    // ...
}
 
- (void)interstitialAd:(OguryInterstitialAd *)interstitialAd didFailWithError:(OguryAdError *)error {
    // ...
}
 
- (void)interstitialAdDidTriggerImpression:(OguryInterstitialAd *)interstitialAd {
    // ...
}

The interstitialAd:didFailWithError:callback now returns an OguryAdError object instead of the previous OguryError. This object includes:

type: OguryAdErrorType.Load or OguryAdErrorType.Show.
code: Listed in OguryLoadErrorCode and OguryShowErrorCode.
localizedDescription: A description of the error.

For more information on integrating Interstitial ads, please refer to the Interstitial page.

Rewarded Ad (formerly Opt-in Video Ad)

API changes

The OguryOptinVideoAd, OguryOptinVideoAdDelegate and OGARewardItem classes have been renamed to OguryRewardedAd, OguryRewardedAdDelegate and OguryReward respectively.

The userId property has been removed.

The didDisplayOguryOptinVideoAd callback has been removed.

The delegates have been renamed as follows:

Legacy API (v4) example

extension MyViewController: OguryOptinVideoAdDelegate {
   func didLoad(_ ad: OguryOptinVideoAd) {
      // ...
   }
   
   func didDisplay(_ ad: OguryOptinVideoAd) {
      // ...
   }
   
   func didClick(_ ad: OguryOptinVideoAd) {
      // ...
   }
   
   func didClose(_ ad: OguryOptinVideoAd) {
      // ...
   }
   
   func didFailOguryOptinVideoAdWithError(_ error: OguryError, for optinVideo: OguryOptinVideoAd) {
      // ...
   }
   
   func didTriggerImpressionOguryOptinVideoAd(_ optinVideo: OguryOptinVideoAd) {
      // ...ssion)
   }
   
   func didRewardOguryOptinVideoAd(with item: OGARewardItem, for optinVideo: OguryOptinVideoAd) {
      // ...)
   }
}

- (void)didLoadOguryOptinVideoAd:(OguryOptinVideoAd *)optinVideo {
    // ...
}
 
- (void)didDisplayOguryOptinVideoAd:(OguryOptinVideoAd *)optinVideo {
    // ...
}
 
- (void)didClickOguryOptinVideoAd:(OguryOptinVideoAd *)optinVideo {
    // ...
}
 
- (void)didCloseOguryOptinVideoAd:(OguryOptinVideoAd *)optinVideo {
    // ...
}
 
- (void)didRewardOguryOptinVideoAdWithItem:(OGARewardItem *)item forAd:(OguryOptinVideoAd *)optinVideo {
    // ...
}
 
- (void)didFailOguryOptinVideoAdWithError:(OguryError *)error forAd:(OguryOptinVideoAd *)optinVideo {
    // ...
}
 
- (void)didTriggerImpressionOguryOptinVideoAd:(OguryOptinVideoAd *)optinVideo {
    // ...
}

New API (v5) example

extension MyViewController: OguryRewardedAdDelegate {
   func rewardedAdDidLoad(_ rewardedAd: OguryRewardedAd) {
        // ...
    }
    
    func rewardedAdDidClick(_ rewardedAd: OguryRewardedAd) {
        // ...
    }
    
    func rewardedAdDidClose(_ rewardedAd: OguryRewardedAd) {
        // ...
    }
    
    func rewardedAd(_ rewardedAd: OguryRewardedAd, didFailWithError error: OguryAdError) {
        // ...
    }
    
    func rewardedAdDidTriggerImpression(_ rewardedAd: OguryRewardedAd) {
        // ...
    }
    
    func rewardedAd(_ rewardedAd: OguryRewardedAd, didReceive reward: OguryReward) {
        // ...
    }
}

- (void)rewardedAdDidLoad:(OguryRewardedAd *)rewardedAd {
    // ...
}
 
- (void)rewardedAdDidClick:(OguryRewardedAd *)rewardedAd {
    // ...
}
 
- (void)rewardedAdDidClose:(OguryRewardedAd *)rewardedAd {
    // ...
}
 
- (void)rewardedAd:(OguryRewardedAd *)rewardedAd didReceiveReward:(OguryReward *)reward {
    // ...
}
 
- (void)rewardedAd:(OguryRewardedAd *)rewardedAd didFailWithError:(OguryAdError *)error {
    // ...
}
 
- (void)rewardedAdDidTriggerImpression:(OguryRewardedAd *)rewardedAd {
    // ...
}

The rewardedAd:didFailWithError:callback now returns an OguryAdError object instead of the previous OguryError. This object includes:

type: OguryAdErrorType.Load or OguryAdErrorType.Show.
code: Listed in OguryLoadErrorCode and OguryShowErrorCode.
localizedDescription: A description of the error.

For more information on integrating Interstitial ads, please refer to the Rewarded page.

Small Banner / MREC (formerly MPU)

API changes

The OguryBannerAd and OguryBannerAdDelegate have been renamed to OguryBannerAdView and OguryBannerAdViewDelegate respectively to reflect that it is actually a UIView subclass.

The initializer for OguryBannerAdView now requires both the ad unit ID and the size, which can be either OguryBannerAdSize.small_banner_320x50() or OguryBannerAdSize.mrec_300x250().

The load(with: OguryBannerAdSize) method has been replaced by load().

The didDisplayOguryBannerAd callback has been removed.

The delegates have been renamed as follows:

Legacy API (v4) example

extension MyViewController: OguryBannerAdDelegate {
   func didLoad(_ ad: OguryBannerAd) {
      // ...
   }
   
   func didDisplay(_ ad: OguryBannerAd) {
      // ...
   }
   
   func didClick(_ ad: OguryBannerAd) {
      // ...
   }
   
   func didClose(_ ad: OguryBannerAd) {
      // ...
   }
   
   func didFailOguryBannerAdWithError(_ error: OguryError, for banner: OguryBannerAd) {
      // ...
   }
   
   func didTriggerImpressionOguryBannerAd(_ banner: OguryBannerAd) {
      // ...
   }
   
   func presentingViewController(forOguryAdsBannerAd banner: OguryBannerAd) -> UIViewController? {
      // ...
   }
}

- (void)didLoadOguryBannerAd:(OguryBannerAd *)banner {
    // ...
}
 
- (void)didDisplayOguryBannerAd:(OguryBannerAd *)banner {
    // ...
}
 
- (void)didClickOguryBannerAd:(OguryBannerAd *)banner {
    // ...
}
 
- (void)didCloseOguryBannerAd:(OguryBannerAd *)banner {
    // ...
}
 
- (void)didFailOguryBannerAdWithError:(OguryError *)error forAd:(OguryBannerAd *)banner {
    // ...
}
 
- (void)didTriggerImpressionOguryBannerAd:(OguryBannerAd *)banner {
    // ...
}
 
- (UIViewController *_Nullable)presentingViewControllerForOguryAdsBannerAd:(OguryBannerAd *)banner {
    // ...
}

New API (v5) example

extension MyViewController: OguryBannerAdViewDelegate {
    func bannerAdViewDidLoad(_ bannerAd: OguryBannerAdView) {
        // ...
    }
    
    func bannerAdViewDidClick(_ bannerAd: OguryBannerAdView) {
        // ...
    }
    
    func bannerAdViewDidClose(_ bannerAd: OguryBannerAdView) {
        // ...
    }
    
    func bannerAdView(_ bannerAd: OguryBannerAdView, didFailWithError error: OguryAdError) {
        // ...
    }
    
    func bannerAdViewDidTriggerImpression(_ bannerAd: OguryBannerAdView) {
        // ...
    }
    
    func presentingViewController(forBannerAdView bannerAd: OguryBannerAdView) -> UIViewController? {
        // ...
    }
}

- (void)bannerAdViewDidLoad:(OguryBannerAdView *)bannerAd {
    // ...
}
 
- (void)bannerAdViewDidClick:(OguryBannerAdView *)bannerAd {
    // ...
}
 
- (void)bannerAdViewDidClose:(OguryBannerAdView *)bannerAd {
    // ...
}
 
- (void)bannerAdView:(OguryBannerAdView *)bannerAd didFailWithError:(OguryAdError *)error {
    // ...
}
 
- (void)bannerAdViewDidTriggerImpression:(OguryBannerAdView *)bannerAd {
    // ...
}
 
- (UIViewController *_Nullable)presentingViewControllerForBannerAdView:(OguryBannerAdView *)bannerAd {
    // ...
}

The bannerAdView:didFailWithError:callback now returns an OguryAdError object instead of the previous OguryError. This object includes:

type: OguryAdErrorType.Load or OguryAdErrorType.Show.
code: Listed in OguryLoadErrorCode and OguryShowErrorCode.
localizedDescription: A description of the error.

For more information on integrating Small Banner and MREC ads, please refer to the Small Banner / MREC page.

Thumbnail Ad

API changes

The didDisplayOguryThumbnailAd callback has been removed.

The UIScene is now passed to the thumbnail as a property thumbnail.scene = scene instead of having to pass it to the show() method.

The delegates have been renamed as follows:

Legacy API (v4) example

extension MyViewController: OguryThumbnailAdDelegate {
   func didLoad(_ ad: OguryThumbnailAd) {
      // ...
   }
   
   func didDisplay(_ ad: OguryThumbnailAd) {
      // ...
   }
   
   func didClick(_ ad: OguryThumbnailAd) {
      // ...
   }
   
   func didClose(_ ad: OguryThumbnailAd) {
      // ...
   }
   
   func didFailOguryThumbnailAdWithError(_ error: OguryError, for thumbnail: OguryThumbnailAd) {
      // ...
   }
   
   func didTriggerImpressionOguryThumbnailAd(_ thumbnail: OguryThumbnailAd) {
      // ...
   }

}

- (void)didLoadOguryThumbnailAd:(OguryThumbnailAd *)thumbnail {
    // ...
}
 
- (void)didDisplayOguryThumbnailAd:(OguryThumbnailAd *)thumbnail {
    // ...
}
 
- (void)didClickOguryThumbnailAd:(OguryThumbnailAd *)thumbnail {
    // ...
}
 
- (void)didCloseOguryThumbnailAd:(OguryThumbnailAd *)thumbnail {
    // ...
}
 
- (void)didFailOguryThumbnailAdWithError:(OguryError *)error forAd:(OguryThumbnailAd *)thumbnail {
    // ...
}
 
- (void)didTriggerImpressionOguryThumbnailAd:(OguryThumbnailAd *)thumbnail {
    // ...
}

New API (v5) example

extension MyViewController: OguryThumbnailAdDelegate {
    func thumbnailAdDidLoad(_ thumbnailAd: OguryThumbnailAd) {
        // ...
    }
    
    func thumbnailAdDidClick(_ thumbnailAd: OguryThumbnailAd) {
        // ...
    }
    
    func thumbnailAdDidClose(_ thumbnailAd: OguryThumbnailAd) {
        // ...
    }
    
    func thumbnailAd(_ thumbnailAd: OguryThumbnailAd, didFailWithError error: OguryAdError) {
        // ...
    }
    
    func thumbnailAdDidTriggerImpression(_ thumbnailAd: OguryThumbnailAd) {
        // ...
    }
}

- (void)thumbnailAdDidLoad:(OguryThumbnailAd *)thumbnailAd {
    // ...
}
 
- (void)thumbnailAdDidClick:(OguryThumbnailAd *)thumbnailAd {
    // ...
}
 
- (void)thumbnailAdDidClose:(OguryThumbnailAd *)thumbnailAd {
    // ...
}
 
- (void)thumbnailAd:(OguryThumbnailAd *)thumbnailAd didFailWithError:(OguryAdError *)error {
    // ...
}
 
- (void)thumbnailAdDidTriggerImpression:(OguryThumbnailAd *)thumbnailAd {
    // ...
}

The thumbnailAd:didFailWithError:callback now returns an OguryAdError object instead of the previous OguryError. This object includes:

type: OguryAdErrorType.Load or OguryAdErrorType.Show.
code: Listed in OguryLoadErrorCode and OguryShowErrorCode.
localizedDescription: A description of the error.

For more information on integrating Thumbnail ads, please refer to the Thumbnail page.

Privacy

All deprecated APIs related to the Ogury Choice Manager have been removed.

If you are using a Consent Management Platform (CMP) that complies with the IAB Transparency & Consent Framework (TCF) v2 or the IAB Global Privacy Platform GPP, consent is automatically collected, requiring no additional action on your part.

For users in the United States, Ogury SDK offers an opt-out option using the following boolean:

Ogury.setPrivacyData("us_optout", boolean: true) // To opt out

[Ogury setPrivacyData:@"us_optout" boolean:YES]; // To opt out

If you are mediation and need to pass this opt-out boolean to Ogury, use:

Ogury.setPrivacyData("us_optout_partner", boolean: true) // To opt out

[Ogury setPrivacyData:@"us_optout_partner" boolean:YES]; // To opt out

For more information about privacy, please refer to the Privacy compliance page.

Mediation

The version 5 introduces some changes to the mediation adapter APIs.

The OguryTokenService class has been renamed to OguryBidTokenService, and the method synchronous method getBidderToken is now is an asynchronous bidToken method that allows us to manage initialization and consent synchronization issues.

This updated method now requires a BidTokenCompletionBlock, which provides the bid token or returns an OguryError if the token cannot be generated.

This error object includes:

code: Listed in OguryBidTokenErrorCode.
localizedDescription: A description of the error.

Legacy API (v4) example

let token = OguryTokenService.getBidderToken()

NSString *token = [OguryTokenService getBidderToken];

New API (v5) example

OguryBidTokenService.bidToken { token, error in
    guard error == nil else {
        // handle error
        return
    }
    // handle token
}

[OguryBidTokenService bidToken:^(NSString * _Nullable bidToken, OguryError * _Nullable error) {
    if (error != nil) {
        [self tokenFailedWithError:error];        
    else {
        [self handle:token];
    }
}];

Last updated 1 month ago