Migration guide

This guide outlines the steps to migrate your app from Ogury SDK v5 to v6. 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 v5 API and the new v6 API, along with practical code examples.

Import the Ogury SDK

To integrate the latest version of the Ogury SDK into your application, you need to update the Ogury dependency in your build.gradle file. Ensure that you reference version 6.+ instead of version 5.+.

dependencies {
    implementation 'co.ogury:ogury-sdk:6.+'
}

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 three parameters:

  • a Context

  • the asset key as a String

  • an optional OguryOnStartListener for handling success (onStarted()) or failure (onFailed(OguryError)).

The Configuration and Configuration.Builder 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 (v5) example

val configurationBuilder = OguryConfiguration.Builder(context, "OGY-XXXXXXXXXXXX")
    .putMonitoringInfo("xxxxx_mediation_version", getMediationVersion())

Ogury.start(configurationBuilder.build())

New API (v6) example

Ogury.start(this, "OGY-XXXXXXXXXXXX", object : OguryOnStartListener {
    override fun onStarted() {
        // Initialization successful
    }

    override fun onFailed(error: OguryError) {
        // Handle initialization failure
    }
})

Integrate the Ogury ad formats

Note that the package com.ogury.ed has been renamed to com.ogury.ad.

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

Interstitial Ad

API changes

The setAdMarkup(adMarkup: String) method has been removed and replaced by the load(adMarkup: String) method.

Callbacks in OguryInterstitialAdListener include the instance of OguryInterstitialAd as a parameter.

The onAdDisplayed callback has been removed.

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

  • type: OguryAdError.Type.LOAD or OguryAdError.Type.SHOW.

  • code: Listed in OguryLoadErrorCode and OguryShowErrorCode.

  • message: A description of the error.

The onAdImpression callback is now part of OguryInterstitialAdListener, leading to the removal of the OguryAdImpressionListener class.

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

Legacy API (v5) example

