Documentation Index
Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt
Use this file to discover all available pages before exploring further.
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', '~> 3.4.0' # Meta Audience Network >= 6.15.1, < 7.0
pod 'CloudXVungleAdapter', '~> 3.4.0' # VungleAds >= 7.4.0, < 8.0
pod 'CloudXInMobiAdapter', '~> 3.4.0' # InMobiSDK >= 11.0.0, < 12.0
pod 'CloudXMintegralAdapter', '~> 3.4.0' # MintegralAdSDK ~> 8.0
pod 'CloudXUnityAdsAdapter', '~> 3.4.0' # UnityAds >= 4.17.0, < 5.0
pod 'CloudXMagniteAdapter', '~> 3.4.0' # MagniteSDK ~> 1.0.0
pod 'CloudXMolocoAdapter', '~> 3.4.0' # MolocoSDKiOS ~> 4.6.0
pod 'CloudXVerveAdapter', '~> 3.4.0' # HyBid = 3.8.0
pod 'CloudXRenderer', '~> 3.4.0' # CloudX 测试广告
end
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:4.1.0"
// 广告网络适配器（按需添加）
implementation "io.cloudx:adapter-googlewaterfall:23.6.0.0" // Google Mobile Ads SDK 23.6.0
implementation "io.cloudx:adapter-inmobi:11.2.0.0" // InMobi SDK 11.2.0
implementation "io.cloudx:adapter-magnite:1.0.0.0" // Magnite Ads SDK 1.0.0
implementation "io.cloudx:adapter-meta:6.21.0.1" // Meta Audience Network 6.21.0
implementation "io.cloudx:adapter-mintegral:17.1.51.0" // Mintegral SDK 17.1.51
implementation "io.cloudx:adapter-moloco:4.8.0.0" // Moloco SDK 4.8.0
implementation "io.cloudx:adapter-unityads:4.17.0.0" // Unity Ads SDK 4.17.0
implementation "io.cloudx:adapter-verve:3.8.1.0" // Verve HyBid SDK 3.8.1
implementation "io.cloudx:adapter-vungle:7.7.3.0" // Vungle SDK 7.7.3
}
android/build.gradle 中声明其 Maven 仓库：
allprojects {
repositories {
maven { url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea" }
}
}
初始化
在加载任何广告之前初始化 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();
广告格式
CloudX React Native 支持横幅、MREC、插页式和激励视频广告集成。具体实现请参阅对应的广告格式指南：
横幅和 MREC 广告
创建程序化叠加展示广告位，并可控制刷新。
广告信息 (CloudXAdInfo)
大多数广告事件回调都会收到 CloudXAdInfo 对象：
| 属性 | 类型 | 描述 |
|---|
adUnitId | string | 广告单元 ID |
adFormat | string | 广告格式：BANNER、MREC、INTERSTITIAL 或 REWARDED |
networkName | string | 胜出广告网络名称 |
networkPlacement | string | null | 广告网络侧的 placement ID |
placement | string | null | 集成侧设置的自定义 placement |
revenue | number | 美元收入值 |
adValues | Record<string, string> | SDK 提供的广告元数据，可用于 Trusted Arbiter 等功能 |
错误处理
所有 SDK 错误都会在回调或 rejected promise 中以错误对象返回：
| 属性 | 类型 | 描述 |
|---|
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 |
CloudXErrorCode 导出。
高级功能
调试日志
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);
});
测试模式
测试模式通过设备白名单由服务端控制，这样可以更安全、更可控地指定哪些设备接收测试广告。
启用测试模式：
- 启用详细日志后初始化 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);
当手动设置值和 CMP 信号同时存在时，CMP 信号（GPP/TCF/US Privacy）优先。手动设置值在未集成 CMP 时作为回退使用。
用户定向
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();
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() 以获得最佳广告定向效果。
AUTHORIZED、DENIED、RESTRICTED、NOT_DETERMINED、NOT_REQUIRED。
在 Android 或 iOS < 14 上，requestTrackingAuthorization() 返回 NOT_REQUIRED。
可视化调试
启用可视化调试覆盖层以查看广告单元边界和网络信息：
CloudX.setVisualDebuggingEnabled(true);
