Integration - CloudX Documentation

The CloudX React Native SDK enables monetization of your React Native apps with banner, MREC, interstitial, and rewarded ads on iOS and Android. It supports both the New Architecture (Fabric) and the legacy architecture (Paper).

Manual Installation

Requires React Native 0.70+, React 18.0+, iOS 13.0+, and Android API 23+.

npm install cloudx-react-native

iOS Setup

Add ad network adapter pods to your ios/Podfile:

target 'YourApp' do
  # ... existing config ...

  # CloudX ad network adapters (add as needed)
  pod 'CloudXMetaAdapter', '~> 3.4.0'       # Meta Audience Network >= 6.15.1, < 7.0
  pod 'CloudXVungleAdapter', '~> 3.4.0'     # VungleAds >= 7.4.0, < 8.0
  pod 'CloudXInMobiAdapter', '~> 3.4.0'     # InMobiSDK >= 11.0.0, < 12.0
  pod 'CloudXMintegralAdapter', '~> 3.4.0'  # MintegralAdSDK ~> 8.0
  pod 'CloudXUnityAdsAdapter', '~> 3.4.0'   # UnityAds >= 4.17.0, < 5.0
  pod 'CloudXMagniteAdapter', '~> 3.4.0'    # MagniteSDK ~> 1.0.0
  pod 'CloudXMolocoAdapter', '~> 3.4.0'     # MolocoSDKiOS ~> 4.6.0
  pod 'CloudXVerveAdapter', '~> 3.4.0'      # HyBid = 3.8.0
  pod 'CloudXRenderer', '~> 3.4.0'          # CloudX test ads
end

Then install pods:

cd ios && pod install

The CloudXCore pod is automatically included as a dependency of the cloudx-react-native npm package. You only need to add the adapter pods you want.

App Transport Security

If your ads use HTTP URLs, add the following to your Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

Android Setup

Add CloudX SDK and adapter dependencies to your android/app/build.gradle:

dependencies {
    // CloudX Android SDK
    implementation "io.cloudx:sdk:4.1.0"

    // Adapters for ad networks (add as needed)
    implementation "io.cloudx:adapter-googlewaterfall:23.6.0.0"   // Google Mobile Ads SDK 23.6.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
}

At least one adapter is required for the SDK to serve ads.

If you integrate the Mintegral adapter, also declare its Maven repository in android/build.gradle:

