> ## 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.

# Integration

> Complete guide to integrating the CloudX React Native SDK

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

The CloudX React Native SDK enables monetization of your React Native apps with banner, MREC, interstitial, and rewarded ads on iOS and Android. It supports both the New Architecture (Fabric) and the legacy architecture (Paper).

## Manual Installation

Requires React Native 0.70+, React 18.0+, iOS 13.0+, and Android API 23+.

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

### iOS Setup

Add ad network adapter pods to your `ios/Podfile`:

```ruby theme={null}
target 'YourApp' do
  # ... existing config ...

  # CloudX ad network adapters (add as needed)
  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 test ads
end
```

Then install pods:

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

<Note>
  The `CloudXCore` pod is automatically included as a dependency of the `cloudx-react-native` npm package. You only need to add the adapter pods you want.
</Note>

#### App Transport Security

If your ads use HTTP URLs, add the following to your `Info.plist`:

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

### Android Setup

Add CloudX SDK and adapter dependencies to your `android/app/build.gradle`:

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

    // Adapters for ad networks (add as needed)
    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.61.1"        // Mintegral SDK 17.1.61
    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>
  At least one adapter is required for the SDK to serve ads.
</Note>

If you integrate the Mintegral adapter, also declare its Maven repository in `android/build.gradle`:

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

## Initialization

Initialize the SDK before loading any ads:

```typescript theme={null}
import { CloudX, CloudXLogLevel } from 'cloudx-react-native';

// Optional: enable verbose logging (development only)
CloudX.setMinLogLevel(CloudXLogLevel.VERBOSE);

// Initialize with your app key
const result = await CloudX.initialize('YOUR_APP_KEY');
if (result.success) {
    console.log('CloudX initialized');
} else {
    console.error('CloudX init failed:', result.message);
}
```

`CloudX.initialize()` returns a `CloudXInitializationResult` with:

* `success: boolean` — whether initialization succeeded
* `message?: string` — additional details, populated on failure

Other initialization utilities:

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

## Ad Formats

CloudX React Native supports banner, MREC, interstitial, and rewarded ad integrations. Use the format-specific guides for implementation details:

<CardGroup cols={2}>
  <Card title="Banner & MREC ads" href="/en/react-native/ad-formats/banner-mrec">
    Create programmatic overlay display placements with optional refresh control.
  </Card>

  <Card title="Interstitial ads" href="/en/react-native/ad-formats/interstitial">
    Load and show full-screen interstitial placements.
  </Card>

  <Card title="Rewarded ads" href="/en/react-native/ad-formats/rewarded">
    Reward users after completed rewarded ad views.
  </Card>
</CardGroup>

### Ad Information (CloudXAdInfo)

Most ad event callbacks receive a `CloudXAdInfo` object:

| Property           | Type                     | Description                                                        |
| ------------------ | ------------------------ | ------------------------------------------------------------------ |
| `adUnitId`         | `string`                 | The ad unit ID                                                     |
| `adFormat`         | `string`                 | Ad format: `BANNER`, `MREC`, `INTERSTITIAL`, or `REWARDED`         |
| `networkName`      | `string`                 | Name of the winning ad network                                     |
| `networkPlacement` | `string \| null`         | Network-specific placement ID                                      |
| `placement`        | `string \| null`         | Custom placement set by your integration                           |
| `revenue`          | `number`                 | Revenue value in USD                                               |
| `adValues`         | `Record<string, string>` | SDK-provided ad metadata, used by features such as Trusted Arbiter |

### Error Handling

All SDK errors are returned as error objects in callbacks and rejected promises:

| Property  | Type              | Description                |
| --------- | ----------------- | -------------------------- |
| `code`    | `CloudXErrorCode` | Error category             |
| `message` | `string \| null`  | Human-readable description |

#### Error Code Categories

| Range   | Category       | Common Codes                                            |
| ------- | -------------- | ------------------------------------------------------- |
| 0       | General        | `internalError`                                         |
| 100-199 | Network        | `networkError`, `networkTimeout`, `networkNoConnection` |
| 200-299 | Initialization | `notInitialized`, `sdkDisabled`, `invalidAppKey`        |
| 300-399 | Ad Loading     | `noFill`, `invalidAdUnit`, `adsDisabled`                |
| 400-499 | Display        | `adNotReady`, `adAlreadyShowing`                        |
| 600-699 | Adapter        | `adapterNoFill`, `adapterTimeout`                       |

See `CloudXErrorCode` export for the full list of error codes.

## Advanced Features

### Debug Logging

```typescript theme={null}
import { CloudX, CloudXLogLevel } from 'cloudx-react-native';

// Enable verbose logging (call before initialize)
CloudX.setMinLogLevel(CloudXLogLevel.VERBOSE);

// Available levels: VERBOSE, DEBUG, INFO, WARN, ERROR, NONE
```

