横幅和 MREC 广告

在 React Native 应用中集成 CloudX 横幅和 MREC 广告

组件横幅

当广告需要参与 React Native 布局时，使用 CloudXBannerView。该组件会像普通视图一样渲染，因此父级布局、间距、安全区域、覆盖层和层级顺序都按应用 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('横幅已加载，来自', adInfo.networkName);
                }}
                onAdLoadFailed={(error) => {
                    console.log('横幅加载失败:', error.code, error.message);
                }}
                onAdClicked={(adInfo) => {
                    console.log('横幅已点击:', adInfo.adUnitId);
                }}
                onAdRevenuePaid={(adInfo) => {
                    console.log('横幅收入:', adInfo.revenue);
                }}
            />
        </View>
    );
}

CloudXBannerView 在手机上默认为 320x50，在平板上默认为 728x90。你可以传入普通 React Native ViewProps，包括 style、testID 和无障碍属性。

组件会自行管理原生广告生命周期。组件广告位不要再调用 CloudXBannerAd.createAd()、showAd() 或 destroyAd()。如果需要更换 adUnitId，请通过不同的 React key 重新挂载组件。

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

组件 MREC

使用 CloudXMRECView 集成布局内的 300x250 MREC 广告位。它支持与 CloudXBannerView 相同的组件 props 和回调。

组件会自行管理原生广告生命周期。组件广告位不要再调用 CloudXMRECAd.createAd()、showAd() 或 destroyAd()。

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 已加载，来自', adInfo.networkName);
                }}
                onAdLoadFailed={(error) => {
                    console.log('MREC 加载失败:', error.code, error.message);
                }}
                onAdClicked={(adInfo) => {
                    console.log('MREC 已点击:', adInfo.adUnitId);
                }}
                onAdRevenuePaid={(adInfo) => {
                    console.log('MREC 收入:', adInfo.revenue);
                }}
            />
        </View>
    );
}

组件 Props

Prop	类型	说明
`adUnitId`	`string`	必填的 CloudX 广告单元 ID。
`placement`	`string` 或 `null`	可选的 placement 名称，用于报表统计。
`customData`	`string` 或 `null`	可选的 custom data 字符串。
`extraParameters`	`CloudXExtraParameters` 或 `null`	可选的额外参数，用于广告网络或服务端配置。
`onAdLoaded`	`(adInfo) => void`	广告加载成功时调用。
`onAdLoadFailed`	`(error) => void`	广告加载失败时调用。
`onAdClicked`	`(adInfo) => void`	广告被点击时调用。
`onAdRevenuePaid`	`(adInfo) => void`	展示级收入可用时调用。

CloudXExtraParameters 支持 string、number、boolean、null、数组和嵌套对象。

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

程序化叠加横幅

需要现有原生叠加行为时，使用 CloudXBannerAd。程序化横幅会在固定屏幕位置覆盖在应用内容上方。

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

const AD_UNIT_ID = 'home_banner';

CloudXBannerAd.addAdLoadedEventListener((adInfo) => {
    console.log('横幅已加载，来自', adInfo.networkName);
});
CloudXBannerAd.addAdLoadFailedEventListener((error) => {
    console.log('横幅加载失败:', error.code, error.message);
});
CloudXBannerAd.addAdClickedEventListener((adInfo) => {
    console.log('横幅已点击');
});
CloudXBannerAd.addAdExpandedEventListener((adInfo) => {
    console.log('横幅已展开');
});
CloudXBannerAd.addAdCollapsedEventListener((adInfo) => {
    console.log('横幅已收起');
});
CloudXBannerAd.addAdRevenuePaidListener((adInfo) => {
    console.log('横幅收入:', 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);

默认启用自动刷新。如需手动控制：

CloudXBannerAd.stopAutoRefresh(AD_UNIT_ID);
CloudXBannerAd.startAutoRefresh(AD_UNIT_ID);

使用 CloudXAdPosition 放置叠加横幅：

TOP_LEFT、TOP_CENTER、TOP_RIGHT、CENTER_LEFT、CENTERED、CENTER_RIGHT、BOTTOM_LEFT、BOTTOM_CENTER、BOTTOM_RIGHT

如需像素级控制，使用偏移量：

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

用于统计的可选 placement 和 custom data：

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

程序化叠加 MREC

MREC 叠加广告使用 CloudXMRECAd，尺寸为 300x250。

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

const AD_UNIT_ID = 'home_mrec';

CloudXMRECAd.addAdLoadedEventListener((adInfo) => {
    console.log('MREC 已加载，来自', adInfo.networkName);
});
CloudXMRECAd.addAdLoadFailedEventListener((error) => {
    console.log('MREC 加载失败:', error.code, error.message);
});
CloudXMRECAd.addAdClickedEventListener((adInfo) => {
    console.log('MREC 已点击');
});
CloudXMRECAd.addAdExpandedEventListener((adInfo) => {
    console.log('MREC 已展开');
});
CloudXMRECAd.addAdCollapsedEventListener((adInfo) => {
    console.log('MREC 已收起');
});
CloudXMRECAd.addAdRevenuePaidListener((adInfo) => {
    console.log('MREC 收入:', adInfo.revenue);
});

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

CloudXMRECAd.destroyAd(AD_UNIT_ID);

CloudXMRECAd 与 CloudXBannerAd 的 API 相同，包括位置、偏移、背景色、placement、custom data、自动刷新控制和事件监听器。

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 ? '横幅展示中' : error?.message ?? '加载横幅中...'}</Text>;
}

返回：{ isLoaded, error }