概览

CloudX React Native SDK 设置和核心功能概览

CloudX React Native SDK 可让您通过横幅、MREC、插页式、激励视频和 App Open 广告在 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', '~> 6.21.1.0'            # FBAudienceNetwork 6.21.1
  pod 'CloudXVungleAdapter', '~> 7.7.4.0'           # VungleAds 7.7.4
  pod 'CloudXInMobiAdapter', '~> 11.3.0.0'          # InMobiSDK 11.3.0
  pod 'CloudXMintegralAdapter', '~> 8.1.5.0'        # MintegralAdSDK 8.1.5
  pod 'CloudXUnityAdsAdapter', '~> 4.19.0.0'        # UnityAds 4.19.0
  pod 'CloudXMagniteAdapterV2', '~> 1.0.0.1'        # MagniteSDK 1.0.0
  pod 'CloudXMobileFuseAdapter', '~> 1.11.0.0'      # MobileFuseSDK 1.11.0
  pod 'CloudXMolocoAdapter', '~> 4.8.0.0'           # MolocoSDKiOS 4.8.0
  pod 'CloudXVerveAdapter', '~> 3.9.0.0'            # HyBid 3.9.0
  pod 'CloudXDigitalTurbineAdapter', '~> 8.4.8.0'   # Fyber Marketplace SDK 8.4.8
  pod 'CloudXGoogleWaterfallAdapter', '~> 13.6.0.2' # Google Mobile Ads SDK 13.6.0
  pod 'CloudXPangleAdapter', '~> 8.2.0.7.0'         # Ads-Global（Pangle / 字节跳动）8.2.0.7
  pod 'CloudXTaurusXAdapter', '~> 1.18.1.0'          # TaurusX SDK 1.18.1
end

然后安装 Pod：

cd ios && pod install

App Transport Security

CloudX SDK 不需要禁用应用传输安全（App Transport Security）。如果某个聚合广告网络确实通过特定域名的纯 HTTP 提供素材，请在 Info.plist 中为该域名单独配置例外，而不要在整个应用范围启用任意加载（全局 NSAllowsArbitraryLoads 会削弱应用的传输安全，并可能引起 App Store 审核关注）：

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSExceptionDomains</key>
  <dict>
    <key>example-ad-network.com</key>
    <dict>
      <key>NSExceptionAllowsInsecureHTTPLoads</key>
      <true/>
      <key>NSIncludesSubdomains</key>
      <true/>
    </dict>
  </dict>
</dict>

Android 设置

在 android/app/build.gradle 中添加 CloudX SDK 和适配器依赖：

dependencies {
    // CloudX Android SDK
    implementation "io.cloudx:sdk:4.5.0"

    // 广告网络适配器（按需添加）
    implementation "io.cloudx:adapter-digitalturbine:8.4.7.0"     // Digital Turbine Marketplace SDK 8.4.7
    implementation "io.cloudx:adapter-googlewaterfall:25.2.0.2"   // Google Mobile Ads SDK 25.2.0
    implementation "io.cloudx:adapter-inmobi:11.4.0.1"            // InMobi SDK 11.4.0
    implementation "io.cloudx:adapter-magnite:1.0.0.1"            // Magnite Ads SDK 1.0.0
    implementation "io.cloudx:adapter-meta:6.22.0.0"              // Meta Audience Network 6.22.0
    implementation "io.cloudx:adapter-mintegral:17.1.71.1"        // Mintegral SDK 17.1.71
    implementation "io.cloudx:adapter-mobilefuse:1.11.0.1"        // MobileFuse SDK 1.11.0
    implementation "io.cloudx:adapter-moloco:4.11.0.0"            // Moloco SDK 4.11.0
    implementation "io.cloudx:adapter-pangle:8.2.0.4.0"           // Pangle SDK 8.2.0.4
    implementation "io.cloudx:adapter-taurusx:1.18.3.0"           // TaurusX SDK 1.18.3
    implementation "io.cloudx:adapter-unityads:4.19.0.1"          // Unity Ads SDK 4.19.0
    implementation "io.cloudx:adapter-verve:3.9.0.1"              // Verve HyBid SDK 3.9.0
    implementation "io.cloudx:adapter-vungle:7.7.7.0"             // Vungle SDK 7.7.7
}

