Integration

Complete guide to integrating the CloudX Android SDK

Automated Integration with Claude Code

Integrate CloudX SDK in 15 minutes with AI-powered agents:

Requires Claude Code.

# Install CloudX agents
bash <(curl -fsSL https://raw.githubusercontent.com/cloudx-io/cloudx-sdk-agents/main/scripts/install.sh)

# In your Android project:
claude "Use @agent-cloudx-android-integrator to integrate CloudX SDK with app key: YOUR_KEY"

• First-look CloudX with automatic fallback to existing ad setup
• Privacy compliance validation (GDPR, CCPA)
• Build verification catches errors early
• Preserves existing ad setup as backup

Full Setup Guide

Manual Installation

Requires Android API 23+ and Java 8+.

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

Kotlin DSL

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

    // Adapters for ad networks
    implementation("io.cloudx:adapter-digitalturbine:8.4.5.0")     // Digital Turbine Marketplace SDK 8.4.5
    implementation("io.cloudx:adapter-googlewaterfall:25.1.0.0")   // Google Mobile Ads SDK 25.1.0
    implementation("io.cloudx:adapter-inmobi:11.2.0.0")            // InMobi SDK 11.2.0
    implementation("io.cloudx:adapter-magnite:1.0.0.0")            // Magnite Ads SDK 1.0.0
    implementation("io.cloudx:adapter-meta:6.21.0.1")              // Meta Audience Network 6.21.0
    implementation("io.cloudx:adapter-mintegral:17.1.51.0")        // Mintegral SDK 17.1.51
    implementation("io.cloudx:adapter-moloco:4.8.0.0")             // Moloco SDK 4.8.0
    implementation("io.cloudx:adapter-unityads:4.17.0.0")          // Unity Ads SDK 4.17.0
    implementation("io.cloudx:adapter-verve:3.8.1.0")              // Verve HyBid SDK 3.8.1
    implementation("io.cloudx:adapter-vungle:7.7.3.0")             // Vungle SDK 7.7.3
}

Initialization

Kotlin

// 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}")
        }
    }
)

Ad Formats

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

Banner & MREC ads

Create fixed-size display placements with optional refresh control.

Interstitial ads

Load and show full-screen interstitial placements.

Native ads

Render native creatives and Reels-style native video experiences.

Rewarded ads

Reward users after completed rewarded ad views.

Ad Information (CloudXAd)

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

Property	Type	Description
adFormat	CloudXAdFormat	Ad format (BANNER, MREC, INTERSTITIAL, REWARDED, NATIVE)
adUnitId	String	The ad unit ID
networkName	String	Name of the winning ad network
networkPlacement	String?	Network-specific placement ID
placement	String?	Custom placement set via setPlacement()
revenue	Double	Bid-time revenue estimate in USD
adValues	Map<String, String>	SDK-provided ad metadata, used by features such as Trusted Arbiter

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:

Property	Type	Description
code	CloudXErrorCode	Error category
message	String	Human-readable description
cause	Throwable?	Optional underlying exception
formattedMessage	String	Pre-formatted message including code and description

Error Code Categories

Range	Category	Common Codes
0	General	INTERNAL_ERROR
100-199	Network	NETWORK_ERROR, NETWORK_TIMEOUT, NETWORK_SERVER_ERROR, NETWORK_NO_CONNECTION
200-299	Initialization	NOT_INITIALIZED, SDK_DISABLED, NO_ADAPTERS_FOUND, INVALID_APP_KEY
300-399	Ad Loading	NO_FILL, INVALID_AD_UNIT, ADS_DISABLED
400-499	Display	AD_NOT_READY, AD_ALREADY_SHOWING
600-699	Adapter	ADAPTER_NO_FILL, ADAPTER_TIMEOUT, ADAPTER_LOAD_TIMEOUT, ADAPTER_INITIALIZATION_ERROR

Advanced Features

Debug Logging

Kotlin

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.

Impression-Level Revenue Tracking

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

Kotlin

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

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 excluded

Supported Privacy Keys

Key	Standard	Description
IABGPP_HDR_GppString	GPP	Global Privacy Platform string (modern)
IABGPP_GppSID	GPP	Section IDs (e.g., “2” for EU, “7” for US-National, “8” for US-CA)
IABTCF_TCString	TCF v2	GDPR consent string (legacy)
IABTCF_gdprApplies	TCF v2	Whether GDPR applies (1 = yes, 0 = no)
IABUSPrivacy_String	US Privacy	CCPA privacy string (legacy, e.g., “1YNN”)

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.

Kotlin

// 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)

When both manual values and CMP signals are present, CMP signals (GPP/TCF/US Privacy) take priority. Manual values act as a fallback when no CMP is integrated.

User Targeting

Kotlin

// 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()

Support

For support, contact [e-mail]