Native Ads

Integrate CloudX native ads in React Native apps

Native ads render inside your own content instead of in a fixed banner slot. CloudXNativeAdView either draws the ad for you from a bundled template, or hands you the individual creative assets to lay out yourself.

Native ads need CloudX React Native SDK 3.10.1 or newer. They work on both the New Architecture and the legacy architecture.

Template mode

Template mode is the default and the quickest path. Mount the component, pick a template, and the SDK renders the whole ad.

import React from 'react';
import { View } from 'react-native';
import { CloudXNativeAdView, CloudXNativeTemplate } from 'cloudx-react-native';

const AD_UNIT_ID = 'feed_native';

export function FeedScreen() {
    return (
        <View>
            <CloudXNativeAdView
                adUnitId={AD_UNIT_ID}
                template={CloudXNativeTemplate.MEDIUM}
                placement="home_feed"
                style={{ height: 260 }}
                onAdLoaded={(adInfo) => {
                    console.log('Native loaded from', adInfo.networkName);
                }}
                onAdLoadFailed={(error) => {
                    console.log('Native failed:', error.code, error.message);
                }}
                onAdRevenuePaid={(adInfo) => {
                    console.log('Native revenue:', adInfo.revenue);
                }}
            />
        </View>
    );
}

The view has no intrinsic size. Give it a style with a height, or it renders 0pt tall.

Templates

Template	Shape
`CloudXNativeTemplate.SMALL`	Compact row: icon, title, advertiser, call to action
`CloudXNativeTemplate.MEDIUM`	Default. Icon, title, body, call to action
`CloudXNativeTemplate.MEDIA_BANNER`	Media-forward, landscape creative
`CloudXNativeTemplate.VERTICAL_MEDIA`	Full-screen portrait, for feed-style vertical surfaces

template is read when the ad loads. Changing it on a mounted view has no effect until the next load.

Manual mode

Set renderMode="manual" to build the ad out of your own layout. Mount the asset components you want; the SDK fills them in and registers them for click and impression tracking.

import React from 'react';
import { View, StyleSheet } from 'react-native';
import {
    CloudXNativeAdView,
    CloudXTitleView,
    CloudXAdvertiserView,
    CloudXBodyView,
    CloudXCallToActionView,
    CloudXIconView,
    CloudXOptionsView,
    CloudXMediaView,
} from 'cloudx-react-native';

export function CustomNativeAd() {
    return (
        <CloudXNativeAdView
            adUnitId="feed_native"
            renderMode="manual"
            style={styles.card}
            onAdLoaded={(adInfo) => console.log('Loaded', adInfo.nativeAd?.title)}
        >
            <View style={styles.row}>
                <CloudXIconView style={styles.icon} />
                <View style={styles.text}>
                    <CloudXTitleView style={styles.title} />
                    <CloudXAdvertiserView style={styles.advertiser} />
                </View>
                <CloudXOptionsView style={styles.options} />
            </View>

            <CloudXMediaView style={styles.media} />
            <CloudXBodyView style={styles.body} />
            <CloudXCallToActionView style={styles.cta} />
        </CloudXNativeAdView>
    );
}

Available asset components: CloudXTitleView, CloudXAdvertiserView, CloudXBodyView, CloudXCallToActionView, CloudXIconView, CloudXOptionsView, CloudXMediaView, CloudXStarRatingView.

Mount only the assets your layout uses. The SDK waits for the ones you mount and ignores the rest.

Video

Native creatives can carry video. Three props control playback, and they apply to both render modes.

<CloudXNativeAdView
    adUnitId="reels_native"
    template={CloudXNativeTemplate.VERTICAL_MEDIA}
    disableVideoFullScreen
    startVideoUnmuted={false}
    hideVideoMediaControls
/>

Prop	Effect
`disableVideoFullScreen`	Stops the creative expanding to fullscreen on tap
`startVideoUnmuted`	Starts playback unmuted
`hideVideoMediaControls`	Hides the creative’s own playback controls

Callbacks

Callback	Fires when
`onAdLoaded`	An ad is ready. `adInfo.nativeAd` carries the creative’s metadata
`onAdLoadFailed`	No ad was returned
`onAdDisplayFailed`	An ad loaded but could not be shown
`onAdClicked`	The user tapped the ad
`onAdRevenuePaid`	An impression was recorded and billed
`onAdExpired`	The held ad aged out before it was shown
`onAdClosed`	The user dismissed the ad

Reloading

The component loads on mount and tears down on unmount, so most integrations never need the ref.

import { useRef } from 'react';
import { CloudXNativeAdView } from 'cloudx-react-native';
import type { CloudXNativeAdViewHandle } from 'cloudx-react-native';

function FeedAd() {
    const ref = useRef<CloudXNativeAdViewHandle>(null);

    // Re-serves the ad already held for this unit.
    const reload = () => ref.current?.loadAd();

    // Discards it. The next loadAd() runs a fresh auction.
    const discard = () => ref.current?.destroyAd();

    return <CloudXNativeAdView ref={ref} adUnitId="feed_native" />;
}

Feeds

Loads are limited per ad unit, and the component does not retry a failed load. In a feed, load slots one at a time rather than mounting every slot at once, or most of them will come back empty.