Skip to main content

​
CloudX React Native SDK

npm 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).

​
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', '~> 2.2.3'
  pod 'CloudXVungleAdapter', '~> 2.2.3'
  pod 'CloudXInMobiAdapter', '~> 2.2.3'
  pod 'CloudXRenderer', '~> 2.2.3'
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:2.2.3"

    // Adapters for ad networks (add as needed)
    implementation "io.cloudx:adapter-cloudx:2.2.3"
    implementation "io.cloudx:adapter-meta:2.2.3"
    implementation "io.cloudx:adapter-vungle:2.2.3"
    implementation "io.cloudx:adapter-inmobi:2.2.3"
}
At least one adapter is required for the SDK to serve ads.

​
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 Integration

Banners use the programmatic overlay approach — they overlay your content at a fixed screen position. 
import { CloudXBannerAd, CloudXAdPosition } from 'cloudx-react-native';

const AD_UNIT_ID = 'home_banner';

// Set up event listeners
CloudXBannerAd.addAdLoadedEventListener((adInfo) => {
    console.log('Banner loaded from', adInfo.networkName);
});
CloudXBannerAd.addAdLoadFailedEventListener((error) => {
    console.log('Banner failed:', error.code, error.message);
});
CloudXBannerAd.addAdRevenuePaidListener((adInfo) => {
    console.log('Banner revenue:', adInfo.revenue);
});

// Create and show
CloudXBannerAd.createAd(AD_UNIT_ID, CloudXAdPosition.BOTTOM_CENTER);
CloudXBannerAd.showAd(AD_UNIT_ID);

// Hide / destroy when done
CloudXBannerAd.hideAd(AD_UNIT_ID);
CloudXBannerAd.destroyAd(AD_UNIT_ID);
Auto-refresh is enabled by default. To control it manually: 
CloudXBannerAd.stopAutoRefresh(AD_UNIT_ID);
CloudXBannerAd.startAutoRefresh(AD_UNIT_ID);
Use CloudXAdPosition to place the banner: TOP_LEFT, TOP_CENTER, TOP_RIGHT, CENTER_LEFT, CENTERED, CENTER_RIGHT, BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT For pixel-level control, use offsets: 
CloudXBannerAd.createAdWithOffsets(AD_UNIT_ID, CloudXAdPosition.TOP_CENTER, 0, 50);
CloudXBannerAd.updatePosition(AD_UNIT_ID, CloudXAdPosition.BOTTOM_CENTER);
CloudXBannerAd.updateOffsets(AD_UNIT_ID, 0, 20);

​
Additional Banner APIs

CloudXBannerAd.setBackgroundColor(AD_UNIT_ID, '#000000');
CloudXBannerAd.setPlacement(AD_UNIT_ID, 'home_screen');
CloudXBannerAd.setCustomData(AD_UNIT_ID, 'custom_data');
Event ListenerCallback Type
addAdLoadedEventListenerCloudXAdInfo
addAdLoadFailedEventListenerCloudXAdLoadFailedInfo
addAdClickedEventListenerCloudXAdInfo
addAdExpandedEventListenerCloudXAdInfo
addAdCollapsedEventListenerCloudXAdInfo
addAdRevenuePaidListenerCloudXAdInfo
Each listener has a corresponding remove* method (e.g., removeAdLoadedEventListener()).

​
MREC Ads (300x250)

MRECs work identically to banners but with a 300x250 size. Use the CloudXMRECAd module: 
import { CloudXMRECAd, CloudXAdPosition } from 'cloudx-react-native';

const AD_UNIT_ID = 'home_mrec';

CloudXMRECAd.addAdLoadedEventListener((adInfo) => {
    console.log('MREC loaded from', adInfo.networkName);
});

CloudXMRECAd.createAd(AD_UNIT_ID, CloudXAdPosition.CENTERED);
CloudXMRECAd.showAd(AD_UNIT_ID);

// Destroy when done
CloudXMRECAd.destroyAd(AD_UNIT_ID);
The CloudXMRECAd API is identical to CloudXBannerAd — all the same methods and events are available, including createAdWithOffsets, updatePosition, updateOffsets, setBackgroundColor, setPlacement, setCustomData, auto-refresh control, and all event listeners.

​
Interstitial Ads