allprojects {
    repositories {
        maven { url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea" }
    }
}

Initialization

Initialize the SDK before loading any ads:

import { CloudX, CloudXLogLevel } from 'cloudx-react-native';

// Optional: enable verbose logging (development only)
CloudX.setMinLogLevel(CloudXLogLevel.VERBOSE);

// Initialize with your app key
const result = await CloudX.initialize('YOUR_APP_KEY');
if (result.success) {
    console.log('CloudX initialized');
} else {
    console.error('CloudX init failed:', result.message);
}

CloudX.initialize() returns a CloudXInitializationResult with:

success: boolean — whether initialization succeeded
message?: string — additional details, populated on failure

Other initialization utilities:

const initialized = await CloudX.isInitialized();
const version = await CloudX.getVersion();
const tablet = await CloudX.isTablet();

Ad Formats

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

Banner & MREC ads

Create programmatic overlay display placements with optional refresh control.

Interstitial ads

Load and show full-screen interstitial placements.

Rewarded ads

Reward users after completed rewarded ad views.

Ad Information (CloudXAdInfo)

Most ad event callbacks receive a CloudXAdInfo object:

Property	Type	Description
`adUnitId`	`string`	The ad unit ID
`adFormat`	`string`	Ad format: `BANNER`, `MREC`, `INTERSTITIAL`, or `REWARDED`
`networkName`	`string`	Name of the winning ad network
`networkPlacement`	`string \| null`	Network-specific placement ID
`placement`	`string \| null`	Custom placement set by your integration
`revenue`	`number`	Revenue value in USD
`adValues`	`Record<string, string>`	SDK-provided ad metadata, used by features such as Trusted Arbiter

Error Handling

All SDK errors are returned as error objects in callbacks and rejected promises:

Property	Type	Description
`code`	`CloudXErrorCode`	Error category
`message`	`string \| null`	Human-readable description

Error Code Categories

Range	Category	Common Codes
0	General	`internalError`
100-199	Network	`networkError`, `networkTimeout`, `networkNoConnection`
200-299	Initialization	`notInitialized`, `sdkDisabled`, `invalidAppKey`
300-399	Ad Loading	`noFill`, `invalidAdUnit`, `adsDisabled`
400-499	Display	`adNotReady`, `adAlreadyShowing`
600-699	Adapter	`adapterNoFill`, `adapterTimeout`

See CloudXErrorCode export for the full list of error codes.

Advanced Features

Debug Logging

import { CloudX, CloudXLogLevel } from 'cloudx-react-native';

// Enable verbose logging (call before initialize)
CloudX.setMinLogLevel(CloudXLogLevel.VERBOSE);

// Available levels: VERBOSE, DEBUG, INFO, WARN, ERROR, NONE

Log Levels: VERBOSE < DEBUG < INFO < WARN < ERROR < NONE Native SDK logs appear in the iOS and Android platform logs. JavaScript-side calls and event handling can also be logged through your app’s normal React Native logging.

Impression-Level Revenue Tracking

Set an addAdRevenuePaidListener callback on any ad format to receive impression-level revenue events. The CloudXAdInfo object includes the revenue value in USD and the winning network name.

CloudXInterstitialAd.addAdRevenuePaidListener((adInfo) => {
    trackRevenue(adInfo.revenue, adInfo.networkName, adInfo.adUnitId);
});

Works with all React Native ad formats: banner, MREC, interstitial, and 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:

Initialize the SDK with verbose logging enabled.
Find your device advertising ID in the iOS or Android platform logs.
Add the advertising ID to your device whitelist on the CloudX server dashboard.

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 platform storage (NSUserDefaults on iOS, SharedPreferences on Android). These values are typically set automatically by your Consent Management Platform (CMP), such as Google UMP, OneTrust, or Sourcepoint.

How It Works

The native SDKs automatically detect user location and read consent signals:

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)
US Users (CCPA): Checks for sale/sharing opt-out signals
Other Regions: No restrictions applied

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

Advertising ID (IDFA/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 can be called before or after SDK initialization.

import { CloudX } from 'cloudx-react-native';

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

import { CloudX } from 'cloudx-react-native';

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

App Tracking Transparency (iOS)

Request tracking authorization on iOS 14+:

import { requestTrackingAuthorization, getTrackingAuthorizationStatus, CloudXATTStatus } from 'cloudx-react-native';

const status = await requestTrackingAuthorization();
if (status === CloudXATTStatus.AUTHORIZED) {
    console.log('Tracking authorized');
}

Call requestTrackingAuthorization() before CloudX.initialize() for best ad targeting results.

ATT status values: AUTHORIZED, DENIED, RESTRICTED, NOT_DETERMINED, NOT_REQUIRED. On Android or iOS < 14, requestTrackingAuthorization() returns NOT_REQUIRED.

Visual Debugging

Enable visual debugging overlays to see ad unit boundaries and network info:

CloudX.setVisualDebuggingEnabled(true);

Support

For support, contact mobile@cloudx.io

Documentation Index

​Manual Installation

​iOS Setup

​App Transport Security

​Android Setup

​Initialization

​Ad Formats

Banner & MREC ads

Interstitial ads

Rewarded ads

​Ad Information (CloudXAdInfo)

​Error Handling

​Error Code Categories

​Advanced Features

​Debug Logging

​Impression-Level Revenue Tracking

​Test Mode

​Privacy Compliance

​How It Works

​Supported Privacy Keys

​Manual Privacy API

​User Targeting

​App Tracking Transparency (iOS)

​Visual Debugging

​Support

Manual Installation

iOS Setup

App Transport Security

Android Setup

Initialization

Ad Formats

Ad Information (CloudXAdInfo)

Error Handling

Error Code Categories

Advanced Features

Debug Logging

Impression-Level Revenue Tracking

Test Mode

Privacy Compliance

How It Works

Supported Privacy Keys

Manual Privacy API

User Targeting

App Tracking Transparency (iOS)

Visual Debugging

Support