cloudx-react-native

v2.2.3

Published

23 days ago

React Native wrapper for CloudX SDK (iOS & Android)

0High
0Medium
0Low

cloudx_eng

react-native cloudx ads monetization banner interstitial rewarded

CloudX React Native SDK

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

Features

Cross-Platform: Full iOS and Android support
Dual Architecture: Works on both Fabric (New Architecture) and Paper (Legacy)
All Ad Formats: Banner, MREC, Interstitial, and Rewarded ads
Programmatic Ad APIs: Overlay APIs for banner and MREC, plus fullscreen formats
React Hooks: Declarative hooks for fullscreen and banner ad lifecycles
Privacy Compliance: IAB privacy handled automatically via CMP shared storage
App Tracking Transparency: Built-in ATT support for iOS 14+
Type Safety: Full TypeScript definitions with CloudX-prefixed namespace

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

Note: 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"
}

Note: 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);
}

Initialization API

| Method | Returns | Description | |--------|---------|-------------| | CloudX.initialize(appKey) | Promise<CloudXInitializationResult> | Initialize the SDK with your app key | | CloudX.isInitialized() | Promise<boolean> | Check if the SDK has been initialized | | CloudX.getVersion() | Promise<string> | Get the native SDK version string | | CloudX.isTablet() | Promise<boolean> | Check if the device is a tablet |

The CloudXInitializationResult contains:

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

Ad Integration

Banner Ads (Programmatic Overlay)

Banners 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);

Full Banner API

| Method | Description | |--------|-------------| | createAd(adUnitId, position) | Create a banner at the given CloudXAdPosition | | createAdWithOffsets(adUnitId, position, xOffset, yOffset) | Create with pixel offsets from the position anchor | | showAd(adUnitId) | Show the banner | | hideAd(adUnitId) | Hide the banner (preserves the ad) | | destroyAd(adUnitId) | Destroy the banner and release resources | | updatePosition(adUnitId, position) | Move to a new CloudXAdPosition | | updateOffsets(adUnitId, xOffset, yOffset) | Update pixel offsets | | setBackgroundColor(adUnitId, hexColor) | Set banner background color (e.g., "#000000") | | setPlacement(adUnitId, placement) | Set placement name for reporting | | setCustomData(adUnitId, customData) | Set custom data string | | startAutoRefresh(adUnitId) | Resume auto-refresh | | stopAutoRefresh(adUnitId) | Pause auto-refresh |

Banner Events

| Method | Callback Parameter | |--------|--------------------| | addAdLoadedEventListener(fn) | CloudXAdInfo | | addAdLoadFailedEventListener(fn) | CloudXAdLoadFailedInfo | | addAdClickedEventListener(fn) | CloudXAdInfo | | addAdExpandedEventListener(fn) | CloudXAdInfo | | addAdCollapsedEventListener(fn) | CloudXAdInfo | | addAdRevenuePaidListener(fn) | CloudXAdInfo |

Each add* listener has a corresponding remove* method (e.g., removeAdLoadedEventListener()).

MREC Ads (Programmatic Overlay)

MRECs work identically to banners but with a 300x250 size:

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 MREC API surface is identical to Banner — all the same methods and events are available on CloudXMRECAd, 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 with placement/custom data:
    // CloudXInterstitialAd.showAd(AD_UNIT_ID, 'level_end', 'custom_data');
}

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

Interstitial API

| Method | Description | |--------|-------------| | loadAd(adUnitId) | Start loading an interstitial | | isAdReady(adUnitId) | Returns Promise<boolean> — whether an ad is ready to show | | showAd(adUnitId, placement?, customData?) | Show the loaded interstitial | | destroyAd(adUnitId) | Destroy the interstitial and release resources |

Interstitial Events

| Method | Callback Parameter | |--------|--------------------| | addAdLoadedEventListener(fn) | CloudXAdInfo | | addAdLoadFailedEventListener(fn) | CloudXAdLoadFailedInfo | | addAdDisplayedEventListener(fn) | CloudXAdInfo | | addAdFailedToDisplayEventListener(fn) | CloudXAdDisplayFailedInfo | | addAdClickedEventListener(fn) | CloudXAdInfo | | addAdHiddenEventListener(fn) | CloudXAdInfo | | addAdRevenuePaidListener(fn) | CloudXAdInfo |

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

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

Rewarded API

| Method | Description | |--------|-------------| | loadAd(adUnitId) | Start loading a rewarded ad | | isAdReady(adUnitId) | Returns Promise<boolean> — whether an ad is ready to show | | showAd(adUnitId, placement?, customData?) | Show the loaded rewarded ad | | destroyAd(adUnitId) | Destroy the rewarded ad and release resources |