val interstitialAd = OguryInterstitialAd(this, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

interstitialAd.setListener(object : OguryInterstitialAdListener {

    override fun onAdLoaded() {
        if (interstitialAd.isLoaded()) {
            interstitialAd.show()
        }
    }

    override fun onAdDisplayed() { 
        // ...
    }
    
    override fun onAdClicked() {
        // ... 
    }
    
    override fun onAdClosed() {
        // ... 
    }

    override fun onAdError(oguryError: OguryError) {
        Log.w("Ogury", "An error occurred (code: ${oguryError.errorCode}; message: ${oguryError.message})")
    }
})

interstitialAd.setAdImpressionListener(object : OguryAdImpressionListener {
    override fun onAdImpression() {
        // ...
    }
})

interstitialAd.load()

New API (v6) example

val interstitialAd = OguryInterstitialAd(this, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

interstitialAd.setListener(object : OguryInterstitialAdListener {

    override fun onAdLoaded(interstitialAd: OguryInterstitialAd) {
        if (interstitialAd.isLoaded()) {
            interstitialAd.show()
        }
    }

    override fun onAdImpression(interstitialAd: OguryInterstitialAd) {
        // ...
    }

    override fun onAdClicked(interstitialAd: OguryInterstitialAd) {
        // ...
    }

    override fun onAdClosed(interstitialAd: OguryInterstitialAd) {
        // ...
    }

    override fun onAdError(interstitialAd: OguryInterstitialAd, error: OguryAdError) {
        when (error.type) {
            OguryAdError.Type.LOAD_ERROR -> {
                Log.w("Ogury", "A LOAD error occurred (code: ${error.code}; message: ${error.message})")
            }
            OguryAdError.Type.SHOW_ERROR -> {
                Log.w("Ogury", "A SHOW error occurred (code: ${error.code}; message: ${error.message})")
            }
        }
    }
})

interstitialAd.load()

Rewarded Ad (formerly Opt-in Video Ad)

API changes

The OguryOptinVideoAd and OguryOptinVideoAdListener classes have been renamed to OguryRewardedAd and OguryRewardedAdListener, respectively.

The setAdMarkup(adMarkup: String) method has been removed and replaced by the load(adMarkup: String) method. Additionally, the setUserId method has been removed.

Callbacks in OguryRewardedAdListener include the instance of OguryRewardedAd as a parameter.

The onAdDisplayed callback has been removed.

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

  • type: OguryAdError.Type.LOAD or OguryAdError.Type.SHOW.

  • code: Listed in OguryLoadErrorCode and OguryShowErrorCode.

  • message: A description of the error.

The onAdImpression callback is now part of OguryRewardedAdListener, leading to the removal of the OguryAdImpressionListener class

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

Legacy API (v5) example

val rewardedAd = OguryRewardedAd(this, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

rewardedAd.setListener(object : OguryRewardedAdListener {

    override fun onAdLoaded() {
        if (rewardedAd.isLoaded()) {
            rewardedAd.show()
        }
    }

    override fun onAdDisplayed() { 
        // ...
    }
    
    override fun onAdRewarded(oguryReward: OguryReward) {
        Log.d("Ogury", "User has received reward '${oguryReward.name}' with value: ${oguryReward.value}")
    }

    
    override fun onAdClicked() {
        // ... 
    }
    
    override fun onAdClosed() {
        // ... 
    }

    override fun onAdError(oguryError: OguryError) {
        Log.w("Ogury", "An error occurred (code: ${oguryError.errorCode}; message: ${oguryError.message})")
    }
})

rewardedAd.setAdImpressionListener(object : OguryAdImpressionListener {
    override fun onAdImpression() {
        // ...
    }
})

rewardedAd.load()

New API (v6) example

val rewardedAd = OguryRewardedAd(this, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

rewardedAd.setListener(object : OguryRewardedAdListener {

    override fun onAdLoaded(rewardedAd: OguryRewardedAd) {
        if (rewardedAd.isLoaded()) {
            rewardedAd.show()
        }
    }

    override fun onAdImpression(rewardedAd: OguryRewardedAd) {
        // ...
    }
    
    override fun onAdRewarded(rewardedAd: OguryRewardedAd, reward: OguryReward) {
        Log.d("Ogury", "User has received reward '${reward.name}' with value: ${reward.value}")
    }

    override fun onAdClicked(rewardedAd: OguryRewardedAd) {
        // ...
    }

    override fun onAdClosed(rewardedAd: OguryRewardedAd) {
        // ...
    }

    override fun onAdError(rewardedAd: OguryRewardedAd, error: OguryAdError) {
        when (error.type) {
            OguryAdError.Type.LOAD_ERROR -> {
                Log.w("Ogury", "A LOAD error occurred (code: ${error.code}; message: ${error.message})")
            }
            OguryAdError.Type.SHOW_ERROR -> {
                Log.w("Ogury", "A SHOW error occurred (code: ${error.code}; message: ${error.message})")
            }
        }
    }
})

rewardedAd.load()

Small Banner / MREC (formerly MPU)

API changes

The constructor 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 previous methods setAdUnit() and setAdSize() have been removed.

The loadAd() method has been renamed to load(). A new method, isLoaded(), has been introduced to check if the banner has been successfully loaded.

Additionally, the method setAdMarkup(adMarkup: String) has been removed and replaced with load(adMarkup: String).

Callbacks in OguryBannerAdListener now include the specific instance of OguryBannerAdView as a parameter.

The onAdDisplayed callback has been removed.

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

  • type: OguryAdError.Type.LOAD or OguryAdError.Type.SHOW.

  • code: Listed in OguryLoadErrorCode and OguryShowErrorCode.

  • message: A description of the error.

The onAdImpression callback is now part of OguryBannerAdListener, leading to the removal of the OguryAdImpressionListener class.

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

Legacy API (v5) example

val bannerAd = OguryBannerAdView(this)
bannerAd.setAdUnit("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
bannerAd.setAdSize(OguryBannerAdSize.SMALL_BANNER_320x50) // or MPU_300x250 size, for MREC ads.

bannerAd.setListener(object : OguryBannerAdListener {

    override fun onAdLoaded() {
        yourView.removeAllViews()
        yourView.addView(bannerAd)
    }

    override fun onAdDisplayed() { 
        // ...
    }
    
    override fun onAdClicked() {
        // ... 
    }
    
    override fun onAdClosed() {
        // ... 
    }

    override fun onAdError(oguryError: OguryError) {
        Log.w("Ogury", "An error occurred (code: ${oguryError.errorCode}; message: ${oguryError.message})")
    }
})

bannerAd.setAdImpressionListener(object : OguryAdImpressionListener {
    override fun onAdImpression() {
        // ...
    }
})

bannerAd.loadAd()

New API (v6) example

val bannerAd = OguryBannerAdView(
            this,
            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            OguryBannerAdSize.SMALL_BANNER_320x50 // or MREC_300x250 size, for MREC ads.
        )
        
bannerAd.setListener(object : OguryBannerAdListener {

    override fun onAdLoaded(bannerAd: OguryBannerAdView) {
        if (bannerAd.isLoaded()) {
            yourView.removeAllViews()
            yourView.addView(bannerAd)
        }
    }

    override fun onAdImpression(bannerAd: OguryBannerAdView) {
        // ...
    }

    override fun onAdClicked(bannerAd: OguryBannerAdView) {
        // ...
    }

    override fun onAdClosed(bannerAd: OguryBannerAdView) {
        // ...
    }

    override fun onAdError(bannerAd: OguryBannerAdView, error: OguryAdError) {
        when (error.type) {
            OguryAdError.Type.LOAD_ERROR -> {
                Log.w("Ogury", "A LOAD error occurred (code: ${error.code}; message: ${error.message})")
            }
            OguryAdError.Type.SHOW_ERROR -> {
                Log.w("Ogury", "A SHOW error occurred (code: ${error.code}; message: ${error.message})")
            }
        }
    }
})

bannerAd.load()

Thumbnail Ad

API changes

Callbacks in OguryThumbnailAdListener now include the specific instance of OguryThumbnailAd as a parameter.

The onAdDisplayed callback has been removed.

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

  • type: OguryAdError.Type.LOAD or OguryAdError.Type.SHOW.

  • code: Listed in OguryLoadErrorCode and OguryShowErrorCode.

  • message: A description of the error.

The onAdImpression callback is now part of OguryThumbnailAdListener, leading to the removal of the OguryAdImpressionListener class.

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

Legacy API (v5) example

val thumbnailAd = OguryThumbnailAd(this, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

thumbnailAd.setListener(object : OguryThumbnailAdListener {

    override fun onAdLoaded() {
        if (thumbnailAd.isLoaded()) {
            thumbnailAd.show(activity)
        }
    }

    override fun onAdDisplayed() { 
        // ...
    }
    
    override fun onAdClicked() {
        // ... 
    }
    
    override fun onAdClosed() {
        // ... 
    }

    override fun onAdError(oguryError: OguryError) {
        Log.w("Ogury", "An error occurred (code: ${oguryError.errorCode}; message: ${oguryError.message})")
    }
})

thumbnailAd.setAdImpressionListener(object : OguryAdImpressionListener {
    override fun onAdImpression() {
        // ...
    }
})

thumbnailAd.load()

New API (v6) example

val thumbnailAd = OguryThumbnailAd(this, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

thumbnailAd.setListener(object : OguryThumbnailAdListener {

    override fun onAdLoaded(thumbnailAd: OguryThumbnailAd) {
        if (interstitialAd.isLoaded()) {
            interstitialAd.show()
        }
    }

    override fun onAdImpression(thumbnailAd: OguryThumbnailAd) {
        // ...
    }

    override fun onAdClicked(thumbnailAd: OguryThumbnailAd) {
        // ...
    }

    override fun onAdClosed(thumbnailAd: OguryThumbnailAd) {
        // ...
    }

    override fun onAdError(thumbnailAd: OguryThumbnailAd, error: OguryAdError) {
        when (error.type) {
            OguryAdError.Type.LOAD_ERROR -> {
                Log.w("Ogury", "A LOAD error occurred (code: ${error.code}; message: ${error.message})")
            }
            OguryAdError.Type.SHOW_ERROR -> {
                Log.w("Ogury", "A SHOW error occurred (code: ${error.code}; message: ${error.message})")
            }
        }
    }
})

thumbnailAd.load()

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", true) // To opt out

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

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

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

Mediation

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

The OguryTokenProvider class has been renamed to OguryBidTokenProvider, and the method getBidderToken is now getBidToken(). This updated method now requires two parameters: a Context and an OguryBidTokenListener, which provides the bid token or returns an OguryError if the token cannot be generated.

This error object includes:

  • code: Listed in OguryBidTokenErrorCode.

  • message: A description of the error.

Legacy API (v5) example

val bidToken = OguryTokenProvider.getBidderToken(context)

New API (v6) example

OguryTokenProvider.getBidderToken(context, object : OguryBidTokenListener {

    override fun onBidTokenGenerated(bidToken: String) {
        // Token successfully generated, handle the bidToken here
    }

    override fun onBidTokenGenerationFailed(error: OguryError) {
        // Token generation failed, handle the error here
    }
})

Last updated