如果集成 Mintegral 适配器，还需要在 android/build.gradle 中声明其 Maven 仓库：

allprojects {
    repositories {
        maven { url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea" }
    }
}

可选 MMP 广告收入连接器

如果您的应用已经使用 Adjust 或 AppsFlyer，可以添加原生连接器依赖，将 CloudX 获胜展示收入转发给 MMP，无需 React Native JavaScript 胶水代码：

target 'YourApp' do
  pod 'CloudXAdjustConnector', '~> 5.0.0.0'
  pod 'CloudXAppsFlyerConnector', '~> 6.15.0.0'
end

连接器不会初始化 MMP SDK。您的应用必须已经使用自己的凭据集成并初始化 Adjust 或 AppsFlyer。请在连接器和自己的 onAdRevenuePaid 转发代码之间二选一，不要同时使用。

初始化

在加载任何广告之前初始化 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();

属性	类型	描述
`adUnitId`	`string`	广告单元 ID
`adFormat`	`string`	广告格式：`BANNER`、`MREC`、`INTERSTITIAL`、`REWARDED` 或 `APP_OPEN`
`networkName`	`string`	胜出广告网络名称
`networkPlacement`	`string \| null`	广告网络侧的 placement ID
`placement`	`string \| null`	集成侧设置的自定义 placement
`revenue`	`number`	美元收入值
`adValues`	`Record<string, string>`	SDK 提供的广告元数据，可用于 Trusted Arbiter 等功能

属性	类型	描述
`code`	`CloudXErrorCode`	错误类别
`message`	`string \| null`	人类可读的错误描述

范围	类别	常见错误码
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`

高级功能

调试日志

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

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

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

日志级别： VERBOSE < DEBUG < INFO < WARN < ERROR < NONE

原生 SDK 日志会出现在 iOS 和 Android 平台日志中。JavaScript 侧调用和事件处理也可以通过应用常规的 React Native 日志记录。

展示级收入追踪

在任意广告格式上设置 addAdRevenuePaidListener 回调即可接收展示级收入事件。CloudXAdInfo 对象包含美元收入值和胜出广告网络名称。

CloudXInterstitialAd.addAdRevenuePaidListener((adInfo) => {
    trackRevenue(adInfo.revenue, adInfo.networkName, adInfo.adUnitId);
});

适用于所有 React Native 广告格式：横幅、MREC、插页式、激励视频和 App Open。

如果需要将其他聚合平台或报表平台的 paid event 转发到 CloudX，请调用 CloudX.reportRevenueData()。收入值是货币单位，不是 micros。

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

const accepted = await CloudX.reportRevenueData({
    platform: CloudXRevenuePlatform.ADMOB,
    revenue: adValue.valueMicros / 1_000_000.0,
    adFormat: 'INTERSTITIAL',
    currencyCode: adValue.currencyCode,
    precision: CloudXRevenuePrecision.ESTIMATED,
    networkName: 'admob',
    adUnitId: 'interstitial_ad_unit',
});

Google Ad Manager paid event 请使用 CloudXRevenuePlatform.GAM。对于没有 JavaScript 常量的聚合平台，可使用 CloudXRevenuePlatform.custom('TopOn')、CloudXRevenuePlatform.custom('InMobi') 或其他非空平台名称。

发布商上报收入数据

如果您的应用在 CloudX 广告流程之外接收来自 AdMob、Google Ad Manager 或其他提供方的展示级收入回调，请在 CloudX 初始化完成后将这些事件转发给 CloudX：

字段	必填	描述
`platform`	是	`CloudXRevenuePlatform.ADMOB`、`CloudXRevenuePlatform.GAM` 或 `CloudXRevenuePlatform.custom("MyProvider")`
`revenue`	是	单次展示收入，使用传入货币；不是 CPM/eCPM
`adFormat`	是	广告格式字符串，例如 `banner`、`mrec`、`interstitial` 或 `rewarded`
`currencyCode`	否	ISO 4217 货币代码（如已知）
`precision`	否	`CloudXRevenuePrecision.EXACT`、`ESTIMATED`、`PUBLISHER_DEFINED` 或 `UNDEFINED`
`networkName`	否	胜出广告网络名称（如已知）
`adUnitId`	否	聚合平台广告单元 ID
`thirdPartyAdPlacementId`	否	广告网络侧广告单元或 placement ID
`creativeId`	否	广告网络返回的创意 ID
`networkPlacement`	否	广告网络 placement 标识
`countryCode`	否	用户国家代码（如已知）
`userSegment`	否	用户分群（如已知）

当事件被 CloudX 收益链路接受时，CloudX.reportRevenueData() 会解析为 true。当 payload 无效、平台名称为空、SDK 尚未初始化或收入追踪不可用时，它会解析为 false。

AdMob paid event

Google 不提供官方的 React Native AdMob 插件。本示例使用 react-native-google-mobile-ads，这是基于官方 Google Mobile Ads Android 和 iOS SDK 的第三方 React Native 封装。

const toCloudXRevenuePrecision = (precision) => {
    switch (precision) {
        case RevenuePrecisions.PRECISE:
            return CloudXRevenuePrecision.EXACT;
        case RevenuePrecisions.ESTIMATED:
            return CloudXRevenuePrecision.ESTIMATED;
        case RevenuePrecisions.PUBLISHER_PROVIDED:
            return CloudXRevenuePrecision.PUBLISHER_DEFINED;
        case RevenuePrecisions.UNKNOWN:
        default:
            return CloudXRevenuePrecision.UNDEFINED;
    }
};

const reportAdMobPaidEvent = (event, adFormat, adUnitId) =>
    CloudX.reportRevenueData({
        platform: CloudXRevenuePlatform.ADMOB,
        revenue: event.value,
        adFormat,
        currencyCode: event.currency,
        precision: toCloudXRevenuePrecision(event.precision),
        adUnitId,
    });

const AdMobBanner = () => (
    <BannerAd
        unitId={ADMOB_BANNER_UNIT_ID}
        size={BannerAdSize.BANNER}
        onPaid={(event) => {
            reportAdMobPaidEvent(event, 'banner', ADMOB_BANNER_UNIT_ID);
        }}
    />
);

对于 Google Ad Manager paid event，请保持相同的收入和精度映射，并设置 platform: CloudXRevenuePlatform.GAM。

React Native 为 AdMob 和 Google Ad Manager 提供 JavaScript 常量。对于没有 CloudX JavaScript SDK 常量的 provider，请使用 custom，例如 InMobi、TopOn、TradPlus 和 Nimbus。这里的值只表示 provider 名称，例如 CloudXRevenuePlatform.custom("TradPlus") 或 CloudXRevenuePlatform.custom("Nimbus")。请保持名称稳定，便于 CloudX 一致归类该 provider 的收益。

不要把金额或币种放进 provider 名称里。如果一条 TradPlus 展示带来 USD 0.01 收入，请传 platform: CloudXRevenuePlatform.custom("TradPlus")、revenue: 0.01 和 currencyCode: "USD"。如果来源返回 CPM/eCPM，请先除以 1_000.0。

const reportCustomRevenueEvent = (
    providerName,
    revenue,
    adFormat,
    currencyCode,
    adUnitId,
    placementId,
) =>
    CloudX.reportRevenueData({
        platform: CloudXRevenuePlatform.custom(providerName),
        revenue,
        adFormat,
        currencyCode,
        precision: CloudXRevenuePrecision.PUBLISHER_DEFINED,
        adUnitId,
        thirdPartyAdPlacementId: placementId,
    });

测试模式

测试模式通过设备白名单由服务端控制，这样可以更安全、更可控地指定哪些设备接收测试广告。

启用测试模式：

启用详细日志后初始化 SDK。
在 iOS 或 Android 平台日志中查找您的设备广告 ID。
将广告 ID 添加到 CloudX 服务端控制台的设备白名单。

注意： 测试模式由服务端决定，因此无需在开发和生产构建之间修改代码。

隐私合规

CloudX SDK 通过读取平台存储（iOS 上的 NSUserDefaults、Android 上的 SharedPreferences）中的标准 IAB 隐私字符串来支持 GDPR 和 CCPA 隐私合规。这些值通常由您的同意管理平台 (CMP) 自动设置，如 Google UMP、OneTrust 或 Sourcepoint。

工作原理

原生 SDK 会自动检测用户位置并读取同意信号：

欧盟用户 (GDPR)：根据 IAB 全球供应商列表检查 TCF v2 目的 1 和 2 的同意和供应商同意（CloudX 供应商 ID：1510）
美国用户 (CCPA)：检查销售/共享退出信号
其他地区：不应用限制

当同意被拒绝或用户选择退出时，SDK 会从广告请求中删除个人身份信息：

广告 ID (IDFA/GAID) 被清除
地理坐标（经纬度）被删除
用户键值对不发送
哈希用户 ID 会从发送给竞价方的请求中移除，并且不会写入展示级报表

支持的隐私密钥

键	标准	描述
`IABGPP_HDR_GppString`	GPP	全球隐私平台字符串（现代）
`IABGPP_GppSID`	GPP	部分 ID（例如，“2” 代表欧盟，“7” 代表美国国家，“8” 代表美国加州）
`IABTCF_TCString`	TCF v2	GDPR 同意字符串（传统）
`IABTCF_gdprApplies`	TCF v2	GDPR 是否适用（1 = 是，0 = 否）
`IABUSPrivacy_String`	US Privacy	CCPA 隐私字符串（传统，例如 “1YNN”）

注意：当 GPP（现代标准）和传统 TCF/US Privacy 字符串同时存在时，SDK 优先使用 GPP。

手动隐私 API

如果您自行管理用户同意（不使用 CMP），可以直接设置 GDPR 和 CCPA 隐私状态。这些方法可以在 SDK 初始化之前或之后调用。

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

// GDPR 同意：true、false 或 null（回退到 CMP）
CloudX.setHasUserConsent(true);

// CCPA do-not-sell：true、false 或 null（回退到 CMP）
CloudX.setDoNotSell(true);

用户定向

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

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

// 设置自定义用户键值对
CloudX.setUserKeyValue('age', '25');
CloudX.setUserKeyValue('gender', 'male');
CloudX.setUserKeyValue('location', 'US');

// 设置自定义应用键值对
CloudX.setAppKeyValue('app_version', '1.0.0');
CloudX.setAppKeyValue('user_level', 'premium');

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

哈希用户 ID 是由发布商提供的假名标识符。当适用的隐私信号允许时，CloudX 会在请求和展示活动导出中以 hashed_user_id 返回竞价时记录的值。使用 auction_id 关联这些导出。您可以使用该 ID 将 CloudX 活动与自己的用户数据分群关联。未设置 ID、隐私信号阻止持久化或值超过 128 个字符时，导出值为空。请勿传递未经哈希的个人数据。

每次加载的额外参数

React Native SDK 3.4.4 及更高版本可以为单次广告加载附加广告网络或服务端配置。参数值支持 string、number、boolean、null、数组和嵌套对象。

对于程序化广告，请在启动加载的方法之前调用对应广告格式的 setExtraParameters 方法：

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

const extraParameters = {
    requestId: 'request-456',
    bidFloor: 0.5,
    testRequest: false,
    keywords: ['sports', 'scores'],
    context: {
        screen: 'home',
        refreshIndex: null,
    },
};

// 程序化横幅和 MREC 广告：在 createAd() 之前调用。
CloudXBannerAd.setExtraParameters(BANNER_AD_UNIT_ID, extraParameters);
CloudXBannerAd.createAd(BANNER_AD_UNIT_ID, CloudXAdPosition.BOTTOM_CENTER);

CloudXMRECAd.setExtraParameters(MREC_AD_UNIT_ID, extraParameters);
CloudXMRECAd.createAd(MREC_AD_UNIT_ID, CloudXAdPosition.CENTERED);

// 插屏和激励视频广告：在 loadAd() 之前调用。
CloudXInterstitialAd.setExtraParameters(INTERSTITIAL_AD_UNIT_ID, extraParameters);
CloudXInterstitialAd.loadAd(INTERSTITIAL_AD_UNIT_ID);

CloudXRewardedAd.setExtraParameters(REWARDED_AD_UNIT_ID, extraParameters);
CloudXRewardedAd.loadAd(REWARDED_AD_UNIT_ID);

对于插屏和激励视频广告，loadAd() 运行时会记录参数值；之后的修改会用于下一次加载。对于程序化横幅和 MREC 广告，请在 createAd() 之前设置参数，以便用于首次竞价。创建广告后的修改会用于后续刷新。

对于组件广告位，请通过 CloudXBannerView 或 CloudXMRECView 的 extraParameters prop 传入参数，不要调用程序化 setter：

import { CloudXBannerView, CloudXMRECView } from 'cloudx-react-native';

<CloudXBannerView
    adUnitId={BANNER_AD_UNIT_ID}
    extraParameters={{ section: 'top_stories', refreshIndex: 1 }}
/>

<CloudXMRECView
    adUnitId={MREC_AD_UNIT_ID}
    extraParameters={{ section: 'article_body', refreshIndex: 1 }}
/>

完整的组件 API 请参阅横幅和 MREC 广告。

身份透传

通过 setUserKeyValue 传入 UID 2.0、EUID、LiveRamp 和 ID5。有值时设置一次，刷新后再设一次。

键	传入内容
`uidapi.com`	UID2 广告 token，不要传 refresh token。不要解密。UID2 文档
`euid.eu`	EUID 广告 token，不要传 refresh token。不要解密。EUID 文档
`liveramp.com`	LiveRamp ATS 信封，不要传 RampID。LiveRamp 文档
`id5-sync.com`	ID5 通用 UID。不要传 `0`。ID5 文档

CloudX 不会生成这些 ID。请先用 UID2、EUID、LiveRamp ATS 或 ID5 生成，再把字符串传进来。这与哈希用户 ID 不是同一回事。

CloudX.setUserKeyValue('uidapi.com', uid2Token);
CloudX.setUserKeyValue('euid.eu', euidToken);
CloudX.setUserKeyValue('liveramp.com', liveRampEnvelope);
CloudX.setUserKeyValue('id5-sync.com', id5Id);

App Tracking Transparency (iOS)

在 iOS 14+ 上请求跟踪授权：

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

const status = await requestTrackingAuthorization();
if (status === CloudXATTStatus.AUTHORIZED) {
    console.log('跟踪已授权');
}

ATT 状态值：AUTHORIZED、DENIED、RESTRICTED、NOT_DETERMINED、NOT_REQUIRED。

在 Android 或 iOS < 14 上，requestTrackingAuthorization() 返回 NOT_REQUIRED。

可视化调试

启用可视化调试覆盖层以查看广告单元边界和网络信息：

CloudX.setVisualDebuggingEnabled(true);

支持

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

概览

手动安装

iOS 设置

App Transport Security

Android 设置

可选 MMP 广告收入连接器

初始化

广告格式

广告信息 (CloudXAdInfo)

错误处理

错误码类别

高级功能

调试日志

展示级收入追踪

发布商上报收入数据

AdMob paid event

自定义平台事件

测试模式

隐私合规

工作原理

支持的隐私密钥

手动隐私 API

用户定向

每次加载的额外参数

身份透传

App Tracking Transparency (iOS)

可视化调试

支持