跳转到主要内容

​
CloudX React Native SDK

npm CloudX React Native SDK 可让您通过横幅、MREC、插页式和激励视频广告在 iOS 和 Android 上实现 React Native 应用的变现。支持新架构 (Fabric) 和旧架构 (Paper)。

​
安装

要求 React Native 0.70+、React 18.0+、iOS 13.0+、Android API 23+。 
npm install cloudx-react-native

​
iOS 设置

在 ios/Podfile 中添加广告网络适配器 Pod： 
target 'YourApp' do
  # ... 现有配置 ...

  # CloudX 广告网络适配器（按需添加）
  pod 'CloudXMetaAdapter', '~> 2.2.0-beta'
  pod 'CloudXVungleAdapter', '~> 2.2.0-beta'
  pod 'CloudXInMobiAdapter', '~> 2.2.0-beta'
  pod 'CloudXRenderer', '~> 2.2.0-beta'
end
然后安装 Pod： 
cd ios && pod install
CloudXCore Pod 作为 cloudx-react-native npm 包的依赖项自动包含。您只需添加所需的适配器 Pod。

​
App Transport Security

如果您的广告使用 HTTP URL，请在 Info.plist 中添加以下内容： 
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

​
Android 设置

在 android/app/build.gradle 中添加 CloudX SDK 和适配器依赖： 
dependencies {
    // CloudX Android SDK
    implementation "io.cloudx:sdk:2.0.0"

    // 广告网络适配器（按需添加）
    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"
}
至少需要一个适配器才能投放广告。

​
初始化

在加载任何广告之前初始化 SDK： 
import { CloudX, CloudXLogLevel } from 'cloudx-react-native';

// 可选：启用详细日志（仅限开发环境）
CloudX.setMinLogLevel(CloudXLogLevel.VERBOSE);

// 使用您的应用密钥初始化
const result = await CloudX.initialize('YOUR_APP_KEY');
if (result.success) {
    console.log('CloudX 初始化完成');
} else {
    console.error('CloudX 初始化失败:', result.message);
}
CloudX.initialize() 返回 CloudXInitializationResult，包含：
  • success: boolean — 初始化是否成功
  • message?: string — 附加详情，失败时填充
其他初始化工具方法： 
const initialized = await CloudX.isInitialized();
const version = await CloudX.getVersion();
const tablet = await CloudX.isTablet();

​
广告集成

​
横幅广告 (320x50)

横幅使用程序化叠加方式 — 在固定屏幕位置覆盖在您的内容上方。 
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.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);

​
其他横幅 API

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

​
横幅事件

事件监听器回调类型
addAdLoadedEventListenerCloudXAdInfo
addAdLoadFailedEventListenerCloudXAdLoadFailedInfo
addAdClickedEventListenerCloudXAdInfo
addAdExpandedEventListenerCloudXAdInfo
addAdCollapsedEventListenerCloudXAdInfo
addAdRevenuePaidListenerCloudXAdInfo
每个监听器都有对应的 remove* 方法（例如 removeAdLoadedEventListener()）。

​
MREC 广告 (300x250)

MREC 与横幅工作方式相同，但尺寸为 300x250。使用 CloudXMRECAd 模块： 
import { CloudXMRECAd, CloudXAdPosition } from 'cloudx-react-native';

const AD_UNIT_ID = 'home_mrec';

CloudXMRECAd.addAdLoadedEventListener((adInfo) => {
    console.log('MREC 已加载，来自', adInfo.networkName);
});

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

// 完成后销毁
CloudXMRECAd.destroyAd(AD_UNIT_ID);
CloudXMRECAd API 与 CloudXBannerAd 完全相同 — 所有方法和事件均可用，包括 createAdWithOffsets、updatePosition、updateOffsets、setBackgroundColor、setPlacement、setCustomData、自动刷新控制和所有事件监听器。

​
插页式广告

在自然过渡点展示的全屏广告。 
import { CloudXInterstitialAd } from 'cloudx-react-native';

const AD_UNIT_ID = 'level_complete';

