Early Access SDK - cleveradssolutions/CAS-Android GitHub Wiki

[!NOTE]
Please note that the new CAS 4.0.0-beta3 version is available as an early release and may have issues.

Changes

CAS 4.0 introduces several enhancements to streamline management and improve the stability of in-app ads:

• Unified Management: All ad formats are now managed using a CAS ID string with the new CASAppOpen, CASInterstitial and CASRewarded ad objects. Read more about the new implementation below. Previously, this required working with a MediationManager instance.
• Ad Type Management: Use ManagerBuilder.withAdTypes() only if you continue to use MediationManager for ad requests. For the new CASInterstitial and CASRewarded implementations, you should skip this function call.
• Preloading and Caching: You can now preload and cache multiple instances of ads for each ad format, reducing latency and improving ad display performance.
• User ID Specification: The CAS.targetingOptions.userId property is now available for specifying the User ID. The previous method using ManagerBuilder.withUserID() has been deprecated.
• Banner View Constructor: A new constructor for CASBannerView has been added that accepts a CAS ID parameter. The old constructor that accepted a MediationManager parameter is now deprecated.

Beta 3

• Includes adapter updates from version 3.9.4.
• Fixed internal critical bugs in mediation.
• Optimized some internal processes.
• The NativeAdContentCallback.onAdFailedToShow function renamed to onNativeAdFailedToShow.
• Added new adapter for YSO Network. Contact our manager if you want to try a new ad network. To integrate, you need to add a new repository to project settings:

maven {  
    name = "YSOAdsRepo"  
    url = "https://ysonetwork.s3.eu-west-3.amazonaws.com/sdk/android"  
    content { it.includeGroup("com.ysocorp") }  
}

And include the adapter to build:

cas {
    adapters {
        ysoNetwork = true
    }
}

Beta 2

• Fixed some internal exceptions.
• Added CASMediaView.imageScaleType property.
• Added CASNativeLoader.isStartVideoMuted property.
• Added Native Ads support from more ad sources.
• Added App Open Ads support from more ad sources.

Integration

In addition to the lines described in the Add Maven repositories section, please add the beta maven repository to your settings.gradle file.

pluginManagement {  
    repositories {  
        ...  
        maven {  
            name = "CASBetaRepo"  
            url = "https://repsy.io/mvn/cleveradssolutions/beta"  
        }  
    }
}

dependencyResolutionManagement {  
    repositories {  
        ...
        maven {  
            name = "CASBetaRepo"  
            url = "https://repsy.io/mvn/cleveradssolutions/beta"  
            content { it.includeGroup("com.cleveradssolutions") }  
        }
    }
}

[!NOTE]
pluginManagement.repositories can also be defined in the root-level build.gradle file within buildscript.repositories.

Continue with Plugin integration, using the beta version:

plugins {
    id("com.cleveradssolutions.gradle-plugin") version "4.0.0-beta3"
}

cas {
    ...
}

CAS ID

In most cases, a casId is the same as your application package name. Use demo as the casId to receive a demo ad for testing your implementation.

val casId = if (BuildConfig.DEBUG) CAS.TEST_ID else BuildConfig.APPLICATION_ID

Initialize Ads

You can skip the manual call for ad initialization, and then the SDK will automatically perform the initialization before the first ad load. However, if it's important for you to change the configuration or listen to states of the Consent Flow, make sure to initialize it at least once before the first ad load.

override fun onCreate() {  
    super.onCreate()
    
    CAS.buildManager()  
        .withManagerId(casId)
        .withConsentFlow(  
            ConsentFlow(isEnabled = true)  
                .withDismissListener {  
                    Log.d(TAG, "Consent flow dismissed")  
                }  
        )  
        .withCompletionListener {  
            if (it.error == null) {  
                Log.d(TAG, "Ads initialized")  
            } else {  
                Log.d(TAG, "Ads initialization failed: " + it.error)  
            }  
        }  
        .build(this)
}

[!NOTE]
Use ManagerBuilder.withAdTypes() only if you continue to use MediationManager for ad requests. For the new CASInterstitial and CASRewarded implementations, you should skip this function call.

Autoload Ad mode

If enabled, the ad will automatically load new content when the current ad is dismissed or completed. Additionally, it will automatically retry loading the ad if an error occurs during the loading process.

Previously, you used settings to choose between automatic or manual loading modes. (Deprecated)

CAS.settings.loadingMode = LoadingManagerMode.Manual

With the update to CAS 4.0, you can now configure automatic loading individually for each ad object. Below is an example of using the isAutoloadEnabled property and the default value for each ad format.

bannerView.isAutoloadEnabled = CAS.settings.loadingMode != LoadingManagerMode.Manual

interstitialAd.isAutoloadEnabled = false
rewardedAd.isAutoloadEnabled = false
appOpenAd.isAutoloadEnabled = false

The CASNativeLoader does not have an autoload ad mode.

OnAdImpressionListener (new)

A functional interface for listening to ad impression events.

val impressionListener = OnAdImpressionListener { ad: AdContent ->  
    // Called when an ad impression occurs.  
}

Each ad format has an onImpressionListener property within the ad object for registering a listener.

AdContent (new)

The deprecated AdImpression (AdStatusHandler) has been replaced by the new AdContent data structure, which contains information about the loaded/displayed ad. You can access AdContent using OnAdImpressionListener, ScreenAdContentCallback, or NativeAdContentCallback.

