> ## 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 完整集成指南

[![npm](https://img.shields.io/npm/v/cloudx-react-native)](https://www.npmjs.com/package/cloudx-react-native)

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

## 手动安装

要求 React Native 0.70+、React 18.0+、iOS 13.0+、Android API 23+。

```bash theme={null}
npm install cloudx-react-native
```

### iOS 设置

在 `ios/Podfile` 中添加广告网络适配器 Pod：

```ruby theme={null}
target 'YourApp' do
  # ... 现有配置 ...

  # CloudX 广告网络适配器（按需添加）
  pod 'CloudXMetaAdapter', '~> 3.4.5'       # Meta Audience Network >= 6.15.1, < 7.0
  pod 'CloudXVungleAdapter', '~> 3.4.5'     # VungleAds >= 7.4.0, < 8.0
  pod 'CloudXInMobiAdapter', '~> 3.4.5'     # InMobiSDK >= 11.2.0, < 12.0
  pod 'CloudXMintegralAdapter', '~> 3.4.5'  # MintegralAdSDK ~> 8.0
  pod 'CloudXUnityAdsAdapter', '~> 3.4.5'   # UnityAds >= 4.17.0, < 5.0
  pod 'CloudXMagniteAdapter', '~> 3.4.5'    # MagniteSDK ~> 1.0.0
  pod 'CloudXMolocoAdapter', '~> 3.4.5'     # MolocoSDKiOS ~> 4.6.0
  pod 'CloudXVerveAdapter', '~> 3.4.5'      # HyBid = 3.8.0
  pod 'CloudXDigitalTurbineAdapter', '~> 3.4.5'  # Fyber Marketplace SDK >= 8.0, < 9.0
  pod 'CloudXGoogleWaterfallAdapter', '~> 3.4.5'  # Google-Mobile-Ads-SDK 12.14.0
  pod 'CloudXPangleAdapter', '~> 3.4.5'           # Ads-Global ~> 7.9.0 (Pangle / ByteDance)
  pod 'CloudXRenderer', '~> 3.4.5'          # CloudX 测试广告
end
```

然后安装 Pod：

```bash theme={null}
cd ios && pod install
```

<Note>
  `CloudXCore` Pod 作为 `cloudx-react-native` npm 包的依赖项自动包含。您只需添加所需的适配器 Pod。
</Note>

#### App Transport Security

如果您的广告使用 HTTP URL，请在 `Info.plist` 中添加以下内容：

```xml theme={null}
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>
```

### Android 设置

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

```groovy theme={null}
dependencies {
    // CloudX Android SDK
    implementation "io.cloudx:sdk:4.1.5"

    // 广告网络适配器（按需添加）
    implementation "io.cloudx:adapter-digitalturbine:8.4.5.0"     // Digital Turbine (Fyber) SDK 8.4.5
    implementation "io.cloudx:adapter-googlewaterfall:23.6.0.0"   // Google Mobile Ads SDK 23.6.0
    implementation "io.cloudx:adapter-inmobi:11.3.0.0"            // InMobi SDK 11.3.0
    implementation "io.cloudx:adapter-magnite:1.0.0.0"            // Magnite Ads SDK 1.0.0
    implementation "io.cloudx:adapter-meta:6.21.0.2"              // Meta Audience Network 6.21.0
    implementation "io.cloudx:adapter-mintegral:17.1.51.0"        // Mintegral SDK 17.1.51
    implementation "io.cloudx:adapter-mobilefuse:1.11.0.0"        // MobileFuse SDK 1.11.0
    implementation "io.cloudx:adapter-moloco:4.9.0.0"             // Moloco SDK 4.9.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.4.0"             // Vungle SDK 7.7.4
}
```

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

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

```groovy theme={null}
allprojects {
    repositories {
        maven { url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea" }
    }
}
```

## 初始化

在加载任何广告之前初始化 SDK：

```typescript theme={null}
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` — 附加详情，失败时填充

其他初始化工具方法：

```typescript theme={null}
const initialized = await CloudX.isInitialized();
const version = await CloudX.getVersion();
const tablet = await CloudX.isTablet();
```

## 广告格式

CloudX React Native 支持横幅、MREC、插页式和激励视频广告集成。具体实现请参阅对应的广告格式指南：

<CardGroup cols={2}>
  <Card title="横幅和 MREC 广告" href="/zh/react-native/ad-formats/banner-mrec">
    创建程序化叠加展示广告位，并可控制刷新。
  </Card>

  <Card title="插页式广告" href="/zh/react-native/ad-formats/interstitial">
    加载并展示全屏插页式广告位。
  </Card>

  <Card title="激励视频广告" href="/zh/react-native/ad-formats/rewarded">
    在用户完成激励视频观看后发放奖励。
  </Card>
</CardGroup>

### 广告信息 (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` 导出。

## 高级功能

### 调试日志

```typescript theme={null}
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` 对象包含美元收入值和胜出广告网络名称。

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

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

### 测试模式

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

**启用测试模式：**

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

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

### 隐私合规

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

#### 工作原理

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

1. **欧盟用户 (GDPR)**：根据 [IAB 全球供应商列表](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) 检查 TCF v2 目的 1 和 2 的同意和供应商同意（[CloudX 供应商 ID：1510](https://vendor-list.consensu.org/v3/vendor-list.json)）
2. **美国用户 (CCPA)**：检查销售/共享退出信号
3. **其他地区**：不应用限制

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

* 广告 ID (IDFA/GAID) 被清除
* 地理坐标（经纬度）被删除
* 用户键值对不发送
* 哈希用户 ID 被排除

#### 支持的隐私密钥

| 键                      | 标准                                                                                                | 描述                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `IABGPP_HDR_GppString` | [GPP](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform)                    | 全球隐私平台字符串（现代）                            |
| `IABGPP_GppSID`        | GPP                                                                                               | 部分 ID（例如，"2" 代表欧盟，"7" 代表美国国家，"8" 代表美国加州） |
| `IABTCF_TCString`      | [TCF v2](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) | GDPR 同意字符串（传统）                           |
| `IABTCF_gdprApplies`   | TCF v2                                                                                            | GDPR 是否适用（1 = 是，0 = 否）                   |
| `IABUSPrivacy_String`  | [US Privacy](https://github.com/InteractiveAdvertisingBureau/USPrivacy)                           | CCPA 隐私字符串（传统，例如 "1YNN"）                 |

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

#### 手动隐私 API

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

```typescript theme={null}
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);
```

<Note>
  当手动设置值和 CMP 信号同时存在时，CMP 信号（GPP/TCF/US Privacy）优先。手动设置值在未集成 CMP 时作为回退使用。
</Note>

### 用户定向

```typescript theme={null}
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+ 上请求跟踪授权：

```typescript theme={null}
import { requestTrackingAuthorization, getTrackingAuthorizationStatus, CloudXATTStatus } from 'cloudx-react-native';

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

<Note>
  在 `CloudX.initialize()` 之前调用 `requestTrackingAuthorization()` 以获得最佳广告定向效果。
</Note>

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

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

### 可视化调试

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

```typescript theme={null}
CloudX.setVisualDebuggingEnabled(true);
```

## 支持

如需支持，请联系 [mobile@cloudx.io](mailto:mobile@cloudx.io)