Full-screen ads shown at natural transition points. 
import { CloudXInterstitialAd } from 'cloudx-react-native';

const AD_UNIT_ID = 'level_complete';

// Set up event listeners
CloudXInterstitialAd.addAdLoadedEventListener((adInfo) => {
    console.log('Interstitial loaded');
});
CloudXInterstitialAd.addAdLoadFailedEventListener((error) => {
    console.log('Interstitial load failed:', error.code, error.message);
});
CloudXInterstitialAd.addAdDisplayedEventListener((adInfo) => {
    console.log('Interstitial displayed');
});
CloudXInterstitialAd.addAdFailedToDisplayEventListener((error) => {
    console.log('Interstitial display failed:', error.code, error.message);
});
CloudXInterstitialAd.addAdHiddenEventListener((adInfo) => {
    // Reload for next use
    CloudXInterstitialAd.loadAd(AD_UNIT_ID);
});
CloudXInterstitialAd.addAdRevenuePaidListener((adInfo) => {
    console.log('Revenue:', adInfo.revenue);
});

// Load
CloudXInterstitialAd.loadAd(AD_UNIT_ID);

// Show when ready (with optional placement and custom data)
const isReady = await CloudXInterstitialAd.isAdReady(AD_UNIT_ID);
if (isReady) {
    CloudXInterstitialAd.showAd(AD_UNIT_ID);
    // or: CloudXInterstitialAd.showAd(AD_UNIT_ID, 'placement_name', 'custom_data');
}

// Destroy when done
CloudXInterstitialAd.destroyAd(AD_UNIT_ID);

​
Interstitial Events

Event ListenerCallback Type
addAdLoadedEventListenerCloudXAdInfo
addAdLoadFailedEventListenerCloudXAdLoadFailedInfo
addAdDisplayedEventListenerCloudXAdInfo
addAdFailedToDisplayEventListenerCloudXAdDisplayFailedInfo
addAdClickedEventListenerCloudXAdInfo
addAdHiddenEventListenerCloudXAdInfo
addAdRevenuePaidListenerCloudXAdInfo

​
Rewarded Ads

Full-screen ads that grant users a reward upon completion. 
import { CloudXRewardedAd } from 'cloudx-react-native';

const AD_UNIT_ID = 'rewarded_coins';

// Set up event listeners
CloudXRewardedAd.addAdLoadedEventListener((adInfo) => {
    console.log('Rewarded loaded');
});
CloudXRewardedAd.addAdLoadFailedEventListener((error) => {
    console.log('Rewarded load failed:', error.code, error.message);
});
CloudXRewardedAd.addAdDisplayedEventListener((adInfo) => {
    console.log('Rewarded displayed');
});
CloudXRewardedAd.addAdFailedToDisplayEventListener((error) => {
    console.log('Rewarded display failed:', error.code, error.message);
});
CloudXRewardedAd.addAdReceivedRewardEventListener((rewardInfo) => {
    console.log(`Earned ${rewardInfo.rewardAmount} ${rewardInfo.rewardLabel}`);
});
CloudXRewardedAd.addAdHiddenEventListener((adInfo) => {
    // Reload for next use
    CloudXRewardedAd.loadAd(AD_UNIT_ID);
});
CloudXRewardedAd.addAdRevenuePaidListener((adInfo) => {
    console.log('Revenue:', adInfo.revenue);
});

// Load
CloudXRewardedAd.loadAd(AD_UNIT_ID);

// Show when ready (with optional placement and custom data)
const isReady = await CloudXRewardedAd.isAdReady(AD_UNIT_ID);
if (isReady) {
    CloudXRewardedAd.showAd(AD_UNIT_ID);
    // or: CloudXRewardedAd.showAd(AD_UNIT_ID, 'placement_name', 'custom_data');
}

// Destroy when done
CloudXRewardedAd.destroyAd(AD_UNIT_ID);

​
Rewarded Events

Event ListenerCallback Type
addAdLoadedEventListenerCloudXAdInfo
addAdLoadFailedEventListenerCloudXAdLoadFailedInfo
addAdDisplayedEventListenerCloudXAdInfo
addAdFailedToDisplayEventListenerCloudXAdDisplayFailedInfo
addAdClickedEventListenerCloudXAdInfo
addAdHiddenEventListenerCloudXAdInfo
addAdReceivedRewardEventListenerCloudXAdRewardInfo
addAdRevenuePaidListenerCloudXAdInfo
The CloudXAdRewardInfo extends CloudXAdInfo with:
  • rewardLabel?: string — the label of the reward (e.g., “coins”)
  • rewardAmount: number — the reward quantity

