Overview

Overview of CloudX Android SDK setup and core features

Installation

Requires Android API 23+ and Java 8+.

The CloudX SDK and its adapters are published to Maven Central (https://repo1.maven.org/maven2/). Make sure your project resolves from it in settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()   // https://repo1.maven.org/maven2/
    }
}

Then add the CloudX SDK to your app’s build.gradle:

dependencies {
    implementation("io.cloudx:sdk:4.5.0")

    // Adapters for ad networks
    implementation("io.cloudx:adapter-digitalturbine:8.4.7.0")     // Digital Turbine Marketplace SDK 8.4.7
    implementation("io.cloudx:adapter-googlewaterfall:25.2.0.3")   // Google Mobile Ads SDK 25.2.0
    implementation("io.cloudx:adapter-inmobi:11.4.0.1")            // InMobi SDK 11.4.0
    implementation("io.cloudx:adapter-magnite:1.0.0.1")            // Magnite Ads SDK 1.0.0
    implementation("io.cloudx:adapter-meta:6.22.0.0")              // Meta Audience Network 6.22.0
    implementation("io.cloudx:adapter-mintegral:17.1.71.0")        // Mintegral SDK 17.1.71
    implementation("io.cloudx:adapter-mobilefuse:1.11.0.1")        // MobileFuse SDK 1.11.0
    implementation("io.cloudx:adapter-moloco:4.11.0.0")            // Moloco SDK 4.11.0
    implementation("io.cloudx:adapter-pangle:8.2.0.4.0")           // Pangle SDK 8.2.0.4
    implementation("io.cloudx:adapter-taurusx:1.18.3.0")           // TaurusX SDK 1.18.3
    implementation("io.cloudx:adapter-unityads:4.19.0.1")          // Unity Ads SDK 4.19.0
    implementation("io.cloudx:adapter-verve:3.9.0.1")              // Verve HyBid SDK 3.9.0
    implementation("io.cloudx:adapter-vungle:7.7.7.0")             // Vungle SDK 7.7.7
}

dependencies {
    implementation 'io.cloudx:sdk:4.5.0'

    // Adapters for ad networks
    implementation 'io.cloudx:adapter-digitalturbine:8.4.7.0'     // Digital Turbine Marketplace SDK 8.4.7
    implementation 'io.cloudx:adapter-googlewaterfall:25.2.0.3'   // Google Mobile Ads SDK 25.2.0
    implementation 'io.cloudx:adapter-inmobi:11.4.0.1'            // InMobi SDK 11.4.0
    implementation 'io.cloudx:adapter-magnite:1.0.0.1'            // Magnite Ads SDK 1.0.0
    implementation 'io.cloudx:adapter-meta:6.22.0.0'              // Meta Audience Network 6.22.0
    implementation 'io.cloudx:adapter-mintegral:17.1.71.0'        // Mintegral SDK 17.1.71
    implementation 'io.cloudx:adapter-mobilefuse:1.11.0.1'        // MobileFuse SDK 1.11.0
    implementation 'io.cloudx:adapter-moloco:4.11.0.0'            // Moloco SDK 4.11.0
    implementation 'io.cloudx:adapter-pangle:8.2.0.4.0'           // Pangle SDK 8.2.0.4
    implementation 'io.cloudx:adapter-taurusx:1.18.3.0'           // TaurusX SDK 1.18.3
    implementation 'io.cloudx:adapter-unityads:4.19.0.1'          // Unity Ads SDK 4.19.0
    implementation 'io.cloudx:adapter-verve:3.9.0.1'              // Verve HyBid SDK 3.9.0
    implementation 'io.cloudx:adapter-vungle:7.7.7.0'             // Vungle SDK 7.7.7
}

Initialization

// Initialize with app key
CloudX.initialize(
    configuration = CloudXInitializationConfiguration.builder("your-app-key-here")
        .build(),
    listener = object : CloudXInitializationListener {
        override fun onInitialized(configuration: CloudXSdkConfiguration) {
            Log.d("CloudX", "CloudX SDK initialized successfully")
        }

        override fun onInitializationFailed(cloudXError: CloudXError) {
            Log.e("CloudX", "Failed to initialize CloudX SDK: ${cloudXError.message}")
        }
    }
)

// Initialize with app key
CloudXInitializationConfiguration configuration = CloudXInitializationConfiguration.builder("your-app-key-here")
    .build();

