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.1.0-beta'
  pod 'CloudXVungleAdapter', '~> 2.1.0-beta'
  pod 'CloudXInMobiAdapter', '~> 2.1.0-beta'
  pod 'CloudXRenderer', '~> 2.1.0-beta'
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.0.0"

    // Adapters for ad networks (add as needed)
    implementation "io.cloudx:adapter-cloudx:2.0.0"
    implementation "io.cloudx:adapter-meta:2.0.0"
    implementation "io.cloudx:adapter-vungle:2.0.0"
    implementation "io.cloudx:adapter-inmobi:2.0.0"
}
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 config = await CloudX.initialize('YOUR_APP_KEY');
console.log('CloudX initialized:', config);

​
Ad Integration

Banners use the programmatic overlay approach — they overlay your content at a fixed screen position. 
import { CloudXBannerAd, CloudXAdViewPosition } 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.message);
});
CloudXBannerAd.addAdRevenuePaidListener((adInfo) => {
    console.log('Banner revenue:', adInfo.revenue);
});

// Create and show
CloudXBannerAd.createAd(AD_UNIT_ID, CloudXAdViewPosition.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);

​
MREC Ads (300x250)

MRECs work identically to banners but with a larger size. Use the CloudXMRecAd module: 
import { CloudXMRecAd, CloudXAdViewPosition } 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, CloudXAdViewPosition.CENTERED);
CloudXMRecAd.showAd(AD_UNIT_ID);

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

​
Inline Ads (CloudXAdView Component)

For ads that embed in the React Native layout and scroll with content, use the CloudXAdView component: 
import { CloudXAdView, CloudXAdFormat } from 'cloudx-react-native';

<CloudXAdView
    adUnitId="feed_banner"
    adFormat={CloudXAdFormat.BANNER}
    onAdLoaded={(adInfo) => console.log('Loaded from', adInfo.networkName)}
    onAdLoadFailed={(error) => console.log('Failed:', error.message)}
    onAdRevenuePaid={(adInfo) => console.log('Revenue:', adInfo.revenue)}
/>
Key differences from programmatic overlay ads:
  • Embeds inline in the component tree (scrolls with content)
  • Each component has its own per-instance callbacks
  • Auto-loads on mount by default
  • Automatically destroyed when unmounted
For MREC format: 
<CloudXAdView
    adUnitId="feed_mrec"
    adFormat={CloudXAdFormat.MREC}
    onAdLoaded={(adInfo) => console.log('MREC loaded')}
/>
Control auto-refresh via props: 
<CloudXAdView
    adUnitId="feed_banner"
    adFormat={CloudXAdFormat.BANNER}
    autoRefresh={false}
/>

​
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 failed:', 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
const isReady = await CloudXInterstitialAd.isAdReady(AD_UNIT_ID);
if (isReady) {
    CloudXInterstitialAd.showAd(AD_UNIT_ID);
}

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

​
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 failed:', error.message);
});
CloudXRewardedAd.addAdReceivedRewardEventListener((rewardInfo) => {
    console.log('User earned reward!');
    // Grant the reward to the user
});
CloudXRewardedAd.addAdHiddenEventListener((adInfo) => {
    // Reload for next use
    CloudXRewardedAd.loadAd(AD_UNIT_ID);
});

// Load
CloudXRewardedAd.loadAd(AD_UNIT_ID);

// Show when ready
const isReady = await CloudXRewardedAd.isAdReady(AD_UNIT_ID);
if (isReady) {
    CloudXRewardedAd.showAd(AD_UNIT_ID);
}

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

​
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}
        />
    );
}

​
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}
        />
    );
}

​
useCloudXBanner

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

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

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

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

​
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) and networkName: 
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

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

​
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