// 设置事件监听器
CloudXInterstitialAd.addAdLoadedEventListener((adInfo) => {
    console.log('插页式广告已加载');
});
CloudXInterstitialAd.addAdLoadFailedEventListener((error) => {
    console.log('插页式广告加载失败:', error.code, error.message);
});
CloudXInterstitialAd.addAdDisplayedEventListener((adInfo) => {
    console.log('插页式广告已展示');
});
CloudXInterstitialAd.addAdFailedToDisplayEventListener((error) => {
    console.log('插页式广告展示失败:', error.code, error.message);
});
CloudXInterstitialAd.addAdHiddenEventListener((adInfo) => {
    // 重新加载以备下次使用
    CloudXInterstitialAd.loadAd(AD_UNIT_ID);
});
CloudXInterstitialAd.addAdRevenuePaidListener((adInfo) => {
    console.log('收入:', adInfo.revenue);
});

// 加载
CloudXInterstitialAd.loadAd(AD_UNIT_ID);

// 准备就绪后展示（可选传入 placement 和 custom data）
const isReady = await CloudXInterstitialAd.isAdReady(AD_UNIT_ID);
if (isReady) {
    CloudXInterstitialAd.showAd(AD_UNIT_ID);
    // 或: CloudXInterstitialAd.showAd(AD_UNIT_ID, 'placement_name', 'custom_data');
}

// 完成后销毁
CloudXInterstitialAd.destroyAd(AD_UNIT_ID);

​
插页式广告事件

事件监听器回调类型
addAdLoadedEventListenerCloudXAdInfo
addAdLoadFailedEventListenerCloudXAdLoadFailedInfo
addAdDisplayedEventListenerCloudXAdInfo
addAdFailedToDisplayEventListenerCloudXAdDisplayFailedInfo
addAdClickedEventListenerCloudXAdInfo
addAdHiddenEventListenerCloudXAdInfo
addAdRevenuePaidListenerCloudXAdInfo

​
激励视频广告

完成观看后授予用户奖励的全屏广告。 
import { CloudXRewardedAd } from 'cloudx-react-native';

const AD_UNIT_ID = 'rewarded_coins';

// 设置事件监听器
CloudXRewardedAd.addAdLoadedEventListener((adInfo) => {
    console.log('激励视频已加载');
});
CloudXRewardedAd.addAdLoadFailedEventListener((error) => {
    console.log('激励视频加载失败:', error.code, error.message);
});
CloudXRewardedAd.addAdDisplayedEventListener((adInfo) => {
    console.log('激励视频已展示');
});
CloudXRewardedAd.addAdFailedToDisplayEventListener((error) => {
    console.log('激励视频展示失败:', error.code, error.message);
});
CloudXRewardedAd.addAdReceivedRewardEventListener((rewardInfo) => {
    console.log(`获得 ${rewardInfo.rewardAmount} ${rewardInfo.rewardLabel}`);
});
CloudXRewardedAd.addAdHiddenEventListener((adInfo) => {
    // 重新加载以备下次使用
    CloudXRewardedAd.loadAd(AD_UNIT_ID);
});
CloudXRewardedAd.addAdRevenuePaidListener((adInfo) => {
    console.log('收入:', adInfo.revenue);
});

// 加载
CloudXRewardedAd.loadAd(AD_UNIT_ID);

// 准备就绪后展示（可选传入 placement 和 custom data）
const isReady = await CloudXRewardedAd.isAdReady(AD_UNIT_ID);
if (isReady) {
    CloudXRewardedAd.showAd(AD_UNIT_ID);
    // 或: CloudXRewardedAd.showAd(AD_UNIT_ID, 'placement_name', 'custom_data');
}

// 完成后销毁
CloudXRewardedAd.destroyAd(AD_UNIT_ID);

​
激励视频广告事件

事件监听器回调类型
addAdLoadedEventListenerCloudXAdInfo
addAdLoadFailedEventListenerCloudXAdLoadFailedInfo
addAdDisplayedEventListenerCloudXAdInfo
addAdFailedToDisplayEventListenerCloudXAdDisplayFailedInfo
addAdClickedEventListenerCloudXAdInfo
addAdHiddenEventListenerCloudXAdInfo
addAdReceivedRewardEventListenerCloudXAdRewardInfo
addAdRevenuePaidListenerCloudXAdInfo
CloudXAdRewardInfo 继承自 CloudXAdInfo，额外包含：
  • rewardLabel?: string — 奖励标签（例如 “coins”）
  • rewardAmount: number — 奖励数量

