集成 - CloudX Documentation

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

然后安装 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: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
}

至少需要一个适配器才能投放广告。

如果集成 Mintegral 适配器，还需要在 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);
});

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

测试模式

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

启用详细日志后初始化 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() 以获得最佳广告定向效果。

ATT 状态值：AUTHORIZED、DENIED、RESTRICTED、NOT_DETERMINED、NOT_REQUIRED。在 Android 或 iOS < 14 上，requestTrackingAuthorization() 返回 NOT_REQUIRED。

可视化调试

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

CloudX.setVisualDebuggingEnabled(true);

支持

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

Documentation Index

​手动安装

​iOS 设置

​App Transport Security

​Android 设置

​初始化

​广告格式

横幅和 MREC 广告

插页式广告

激励视频广告

​广告信息 (CloudXAdInfo)

​错误处理

​错误码类别

​高级功能

​调试日志

​展示级收入追踪

​测试模式

​隐私合规

​工作原理

​支持的隐私密钥

​手动隐私 API

​用户定向

​App Tracking Transparency (iOS)

​可视化调试

​支持

手动安装

iOS 设置

App Transport Security

Android 设置

初始化

广告格式

广告信息 (CloudXAdInfo)

错误处理

错误码类别

高级功能

调试日志

展示级收入追踪

测试模式

隐私合规

工作原理

支持的隐私密钥

手动隐私 API

用户定向

App Tracking Transparency (iOS)

可视化调试

支持