• format: AdFormat - Gets the format of the ad that is shown. See new AdFormat enum.
• sourceName: String - Gets the display name of the mediated network that purchased the impression.
• sourceId: Int - Gets the ID of the mediated network that purchased the impression. See new AdSourceId constants.
• sourceUnitId: String - Gets the Ad Unit ID from the mediated network that purchased the impression.
• creativeId: String? - Gets the Creative ID associated with the ad, if available. May be null. You can use this ID to report creative issues to the Ad review team.
• revenue: Double - Gets the revenue generated from the impression, in USD. The revenue value may be either estimated or exact, depending on the precision specified by revenuePrecision.
• revenuePrecision: Int - Gets the precision type of the revenue field. See new AdRevenuePrecision constants.
• impressionDepth: Int - Gets the total number of impressions across all ad formats for the current user, across all sessions.
• revenueTotal: Double - Gets the accumulated value of user ad revenue in USD from all ad format impressions.

Native Ad (new)

Read more about new Native Ad format implementation.

ScreenAdContentCallback (new)

A abstract class for handling events related to screen ad content.

val screenCallback = object : ScreenAdContentCallback(){  
    override fun onAdLoaded(ad: AdContent) {  
        // Called when the ad content has been successfully loaded.  
    }  
    override fun onAdFailedToLoad(format: AdFormat, error: AdError) {  
        // Called when the ad content fails to load.  
    }  
    override fun onAdFailedToShow(format: AdFormat, error: AdError) {  
        // Called when the ad content fails to show.  
    }  
    override fun onAdShowed(ad: AdContent) {  
        // Called when the ad content is successfully shown.  
    }  
    override fun onAdClicked(ad: AdContent) {  
        // Called when the ad content is clicked by the user.  
    }  
    override fun onAdDismissed(ad: AdContent) {  
        // Called when the ad content is dismissed.  
    }  
}

[!NOTE]
Note that you must keep a reference to the ad object outside of the ScreenAdContentCallback implementation throughout its use.

Ensure that the reference to the ad object is maintained in your code to avoid losing it and missing out on important callbacks. The ad object may be freed from memory if it is no longer in use, and in that case, callbacks will not be triggered.

App Open Ad

The App Open Ad format has been newly implemented in the com.cleveradssolutions.sdk.screen.CASAppOpen class.

// Can be initialized along with the activity.
val appOpenAd = CASAppOpen(this, casId)

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Optionally, you can register listeners.
    appOpenAd.contentCallback = screenCallback
    appOpenAd.onImpressionListener = impressionListener
}

override fun onResume() {  
    super.onResume()  
    if (appOpenAd.isLoaded) {
        appOpenAd.show(this)
    } else {
        appOpenAd.load()
    }
}

override fun onDestroy() {
    appOpenAd.destroy()
    super.onDestroy()  
}

Interstitial Ad

The Interstitial Ad format has been newly implemented in the com.cleveradssolutions.sdk.screen.CASInterstitial class.

// Can be initialized along with the activity.
val interstitialAd = CASInterstitial(this, casId)

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Optionally, you can register listeners.
    interstitialAd.contentCallback = screenCallback
    interstitialAd.onImpressionListener = impressionListener

    interstitialAd.isAutoloadEnabled = false // Disabled by default
}

fun loadInterstitialAd() {
    if (interstitialAd.isAutoloadEnabled == false) {
        interstitialAd.load()
    }
}

// Not mandatory, but you can check the ad loaded
fun isInterstitialAdLoaded(): Boolean {
    return interstitialAd.isLoaded
}

fun showInterstitialAd() {
    interstitialAd.show(this)
}

override fun onDestroy() {
    interstitialAd.destroy()
    super.onDestroy()  
}

Minimum interval between Interstitial ads

Attempting to show a new ad within this interval after the previous ad has closed will result in a call to ScreenAdContentCallback.onAdFailedToShow with AdErrorCode.NOT_PASSED_INTERVAL. By default, this interval is set to 0 seconds, or it uses the global CAS.settings.interstitialInterval value.

interstitialAd.minInterval = 0

App Return Ad

Automatic display of App Return Ads is available for CASAppOpen and CASInterstitial. To enable this feature, use the isAutoshowEnabled property. Note that the ad must be ready for display at the time of returning to the app. Disabled by default.

appOpenAd.isAutoshowEnabled = true
interstitialAd.isAutoshowEnabled = true

Rewarded Ad

The Interstitial Ad format has been newly implemented in the `com.cleveradssolutions.sdk.screen.CASRewarded class.

// Can be initialized along with the activity.
val rewardedAd = CASRewarded(this, casId)

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Optionally, you can register listeners.
    rewardedAd.contentCallback = screenCallback
    rewardedAd.onImpressionListener = impressionListener

    rewardedAd.isAutoloadEnabled = false // Disabled by default
}

fun loadRewardedAd() {
    if (rewardedAd.isAutoloadEnabled == false) {
        rewardedAd.load()
    }
}

// Not mandatory, but you can check the ad loaded
fun isRewardedAdLoaded(): Boolean {
    return rewardedAd.isLoaded
}

fun showRewardedAd() {
    rewardedAd.show(this) { ad: AdContent ->
        // Called when a user earns a reward from the ad.
    }
}

override fun onDestroy() {
    rewardedAd.destroy()
    super.onDestroy()  
}

AdError

• The AdError.message provides more detailed error information. There can be multiple detailed messages for a single error code.
• All error code constants moved from AdError to AdErrorCode.
• New errors have been added: AdErrorCode.TIMEOUT and AdErrorCode.NOT_INITIALIZED.