CloudX.initialize(configuration, new CloudXInitializationListener() {
    @Override
    public void onInitialized(@NonNull CloudXSdkConfiguration configuration) {
        Log.d("CloudX", "CloudX SDK initialized successfully");
    }

    @Override
    public void onInitializationFailed(@NonNull CloudXError cloudXError) {
        Log.e("CloudX", "Failed to initialize CloudX SDK: " + cloudXError.getMessage());
    }
});

Ad Formats

CloudX supports banner, MREC, interstitial, rewarded, native, and App Open ad integrations. Use the format-specific guides for implementation details:

Ad Information (CloudXAd)

The CloudXAd object is passed to listener callbacks and contains information about the loaded/displayed ad:

override fun onAdLoaded(cloudXAd: CloudXAd) {
    Log.d("CloudX", "Ad format: ${cloudXAd.adFormat}")
    Log.d("CloudX", "Network: ${cloudXAd.networkName}")
    Log.d("CloudX", "Bid-time revenue: ${cloudXAd.revenue}")
}

Error Handling

All SDK errors are returned as CloudXError objects in listener callbacks:

Error Code Categories

Advanced Features

Debug Logging

CloudX.setMinLogLevel(CloudXLogLevel.DEBUG)  // Enable debug logging
CloudX.setMinLogLevel(CloudXLogLevel.NONE)   // Disable all logging

CloudX.setMinLogLevel(CloudXLogLevel.DEBUG);  // Enable debug logging
CloudX.setMinLogLevel(CloudXLogLevel.NONE);   // Disable all logging

Log Levels: VERBOSE < DEBUG < INFO < WARN < ERROR < NONE

Filter logcat with tag CloudX to see SDK logs.

Publisher-Reported Revenue Data

If your app receives impression-level revenue callbacks or bid metadata from AdMob, InMobi, TopOn, or another mediation platform outside the CloudX ad flow, forward those events to CloudX after initialization:

reportRevenueData() returns true when the event is accepted into the CloudX revenue pipeline. It returns false if the SDK is not initialized, server-side revenue tracking is disabled, or the platform name is blank. Acceptance is not a delivery guarantee.

AdMob paid events

AdMob Android AdValue.valueMicros is reported in micro-units of the supplied currency, so divide it by 1_000_000.0 before passing it to CloudX.

private fun Int.toCloudXRevenuePrecision(): CloudXRevenuePrecision = when (this) {
    AdValue.PrecisionType.PRECISE -> CloudXRevenuePrecision.EXACT
    AdValue.PrecisionType.ESTIMATED -> CloudXRevenuePrecision.ESTIMATED
    AdValue.PrecisionType.PUBLISHER_PROVIDED -> CloudXRevenuePrecision.PUBLISHER_DEFINED
    else -> CloudXRevenuePrecision.UNDEFINED
}

private fun reportAdMobPaidEvent(
    adValue: AdValue,
    adFormat: String,
    adUnitId: String,
    responseInfo: ResponseInfo?,
): Boolean {
    val servedBy = responseInfo?.loadedAdapterResponseInfo

    return CloudX.reportRevenueData(
        CloudXRevenueData.builder(
            platform = CloudXRevenuePlatform.ADMOB,
            revenue = adValue.valueMicros / 1_000_000.0,
            adFormat = adFormat,
        )
            .currencyCode(adValue.currencyCode)
            .precision(adValue.precisionType.toCloudXRevenuePrecision())
            .networkName(servedBy?.adSourceName)
            .adUnitId(adUnitId)
            .thirdPartyAdPlacementId(servedBy?.adSourceInstanceName)
            .build(),
    )
}

bannerView.setOnPaidEventListener { adValue ->
    reportAdMobPaidEvent(
        adValue = adValue,
        adFormat = "banner",
        adUnitId = adUnitId,
        responseInfo = bannerView.responseInfo,
    )
}

InMobi impression events

For InMobi, save the AdMetaInfo object from onAdFetchSuccessful. When onAdImpression fires, send the saved metaInfo.bid to CloudX, then clear the saved value.

private var latestInMobiMetaInfo: AdMetaInfo? = null

override fun onAdFetchSuccessful(ad: InMobiBanner, info: AdMetaInfo) {
    latestInMobiMetaInfo = info
}