​
React Hooks

SDK 提供 React Hooks 用于声明式广告管理，自动处理事件订阅和清理。

​
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 ? '加载中...' : '展示广告'}
            onPress={() => show()}
            disabled={!isLoaded}
        />
    );
}
返回：{ isLoaded, isLoading, error, load, show, destroy }
  • show() 接受可选的 placement 和 customData 参数
  • Hook 在组件卸载时自动销毁广告

​
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="观看广告获取金币"
            onPress={() => show()}
            disabled={!isLoaded}
        />
    );
}
返回：{ isLoaded, isLoading, error, rewardEarned, load, show, destroy }
  • rewardEarned 在用户完成广告观看后变为 true
  • 在下次 load() 调用或广告隐藏时重置为 false

​
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 ? '横幅展示中' : '加载横幅中...'}</Text>;
}
返回：{ isLoaded, error }

​
高级功能

​
错误处理

所有错误回调接收包含 code 和 message 属性的对象：
范围类别常见错误码
0通用internalError
100-199网络networkError、networkTimeout、networkNoConnection
200-299初始化notInitialized、sdkDisabled、invalidAppKey
300-399广告加载noFill、invalidAdUnit、adsDisabled
400-499展示adNotReady、adAlreadyShowing
600-699适配器adapterNoFill、adapterTimeout
完整错误码列表请参阅 CloudXErrorCode 导出。

​
收入追踪

所有广告格式提供收入回调。CloudXAdInfo 对象包含 revenue（美元）、networkName 和 adFormat： 
CloudXInterstitialAd.addAdRevenuePaidListener((adInfo) => {
    trackRevenue(adInfo.revenue, adInfo.networkName, adInfo.adUnitId);
});

​
用户定向

import { CloudX } from 'cloudx-react-native';

// 设置哈希用户 ID
CloudX.setHashedUserID('hashed-user-id');

// 设置自定义键值对
CloudX.setUserKeyValue('age_group', '25-34');
CloudX.setAppKeyValue('app_version', '1.0.0');

// 清除所有自定义键值对
CloudX.clearAllKeyValues();

​
隐私合规

CloudX SDK 通过读取平台存储（iOS 上的 NSUserDefaults、Android 上的 SharedPreferences）中的标准 IAB 隐私字符串来支持 GDPR 和 CCPA 隐私合规。这些值通常由您的同意管理平台 (CMP) 自动设置。
键标准描述
IABGPP_HDR_GppStringGPP全球隐私平台字符串
IABGPP_GppSIDGPPSection ID
IABTCF_TCStringTCF v2GDPR 同意字符串
IABUSPrivacy_StringUS PrivacyCCPA 隐私字符串

​
App Tracking Transparency (iOS)

在 iOS 14+ 上请求跟踪授权： 
import { requestTrackingAuthorization, getTrackingAuthorizationStatus, CloudXATTStatus } from 'cloudx-react-native';

const status = await requestTrackingAuthorization();
if (status === CloudXATTStatus.AUTHORIZED) {
    console.log('跟踪已授权');
}
在 CloudX.initialize() 之前调用 requestTrackingAuthorization() 以获得最佳广告定向效果。
ATT 状态值：AUTHORIZED、DENIED、RESTRICTED、NOT_DETERMINED、NOT_REQUIRED。 在 Android 或 iOS < 14 上，requestTrackingAuthorization() 返回 NOT_REQUIRED。

​
测试模式

测试模式通过设备白名单由服务端控制：
  1. 启用详细日志后初始化 SDK
  2. 在控制台日志中查找您的设备广告 ID
  3. 在 CloudX 控制台中将设备添加到白名单

​
调试日志

import { CloudX, CloudXLogLevel } from 'cloudx-react-native';

// 启用详细日志（在 initialize 之前调用）
CloudX.setMinLogLevel(CloudXLogLevel.VERBOSE);

// 可用级别: VERBOSE, DEBUG, INFO, WARN, ERROR, NONE

​
可视化调试

启用可视化调试覆盖层以查看广告单元边界和网络信息： 
CloudX.setVisualDebuggingEnabled(true);

​
支持

如需支持，请联系 mobile@cloudx.io