**Log Levels:** `VERBOSE` \< `DEBUG` \< `INFO` \< `WARN` \< `ERROR` \< `NONE`

Native SDK logs appear in the iOS and Android platform logs. JavaScript-side calls and event handling can also be logged through your app's normal React Native logging.

### Impression-Level Revenue Tracking

Set an `addAdRevenuePaidListener` callback on any ad format to receive impression-level revenue events. The `CloudXAdInfo` object includes the revenue value in USD and the winning network name.

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

Works with all React Native ad formats: banner, MREC, interstitial, and rewarded.

### Test Mode

Test mode is **server-controlled** via device whitelisting. This provides better security and control over which devices receive test ads.

**To enable test mode:**

1. Initialize the SDK with verbose logging enabled.
2. Find your device advertising ID in the iOS or Android platform logs.
3. Add the advertising ID to your device whitelist on the CloudX server dashboard.

**Note:** Test mode is determined by the server, so you don't need to change any code between development and production builds.

### Privacy Compliance

The CloudX SDK supports GDPR and CCPA privacy compliance by reading standard IAB privacy strings from platform storage (`NSUserDefaults` on iOS, `SharedPreferences` on Android). These values are typically set automatically by your Consent Management Platform (CMP), such as Google UMP, OneTrust, or Sourcepoint.

#### How It Works

The native SDKs automatically detect user location and read consent signals:

1. **EU Users (GDPR)**: Checks TCF v2 consent for purposes 1 and 2 per the [IAB Global Vendor List](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) and vendor consent ([CloudX Vendor ID: 1510](https://vendor-list.consensu.org/v3/vendor-list.json))
2. **US Users (CCPA)**: Checks for sale/sharing opt-out signals
3. **Other Regions**: No restrictions applied

When consent is denied or the user opts out, the SDK removes PII from ad requests:

* Advertising ID (IDFA/GAID) is cleared
* Geo coordinates (lat/lon) are removed
* User key-values are not sent
* Hashed user ID is excluded

#### Supported Privacy Keys

| Key                    | Standard                                                                                          | Description                                                        |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `IABGPP_HDR_GppString` | [GPP](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform)                    | Global Privacy Platform string (modern)                            |
| `IABGPP_GppSID`        | GPP                                                                                               | Section IDs (e.g., "2" for EU, "7" for US-National, "8" for US-CA) |
| `IABTCF_TCString`      | [TCF v2](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) | GDPR consent string (legacy)                                       |
| `IABTCF_gdprApplies`   | TCF v2                                                                                            | Whether GDPR applies (1 = yes, 0 = no)                             |
| `IABUSPrivacy_String`  | [US Privacy](https://github.com/InteractiveAdvertisingBureau/USPrivacy)                           | CCPA privacy string (legacy, e.g., "1YNN")                         |

> **Note**: The SDK prioritizes GPP (modern standard) over legacy TCF/US Privacy strings when both are available.

#### Manual Privacy API

If you manage user consent yourself (without a CMP), you can set GDPR and CCPA privacy status directly. These can be called before or after SDK initialization.

```typescript theme={null}
import { CloudX } from 'cloudx-react-native';

// GDPR consent: true, false, or null to defer to CMP
CloudX.setHasUserConsent(true);

// CCPA do-not-sell: true, false, or null to defer to CMP
CloudX.setDoNotSell(true);
```

<Note>
  When both manual values and CMP signals are present, CMP signals (GPP/TCF/US Privacy) take priority. Manual values act as a fallback when no CMP is integrated.
</Note>

### User Targeting

```typescript theme={null}
import { CloudX } from 'cloudx-react-native';

// Set hashed user ID for targeting
CloudX.setHashedUserID('hashed-user-id');

// Set custom user key-value pairs
CloudX.setUserKeyValue('age', '25');
CloudX.setUserKeyValue('gender', 'male');
CloudX.setUserKeyValue('location', 'US');

// Set custom app key-value pairs
CloudX.setAppKeyValue('app_version', '1.0.0');
CloudX.setAppKeyValue('user_level', 'premium');

// Clear all custom key-values
CloudX.clearAllKeyValues();
```

### App Tracking Transparency (iOS)

Request tracking authorization on iOS 14+:

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

const status = await requestTrackingAuthorization();
if (status === CloudXATTStatus.AUTHORIZED) {
    console.log('Tracking authorized');
}
```

<Note>
  Call `requestTrackingAuthorization()` before `CloudX.initialize()` for best ad targeting results.
</Note>

ATT status values: `AUTHORIZED`, `DENIED`, `RESTRICTED`, `NOT_DETERMINED`, `NOT_REQUIRED`.

On Android or iOS \< 14, `requestTrackingAuthorization()` returns `NOT_REQUIRED`.

### Visual Debugging

Enable visual debugging overlays to see ad unit boundaries and network info:

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

## Support

For support, contact [mobile@cloudx.io](mailto:mobile@cloudx.io)