​
React Hooks

The SDK provides React hooks for declarative ad management that handle event subscriptions and cleanup automatically.

​
useCloudXInterstitial

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

function GameScreen() {
    const { isLoaded, isLoading, error, load, show, destroy } =
        useCloudXInterstitial('level_complete');

    useEffect(() => {
        load();
    }, [load]);

    return (
        <Button
            title={isLoading ? 'Loading...' : 'Show Ad'}
            onPress={() => show()}
            disabled={!isLoaded}
        />
    );
}
Returns: { isLoaded, isLoading, error, load, show, destroy }
  • show() accepts optional placement and customData parameters
  • The hook automatically destroys the ad on unmount

​
useCloudXRewarded

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

function RewardScreen() {
    const { isLoaded, isLoading, error, rewardEarned, load, show } =
        useCloudXRewarded('rewarded_coins');

    useEffect(() => {
        load();
    }, [load]);

    useEffect(() => {
        if (rewardEarned) {
            grantCoinsToUser();
        }
    }, [rewardEarned]);

    return (
        <Button
            title="Watch Ad for Coins"
            onPress={() => show()}
            disabled={!isLoaded}
        />
    );
}
Returns: { isLoaded, isLoading, error, rewardEarned, load, show, destroy }
  • rewardEarned becomes true when the user completes the ad
  • Resets to false on the next load() call or when the ad is hidden

​
useCloudXBanner

import { useCloudXBanner, CloudXBannerAd, CloudXAdPosition } from 'cloudx-react-native';

function HomeScreen() {
    const { isLoaded, error } = useCloudXBanner('home_banner');

    useEffect(() => {
        CloudXBannerAd.createAd('home_banner', CloudXAdPosition.BOTTOM_CENTER);
        CloudXBannerAd.showAd('home_banner');
        return () => CloudXBannerAd.destroyAd('home_banner');
    }, []);

    return <Text>{isLoaded ? 'Banner showing' : 'Loading banner...'}</Text>;
}
Returns: { isLoaded, error }

​
Advanced Features

​
Error Handling

All error callbacks receive an object with code and message properties:
RangeCategoryCommon Codes
0GeneralinternalError
100-199NetworknetworkError, networkTimeout, networkNoConnection
200-299InitializationnotInitialized, sdkDisabled, invalidAppKey
300-399Ad LoadingnoFill, invalidAdUnit, adsDisabled
400-499DisplayadNotReady, adAlreadyShowing
600-699AdapteradapterNoFill, adapterTimeout
See CloudXErrorCode export for the full list of error codes.

​
Revenue Tracking

All ad formats provide revenue callbacks. The CloudXAdInfo object includes revenue (USD), networkName, and adFormat: 
CloudXInterstitialAd.addAdRevenuePaidListener((adInfo) => {
    trackRevenue(adInfo.revenue, adInfo.networkName, adInfo.adUnitId);
});

​
User Targeting

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

// Set hashed user ID
CloudX.setHashedUserID('hashed-user-id');

// Set custom key-value pairs
CloudX.setUserKeyValue('age_group', '25-34');
CloudX.setAppKeyValue('app_version', '1.0.0');

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

​
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).
KeyStandardDescription
IABGPP_HDR_GppStringGPPGlobal Privacy Platform string
IABGPP_GppSIDGPPSection IDs
IABTCF_TCStringTCF v2GDPR consent string
IABUSPrivacy_StringUS PrivacyCCPA privacy string
For full details on privacy behavior, manual consent APIs, and CMP integration, see the iOS Privacy Compliance and Android Privacy Compliance guides.

​
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.

​
Test Mode

Test mode is server-controlled via device whitelisting:
  1. Initialize the SDK with verbose logging enabled
  2. Find your device advertising ID in the console logs
  3. Add the device to your whitelist on the CloudX dashboard

​
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

​
Visual Debugging

Enable visual debugging overlays to see ad unit boundaries and network info: 
CloudX.setVisualDebuggingEnabled(true);

​
Support

For support, contact mobile@cloudx.io