override fun onAdImpression(ad: InMobiBanner) {
    latestInMobiMetaInfo?.let { metaInfo ->
        reportInMobiImpression(
            metaInfo = metaInfo,
            adFormat = "banner",
            placementId = inMobiPlacementId.toString(),
        )
    }
    latestInMobiMetaInfo = null
}

private fun reportInMobiImpression(
    metaInfo: AdMetaInfo,
    adFormat: String,
    placementId: String,
): Boolean =
    CloudX.reportRevenueData(
        CloudXRevenueData.builder(
            platform = CloudXRevenuePlatform.INMOBI,
            revenue = metaInfo.bid,
            adFormat = adFormat,
        )
            .precision(CloudXRevenuePrecision.ESTIMATED)
            .thirdPartyAdPlacementId(placementId)
            .creativeId(metaInfo.creativeID)
            .build(),
    )

For interstitial and rewarded InMobi ads, use the same pattern with InterstitialAdEventListener: save AdMetaInfo in onAdFetchSuccessful, then report it in onAdImpression.

TopOn revenue events

TopOn Android reports revenue in onAdRevenuePaid(ATAdInfo). Set an ATAdRevenueListener on the ad object and pass adInfo.getPublisherRevenue() directly to CloudX. Do not divide this value like AdMob micros or CPM.

private fun reportTopOnRevenue(
    adInfo: ATAdInfo,
    adFormat: String,
): Boolean =
    CloudX.reportRevenueData(
        CloudXRevenueData.builder(
            platform = CloudXRevenuePlatform.TOPON,
            revenue = adInfo.getPublisherRevenue(),
            adFormat = adFormat,
        )
            .currencyCode(adInfo.getCurrency())
            .networkName(adInfo.getNetworkName())
            .adUnitId(adInfo.getPlacementId())
            .thirdPartyAdPlacementId(adInfo.getNetworkPlacementId())
            .networkPlacement(adInfo.getAdsourceId())
            .build(),
    )

mBannerView.setAdRevenueListener(object : ATAdRevenueListener {
    override fun onAdRevenuePaid(adInfo: ATAdInfo) {
        reportTopOnRevenue(
            adInfo = adInfo,
            adFormat = "banner",
        )
    }
})

For other TopOn ad formats, set the same listener on the loaded ad object and pass the matching CloudX adFormat.

Custom platform events

Use custom for providers that do not have a CloudX SDK constant like AdMob, InMobi, and TopOn do. The value is only the provider name, such as CloudXRevenuePlatform.custom("TradPlus") or CloudXRevenuePlatform.custom("Nimbus"). Keep the name stable so CloudX can group that provider’s revenue consistently.

Do not include the amount or currency in the provider name. For a TradPlus impression worth USD 0.01, send platform = CloudXRevenuePlatform.custom("TradPlus"), revenue = 0.01, and .currencyCode("USD"). If your source reports CPM/eCPM, divide by 1_000.0 first.

private fun reportCustomRevenueEvent(
    providerName: String,
    revenue: Double,
    adFormat: String,
    currencyCode: String,
    adUnitId: String,
    placementId: String,
): Boolean =
    CloudX.reportRevenueData(
        CloudXRevenueData.builder(
            platform = CloudXRevenuePlatform.custom(providerName),
            revenue = revenue,
            adFormat = adFormat,
        )
            .currencyCode(currencyCode)
            .precision(CloudXRevenuePrecision.PUBLISHER_DEFINED)
            .adUnitId(adUnitId)
            .thirdPartyAdPlacementId(placementId)
            .build(),
    )

Impression-Level Revenue Tracking

Set a revenueListener on any ad format to receive revenue callbacks. CloudXAd.revenue contains the bid-time USD estimate.

bannerAd.revenueListener = object : CloudXAdRevenueListener {
    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
        Log.d("CloudX", "Bid-time revenue: ${cloudXAd.revenue} from ${cloudXAd.networkName}")
    }
}

bannerAd.setRevenueListener(new CloudXAdRevenueListener() {
    @Override
    public void onAdRevenuePaid(@NonNull CloudXAd cloudXAd) {
        Log.d("CloudX", "Bid-time revenue: " + cloudXAd.getRevenue() + " from " + cloudXAd.getNetworkName());
    }
});

Works with all ad formats (banner, MREC, interstitial, rewarded).

Test Mode

Test mode is server-controlled via device whitelisting. This provides better security and control over which devices receive test ads.

To enable test mode:

