Custom fallback adapter

The AdMob adapter is one implementation of a small interface in qartvelo-ads-core. You can implement it yourself to fall back to another network, or to your own house ads.

QartveloAds.registerFallbackAdapter(MyNetworkAdapter())

Register before or after initialize; a registered adapter replaces the auto-discovered AdMob adapter. The fallback rules are unchanged: the placement’s fallback provider must not be none, admobFallback must be true, and an ad unit id must be known (admobAdUnits or the dashboard), or test mode must be on. The id string is passed to your adapter as-is, so you can map placement codes to your own network’s ids through admobAdUnits.

Interface

Package com.qartvelo.sdk.fallback:

interface FallbackAdapter {
    val networkName: String                                        // for logs, e.g. "mynetwork"
    fun initialize(context: Context, settings: FallbackSettings)    // once; cheap; never throw
    fun updateSettings(settings: FallbackSettings)                  // test mode or privacy changed

    fun loadInterstitial(context: Context, placementId: String, adUnitId: String, callback: FallbackLoadCallback)
    fun isInterstitialReady(placementId: String): Boolean
    fun showInterstitial(activity: Activity, placementId: String, callback: FallbackShowCallback)

    fun loadRewarded(context: Context, placementId: String, adUnitId: String, callback: FallbackLoadCallback)
    fun isRewardedReady(placementId: String): Boolean
    fun showRewarded(activity: Activity, placementId: String, callback: FallbackShowCallback)

    fun createBanner(context: Context, placementId: String, adUnitId: String, widthDp: Int,
                     callback: FallbackBannerCallback): FallbackBanner
}

data class FallbackSettings(val testMode: Boolean, val privacy: QartveloAdsPrivacy)

interface FallbackLoadCallback { fun onLoaded(); fun onFailed(message: String) }

interface FallbackShowCallback {
    fun onShown() {}
    fun onImpression() {}
    fun onClicked() {}
    fun onReward(type: String, amount: Int) {}   // only after the network confirmed the reward
    fun onDismissed() {}
    fun onShowFailed(message: String) {}
}

interface FallbackBannerCallback {
    fun onLoaded(); fun onFailed(message: String)
    fun onImpression() {}; fun onClicked() {}
}

interface FallbackBanner {
    val view: View
    fun pause(); fun resume(); fun destroy()
}

Contract

• Threading: core calls every method on the main thread. Callbacks may be invoked from any thread; core marshals them to the main thread and de-duplicates terminal events.
• Keys: ads are keyed by Qartvelo Ads placement id, so two placements may share one network unit.
• Test mode: when settings.testMode is true, substitute the network’s public test units. An empty adUnitId is only ever passed in test mode.
• Rewards: call onReward only after the network confirmed the reward; core guarantees the app sees it at most once.
• Banners: createBanner receives a MutableContextWrapper owned by core, which swaps its base context between Activities so the banner never leaks one. Start loading immediately and report through the callback; core calls pause, resume and destroy.
• Never throw: the SDK guards calls, but a throwing adapter turns every fallback into a failure.
• R8: core’s consumer rules keep the com.qartvelo.sdk.fallback interfaces; keep your adapter class if you minify and load it by name.

The AdMob implementation, com.qartvelo.admob.AdMobFallbackAdapter in the SDK repository, is a complete reference.