Rewarded Events

| Method | Callback Parameter | |--------|--------------------| | addAdLoadedEventListener(fn) | CloudXAdInfo | | addAdLoadFailedEventListener(fn) | CloudXAdLoadFailedInfo | | addAdDisplayedEventListener(fn) | CloudXAdInfo | | addAdFailedToDisplayEventListener(fn) | CloudXAdDisplayFailedInfo | | addAdClickedEventListener(fn) | CloudXAdInfo | | addAdHiddenEventListener(fn) | CloudXAdInfo | | addAdReceivedRewardEventListener(fn) | CloudXAdRewardInfo | | addAdRevenuePaidListener(fn) | CloudXAdInfo |

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 CloudXInterstitialHookResult:

isLoaded: boolean — ad is ready to show
isLoading: boolean — load in progress
error: string | null — last error message
load() — start loading
show(placement?, customData?) — show the loaded ad
destroy() — destroy and reset state

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 CloudXRewardedHookResult:

isLoaded: boolean — ad is ready to show
isLoading: boolean — load in progress
error: string | null — last error message
rewardEarned: boolean — user completed the ad and earned a reward
load() — start loading
show(placement?, customData?) — show the loaded ad
destroy() — destroy and reset state

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 CloudXBannerHookResult:

isLoaded: boolean — banner has loaded an ad
error: string | null — last error message

Types Reference

CloudXAdInfo

Received by most ad event callbacks:

type CloudXAdInfo = {
    adUnitId: string;
    adFormat: string;       // "BANNER", "MREC", "INTERSTITIAL", "REWARDED"
    networkName: string;
    networkPlacement?: string | null;
    placement?: string | null;
    revenue: number;        // USD
};

CloudXAdLoadFailedInfo

Received by addAdLoadFailedEventListener:

type CloudXAdLoadFailedInfo = {
    adUnitId: string;
    code: CloudXErrorCode;
    message?: string | null;
};

CloudXAdDisplayFailedInfo

Received by addAdFailedToDisplayEventListener:

type CloudXAdDisplayFailedInfo = CloudXAdInfo & {
    code: CloudXErrorCode;
    message?: string | null;
};

CloudXAdRewardInfo

Received by addAdReceivedRewardEventListener:

type CloudXAdRewardInfo = CloudXAdInfo & {
    rewardLabel?: string | null;
    rewardAmount: number;
};

CloudXAdPosition

Position constants for programmatic banner and MREC placement:

enum CloudXAdPosition {
    TOP_LEFT, TOP_CENTER, TOP_RIGHT,
    CENTER_LEFT, CENTERED, CENTER_RIGHT,
    BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT,
}

Advanced Features

Error Handling

All error callbacks receive an object with code and message properties:

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

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

App Tracking Transparency (iOS)

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

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

Note: 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:

Initialize the SDK with verbose logging enabled
Find your device advertising ID in the console logs
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);

Platform Support

| Platform | Status | Minimum Version | |----------|--------|-----------------| | iOS | Supported | iOS 13.0+ | | Android | Supported | API 23+ |

Requirements

React Native 0.70+
React 18.0+
TypeScript 4.5+ (recommended)
Xcode 14.0+ / CocoaPods (iOS)
Gradle 8.0+ / Kotlin 1.8+ (Android)

Native SDK Versions (2.2.3)

| Platform | Dependency | Version | |----------|-----------|---------| | iOS | CloudXCore | ~> 2.2.3 | | Android | io.cloudx:sdk | 2.2.3 |

Troubleshooting

React Native 0.84.0 — TurboModuleRegistry crash

React Native 0.84.0 has a known issue where TurboModuleRegistry.getEnforcing(...) fails with:

TurboModuleRegistry.getEnforcing(...): 'PlatformConstants' could not be found. Verify that a module by this name is registered in the native binary.

This is a React Native framework bug, not a CloudX SDK issue. It manifests as a red screen crash on app launch:

RN 0.84.0 TurboModule crash

Workaround: Use React Native 0.83.x or wait for the fix in a later 0.84.x patch release. The CloudX SDK is fully compatible with RN 0.70 through 0.83.

Documentation

Integration Guide: Complete integration documentation
Changelog: Release history

Support

For support, contact [email protected]

Email: [email protected]
Issues: GitHub Issues

License

This project is licensed under the Elastic License 2.0 — see the LICENSE file for details.