1. Initialize the SDK and check logcat for your device advertising ID:

   [CloudX][AdvertisingIdProvider] Device IFA for test whitelisting: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (LAT: false)
   

2. Copy the advertising ID and add it to your device whitelist on the CloudX server dashboard

3. The SDK will automatically configure adapters for test mode and include the test flag in bid requests

Note: Test mode is determined by the server, so you don’t need to change any code between development and production builds.

Privacy Compliance

The CloudX SDK supports GDPR and CCPA privacy compliance by reading standard IAB privacy strings from SharedPreferences. These values are typically set automatically by your Consent Management Platform (CMP) such as Google UMP, OneTrust, or Sourcepoint.

How It Works

The SDK automatically detects user location and reads consent signals:

1. EU Users (GDPR): Checks TCF v2 consent for purposes 1 and 2 per the IAB Global Vendor List and vendor consent (CloudX Vendor ID: 1510)
2. US Users (CCPA): Checks for sale/sharing opt-out signals
3. Other Regions: No restrictions applied

When consent is denied or user opts out, the SDK removes PII from ad requests:

• Advertising ID (GAID) is cleared
• Geo coordinates (lat/lon) are removed
• User key-values are not sent
• Hashed user ID is removed from bidder-bound requests and suppressed from impression reporting

Supported Privacy Keys

Note: The SDK prioritizes GPP (modern standard) over legacy TCF/US Privacy strings when both are available.

Manual Privacy API

If you manage user consent yourself (without a CMP), you can set GDPR and CCPA privacy status directly. These must be called prior to SDK initialization.

// GDPR consent: true, false, or null to defer to CMP
CloudX.setHasUserConsent(true)

// CCPA do-not-sell: true, false, or null to defer to CMP
CloudX.setDoNotSell(true)

// GDPR consent: true, false, or null to defer to CMP
CloudX.setHasUserConsent(true);

// CCPA do-not-sell: true, false, or null to defer to CMP
CloudX.setDoNotSell(true);

User Targeting

// Set hashed user ID for targeting
CloudX.setHashedUserId("hashed-user-id")

// Set custom user key-value pairs
CloudX.setUserKeyValue("age", "25")
CloudX.setUserKeyValue("gender", "male")
CloudX.setUserKeyValue("location", "US")

// Set custom app key-value pairs
CloudX.setAppKeyValue("app_version", "1.0.0")
CloudX.setAppKeyValue("user_level", "premium")

// Clear all custom key-values
CloudX.clearAllKeyValues()

// Set hashed user ID for targeting
CloudX.setHashedUserId("hashed-user-id");

// Set custom user key-value pairs
CloudX.setUserKeyValue("age", "25");
CloudX.setUserKeyValue("gender", "male");
CloudX.setUserKeyValue("location", "US");

// Set custom app key-value pairs
CloudX.setAppKeyValue("app_version", "1.0.0");
CloudX.setAppKeyValue("user_level", "premium");

// Clear all custom key-values
CloudX.clearAllKeyValues();

The hashed user ID is a publisher-provided pseudonymous identifier. When applicable privacy signals allow it, CloudX captures the value at auction time and returns it as hashed_user_id in the impression-level revenue export. Use it to join CloudX revenue to cohorts in your own user data. The export value is empty when no ID was set, persistence was suppressed by privacy signals, or the value exceeded 128 characters. Do not pass raw personal data.

User and app key-values are also available in the request activity export. Use setUserKeyValue for session-wide user attributes and setAppKeyValue for session-wide app attributes. The SDK sends current values with each later auction request.

For metadata that belongs to one ad object or load, call setExtraParameter before load:

adView.setExtraParameter("requestId", "request-456")
adView.setExtraParameter("impressionKey", "impression-789")
adView.load()

Extra parameters remain on that ad object until changed or cleared. The SDK snapshots them for each load. CloudX returns the complete bag in the extra_parameters request-export column. The reserved tags key also controls tag-based routing; use another key for correlation metadata.

CloudX stores each of the three compact JSON bags only when the entire bag is at most 256 UTF-8 bytes. The limit is independent for each export column and includes all combined keys, values, quotes, separators, and braces—not 256 bytes per K/V pair. When privacy rules prohibit publisher-data persistence, or a bag is malformed or too large, its export cell is empty. Do not include raw personal data, secrets, or consent strings.

Support

For support, contact support@cloudx.io