Banner & MREC Ads

Integrate CloudX banner and MREC ads in React Native apps

Use CloudXBannerView when the ad should participate in your React Native layout. The component renders as a normal view, so parent layout, spacing, safe areas, overlays, and z-ordering work the same way as the rest of your app UI.

import React from 'react';
import { View } from 'react-native';
import { CloudXBannerView } from 'cloudx-react-native';

const AD_UNIT_ID = 'home_banner';

export function HomeScreen() {
    return (
        <View>
            <CloudXBannerView
                adUnitId={AD_UNIT_ID}
                placement="home_screen"
                customData="subscriber"
                extraParameters={{
                    section: 'top_stories',
                    refreshIndex: 1,
                    loggedIn: true,
                    experiments: ['component_banner'],
                    user: {
                        cohort: 'sports',
                    },
                }}
                onAdLoaded={(adInfo) => {
                    console.log('Banner loaded from', adInfo.networkName);
                }}
                onAdLoadFailed={(error) => {
                    console.log('Banner failed:', error.code, error.message);
                }}
                onAdClicked={(adInfo) => {
                    console.log('Banner clicked:', adInfo.adUnitId);
                }}
                onAdRevenuePaid={(adInfo) => {
                    console.log('Banner revenue:', adInfo.revenue);
                }}
            />
        </View>
    );
}

CloudXBannerView defaults to 320x50 on phones and 728x90 on tablets. You can pass normal React Native ViewProps, including style, testID, and accessibility props.

The component owns the native ad lifecycle. Do not call CloudXBannerAd.createAd(), showAd(), or destroyAd() for a component placement. If you need to change adUnitId, remount the component with a different React key.

<CloudXBannerView
    adUnitId="home_banner"
    style={{ alignSelf: 'center', marginVertical: 12 }}
/>

Component MREC

Use CloudXMRECView for an in-tree 300x250 MREC placement. It supports the same component props and callbacks as CloudXBannerView.

The component owns the native ad lifecycle. Do not call CloudXMRECAd.createAd(), showAd(), or destroyAd() for a component placement.

import React from 'react';
import { View } from 'react-native';
import { CloudXMRECView } from 'cloudx-react-native';

export function ArticleScreen() {
    return (
        <View>
            <CloudXMRECView
                adUnitId="article_mrec"
                placement="article_body"
                customData="sports_article"
                onAdLoaded={(adInfo) => {
                    console.log('MREC loaded from', adInfo.networkName);
                }}
                onAdLoadFailed={(error) => {
                    console.log('MREC failed:', error.code, error.message);
                }}
                onAdClicked={(adInfo) => {
                    console.log('MREC clicked:', adInfo.adUnitId);
                }}
                onAdRevenuePaid={(adInfo) => {
                    console.log('MREC revenue:', adInfo.revenue);
                }}
            />
        </View>
    );
}

Component Props

Prop	Type	Description
`adUnitId`	`string`	Required CloudX ad unit ID.
`placement`	`string` or `null`	Optional placement name for reporting.
`customData`	`string` or `null`	Optional custom data string.
`extraParameters`	`CloudXExtraParameters` or `null`	Optional extra parameters for network or server-side configuration.
`onAdLoaded`	`(adInfo) => void`	Called when an ad loads.
`onAdLoadFailed`	`(error) => void`	Called when an ad load fails.
`onAdClicked`	`(adInfo) => void`	Called when the ad is clicked.
`onAdRevenuePaid`	`(adInfo) => void`	Called when impression-level revenue is available.

CloudXExtraParameters accepts string, number, boolean, null, arrays, and nested objects.

<CloudXBannerView
    adUnitId="home_banner"
    extraParameters={{
        screen: 'home',
        position: 1,
        autoplay: false,
        keywords: ['sports', 'scores'],
        auction: {
            floor: 0.5,
        },
    }}
/>

Use CloudXBannerAd when you need the existing native overlay behavior. Programmatic banners overlay your content at a fixed screen position.

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

const AD_UNIT_ID = 'home_banner';

CloudXBannerAd.addAdLoadedEventListener((adInfo) => {
    console.log('Banner loaded from', adInfo.networkName);
});
CloudXBannerAd.addAdLoadFailedEventListener((error) => {
    console.log('Banner failed:', error.code, error.message);
});
CloudXBannerAd.addAdClickedEventListener((adInfo) => {
    console.log('Banner clicked');
});
CloudXBannerAd.addAdExpandedEventListener((adInfo) => {
    console.log('Banner expanded');
});
CloudXBannerAd.addAdCollapsedEventListener((adInfo) => {
    console.log('Banner collapsed');
});
CloudXBannerAd.addAdRevenuePaidListener((adInfo) => {
    console.log('Banner revenue:', adInfo.revenue);
});

CloudXBannerAd.createAd(AD_UNIT_ID, CloudXAdPosition.BOTTOM_CENTER);
CloudXBannerAd.showAd(AD_UNIT_ID);

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

Optional placement and custom data for tracking:

CloudXBannerAd.setBackgroundColor(AD_UNIT_ID, '#000000');
CloudXBannerAd.setPlacement(AD_UNIT_ID, 'home_screen');
CloudXBannerAd.setCustomData(AD_UNIT_ID, 'custom_data');

Programmatic Overlay MREC

MREC overlays use CloudXMRECAd and 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.addAdLoadFailedEventListener((error) => {
    console.log('MREC failed:', error.code, error.message);
});
CloudXMRECAd.addAdClickedEventListener((adInfo) => {
    console.log('MREC clicked');
});
CloudXMRECAd.addAdExpandedEventListener((adInfo) => {
    console.log('MREC expanded');
});
CloudXMRECAd.addAdCollapsedEventListener((adInfo) => {
    console.log('MREC collapsed');
});
CloudXMRECAd.addAdRevenuePaidListener((adInfo) => {
    console.log('MREC revenue:', adInfo.revenue);
});

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

CloudXMRECAd.destroyAd(AD_UNIT_ID);

CloudXMRECAd has the same API surface as CloudXBannerAd, including positioning, offsets, background color, placement, custom data, auto-refresh control, and event listeners.

React Hook

import React, { useEffect } from 'react';
import { Text } from 'react-native';
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' : error?.message ?? 'Loading banner...'}</Text>;
}

Returns: { isLoaded, error }

Banner & MREC Ads

Component Banner

Component MREC

Component Props

Programmatic Overlay Banner

Programmatic Overlay MREC

React Hook