Android SDK

1. Installation

The Oprello Ads SDK is currently distributed as an AAR file. Add it as a local dependency in your app module:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        // Maven Central publication coming soon
    }
}

// app/build.gradle.kts
dependencies {
    implementation(files("libs/oprello-ads-sdk.aar"))

    // Required dependencies
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("com.squareup.moshi:moshi-kotlin:1.15.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
    implementation("androidx.media3:media3-exoplayer:1.2.0")
}

Maven Central publication coming soon. Contact partnerships@oprello.com to receive the SDK AAR file.

2. Initialization

Initialize the SDK as early as possible, typically in your Application.onCreate() or main Activity:

import com.oprello.ads.sdk.OprelloAdsManager

OprelloAdsManager.initialize(
    context = applicationContext,
    appId = "YOUR_APP_ID",
    onReady = {
        // SDK is ready for ad requests
        // You can start loading ads here
    },
    onConfigLoaded = {
        // Server config loaded successfully
        // Ad units are now validated
    },
    onFailure = { error ->
        // Initialization failed
        Log.e("Oprello", "Init failed: ${error.message}")
    }
)

The appId is found in the Oprello dashboard under your app settings.

3. Banner Ads

import com.oprello.ads.sdk.OprelloBannerAd
import com.oprello.ads.sdk.OprelloBannerAdDelegate
import com.oprello.ads.sdk.BannerAdSize

val bannerAd = OprelloBannerAd(adUnitId = "YOUR_BANNER_AD_UNIT_ID")
bannerAd.delegate = object : OprelloBannerAdDelegate {
    override fun bannerAdDidLoadMetadata(bannerAd: OprelloBannerAd, adResponse: BannerAdResponse) {
        // Metadata loaded, now load assets
        bannerAd.loadAssets()
    }
    override fun bannerAdDidLoadAssets(bannerAd: OprelloBannerAd) {
        // Assets ready, show the ad
        bannerAd.show(containerView)
    }
    override fun bannerAdDidTrackImpression(bannerAd: OprelloBannerAd) {
        // Impression tracked
    }
    override fun bannerAdDidFailToLoadMetadata(bannerAd: OprelloBannerAd, error: Throwable) {
        Log.e("Oprello", "Banner load failed: ${error.message}")
    }
    override fun bannerAdDidClick(bannerAd: OprelloBannerAd) {
        // User clicked the ad
    }
}

// Load with a specific size
val size = BannerAdSize(320, 50) // or BannerAdSize.BANNER_300x250
bannerAd.loadMetadata(size)

Available sizes: BANNER_320x50, BANNER_300x250, BANNER_728x90, and adaptive sizes via BannerAdSize.portrait(width), BannerAdSize.small(width), etc.

4. Interstitial Ads

import com.oprello.ads.sdk.OprelloInterstitialAd
import com.oprello.ads.sdk.OprelloInterstitialAdDelegate

val interstitialAd = OprelloInterstitialAd(adUnitId = "YOUR_INTERSTITIAL_AD_UNIT_ID")
interstitialAd.delegate = object : OprelloInterstitialAdDelegate {
    override fun interstitialAdDidLoadMetadata(interstitialAd: OprelloInterstitialAd, adResponse: InterstitialAdResponse) {
        interstitialAd.loadAssets()
    }
    override fun interstitialAdDidLoadAssets(interstitialAd: OprelloInterstitialAd) {
        // Ad is ready to present
    }
    override fun interstitialAdDidPresent(interstitialAd: OprelloInterstitialAd) {
        // Full-screen ad presented
    }
    override fun interstitialAdDidDismiss(interstitialAd: OprelloInterstitialAd) {
        // User closed the ad
    }
    override fun interstitialAdDidFailToLoadMetadata(interstitialAd: OprelloInterstitialAd, error: Throwable) {
        Log.e("Oprello", "Interstitial load failed: ${error.message}")
    }
}

// Load the ad
interstitialAd.loadMetadata()

// Present when ready (e.g., at a natural transition point)
if (interstitialAd.isReady()) {
    interstitialAd.present(activity)
}

5. Rewarded Ads

import com.oprello.ads.sdk.OprelloRewardedAd
import com.oprello.ads.sdk.OprelloRewardedAdDelegate

val rewardedAd = OprelloRewardedAd(adUnitId = "YOUR_REWARDED_AD_UNIT_ID")
rewardedAd.delegate = object : OprelloRewardedAdDelegate {
    override fun rewardedAdDidLoadMetadata(rewardedAd: OprelloRewardedAd, adResponse: RewardedAdResponse) {
        rewardedAd.loadAssets()
    }
    override fun rewardedAdDidLoadAssets(rewardedAd: OprelloRewardedAd) {
        // Ad is ready to present
    }
    override fun rewardedAdDidEarnReward(rewardedAd: OprelloRewardedAd) {
        // Grant the user their reward
    }
    override fun rewardedAdDidDismiss(rewardedAd: OprelloRewardedAd) {
        // Check if reward was earned
        if (rewardedAd.hasEarnedReward()) {
            // Reward confirmed
        }
        rewardedAd.reset() // Reset for next ad load
    }
    override fun rewardedAdDidFailToLoadMetadata(rewardedAd: OprelloRewardedAd, error: Throwable) {
        Log.e("Oprello", "Rewarded load failed: ${error.message}")
    }
}

rewardedAd.loadMetadata()

// Present when ready
if (rewardedAd.isReady()) {
    rewardedAd.present(activity)
}

6. Native Ads

import com.oprello.ads.sdk.OprelloNativeAd
import com.oprello.ads.sdk.OprelloNativeAdDelegate

val nativeAd = OprelloNativeAd(adUnitId = "YOUR_NATIVE_AD_UNIT_ID")
nativeAd.delegate = object : OprelloNativeAdDelegate {
    override fun nativeAdDidLoadMetadata(nativeAd: OprelloNativeAd, adResponse: NativeAdResponse) {
        nativeAd.loadAssets()
    }
    override fun nativeAdDidLoadAssets(nativeAd: OprelloNativeAd) {
        // Bind ad data to your custom views
        val assets = nativeAd.adResponse?.assets
        titleTextView.text = assets?.title
        bodyTextView.text = assets?.body
        ctaButton.text = assets?.ctaText

        // Load images
        assets?.images?.firstOrNull()?.url?.let { url ->
            val bitmap = nativeAd.getLoadedImage(url)
            mainImageView.setImageBitmap(bitmap)
        }

        // Register the container view for impression tracking
        nativeAd.registerView(containerView)
    }
    override fun nativeAdDidClick(nativeAd: OprelloNativeAd) {
        // User clicked the ad
    }
}

nativeAd.loadMetadata()

// Handle clicks on CTA button
ctaButton.setOnClickListener {
    nativeAd.performClick()
}

7. App Open Ads

import com.oprello.ads.sdk.OprelloAppOpenAd
import com.oprello.ads.sdk.OprelloAppOpenAdDelegate

val appOpenAd = OprelloAppOpenAd(adUnitId = "YOUR_APP_OPEN_AD_UNIT_ID")
appOpenAd.delegate = object : OprelloAppOpenAdDelegate {
    override fun appOpenAdDidLoadMetadata(appOpenAd: OprelloAppOpenAd, adResponse: AppOpenAdResponse) {
        appOpenAd.loadAssets()
    }
    override fun appOpenAdDidLoadAssets(appOpenAd: OprelloAppOpenAd) {
        // Ad is ready to present on next app foreground
    }
    override fun appOpenAdDidDismiss(appOpenAd: OprelloAppOpenAd) {
        // User closed the ad, load next one
        appOpenAd.reset()
        appOpenAd.loadMetadata()
    }
}

// Load on app start
appOpenAd.loadMetadata()

// Present when app comes to foreground (in your lifecycle observer)
if (appOpenAd.isReady()) {
    appOpenAd.present(activity)
}

8. Privacy & Consent

Set privacy signals before loading ads. The SDK also auto-reads from IAB CMP SharedPreferences.

// GDPR - set consent status and TCF string
OprelloAdsManager.setGDPRConsent(applies = true, consentString = "TCF_CONSENT_STRING")

// CCPA - set US Privacy string
OprelloAdsManager.setUSPrivacy("1YNN")

// GPP - set Global Privacy Platform string
OprelloAdsManager.setGPPConsent(gppString = "GPP_STRING", sectionIds = listOf(2, 6))

// COPPA - for child-directed apps
OprelloAdsManager.setCOPPA(applies = true)

// Under age of consent
OprelloAdsManager.setUserIsUnderAgeOfConsent(isUnder = true)

9. SDK Size

The Oprello Ads SDK AAR is approximately 500 KB. However, the SDK depends on several third-party libraries that contribute to your app's total size:

Actual size impact depends on your app's existing dependencies. If your app already uses OkHttp or ExoPlayer, the incremental size increase will be smaller. ProGuard/R8 minification further reduces the final APK contribution.

10. Google Play Data Safety

If your app is published on Google Play, you must declare the data the Oprello SDK collects in your Data Safety section. We provide a detailed guide covering exactly which checkboxes to select.

View the full Google Play Data Safety disclosure guide →

11. Testing

Enable test mode to receive test creatives instead of production ads:

import com.oprello.ads.sdk.OprelloAdsTestManager

// Enable test mode
OprelloAdsTestManager.setTestMode(true)

// Check test mode status
val isTestMode = OprelloAdsTestManager.getTestModeEnabled()

// Disable test mode for production
OprelloAdsTestManager.setTestMode(false)

For debug logging, filter Logcat with the tag OprelloAdsDebugLog. Debug logging is enabled by default and can be controlled via server config.