cloudx-react-native 2.0.0-beta.1 → 2.0.0

package/README.md

@@ -1,1258 +1,632 @@
 # CloudX React Native SDK
 
-A React Native wrapper for the CloudX native SDKs, providing a comprehensive solution for programmatic advertising with full privacy compliance support.
+[![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).
 
 ## Features
 
-- **Full SDK Integration**: Complete wrapper for CloudX Core SDK
-- **Cross-Platform Ready**: iOS support (Android coming soon)
-- **All Ad Types**: Banner, Interstitial, Rewarded, Native, and MREC ads
-- **Privacy**: IAB privacy compliance is handled by the native SDK automatically
-- **Event System**: React Native event emitter pattern for ad lifecycle management
-- **Error Handling**: Comprehensive error handling with detailed error codes
-- **Type Safety**: Full TypeScript support with complete type definitions
-- **React Hooks**: Custom hooks for seamless React integration
-- **Modern Patterns**: Follows React Native 0.70+ best practices
+- **Cross-Platform**: Full iOS and Android support
+- **Dual Architecture**: Works on both Fabric (New Architecture) and Paper (Legacy)
+- **All Ad Formats**: Banner, MREC, Interstitial, and Rewarded ads
+- **Programmatic Ad APIs**: Overlay APIs for banner and MREC, plus fullscreen formats
+- **React Hooks**: Declarative hooks for fullscreen and banner ad lifecycles
+- **Privacy Compliance**: IAB privacy handled automatically via CMP shared storage
+- **App Tracking Transparency**: Built-in ATT support for iOS 14+
+- **Type Safety**: Full TypeScript definitions with CloudX-prefixed namespace
 
 ## Installation
 
+Requires React Native 0.70+, React 18.0+, iOS 13.0+, and Android API 23+.
+
 ```bash
 npm install cloudx-react-native
-# or
-yarn add cloudx-react-native
 ```
 
 ### iOS Setup
 
-1. Add to your `Podfile`:
+Add ad network adapter pods to your `ios/Podfile`:
 
 ```ruby
-# CloudX Core SDK
-pod 'CloudXCore'
+target 'YourApp' do
+  # ... existing config ...
 
-# Optional: CloudX Adapters
-pod 'CloudXMetaAdapter'
+  # CloudX ad network adapters (add as needed)
+  pod 'CloudXMetaAdapter', '~> 2.2.0-beta'
+  pod 'CloudXVungleAdapter', '~> 2.2.0-beta'
+  pod 'CloudXInMobiAdapter', '~> 2.2.0-beta'
+  pod 'CloudXRenderer', '~> 2.2.0-beta'
+end
 ```
 
-2. Install pods:
+Then install pods:
 
 ```bash
 cd ios && pod install
 ```
 
-3. Add required permissions to `Info.plist`:
-
-```xml
-<key>NSUserTrackingUsageDescription</key>
-<string>This app uses tracking to provide personalized ads and better user experience.</string>
-
-<key>SKAdNetworkItems</key>
-<array>
-  <!-- Add your SKAdNetwork IDs -->
-</array>
-```
-
-### Android Setup
-
-> ⚠️ **Android support coming soon**
+> **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.
 
----
+#### App Transport Security
 
-## Quick Start
+If your ads use HTTP URLs, add the following to your `Info.plist`:
 
-### 1. Initialize the SDK
-
-```javascript
-import CloudXSDK from 'cloudx-react-native';
-
-// Initialize CloudX SDK (testMode: false = production, true = test ads)
-const result = await CloudXSDK.initialize({
-  appKey: 'YOUR_APP_KEY',
-  testMode: false, // false = production, true = test ads
-});
-
-if (result.success) {
-  console.log('CloudX SDK initialized successfully');
-} else {
-  console.error('Failed to initialize CloudX SDK:', result.message);
-}
-
-
-// Check if initialized
-const isInitialized = await CloudXSDK.isInitialized();
+```xml
+<key>NSAppTransportSecurity</key>
+<dict>
+  <key>NSAllowsArbitraryLoads</key>
+  <true/>
+</dict>
 ```
 
-#### Test Mode
-
-The SDK supports an optional `testMode` parameter:
-
-- **Production (`testMode: false`)**: Real ads with actual billing. Use for production releases.
-- **Test Mode (`testMode: true`)**: Test ads without billing. Use for development and QA testing.
-
-When `testMode` is enabled:
-- Bid requests include `test=1` flag per OpenRTB spec
-- Adapter SDKs are configured for test mode (e.g., Meta test ads)
-- No real monetization occurs
-
-### 2. Using React Hooks (Recommended)
-
-```jsx
-import { useCloudXInterstitial, useCloudXRewarded } from 'cloudx-react-native';
-
-function GameOverScreen() {
-  const interstitial = useCloudXInterstitial({
-    placement: 'game-over-interstitial',
-    adId: 'interstitial-1',
-    onLoaded: (ad) => console.log('Interstitial ready:', ad.placementName),
-    onFailed: (error) => console.error('Failed to load:', error),
-    onShown: (ad) => console.log('Interstitial shown'),
-    onClosed: (ad) => console.log('Interstitial closed'),
-    onRevenuePaid: (ad) => console.log('Revenue:', ad.revenue, ad.currency),
-  });
-
-  return (
-    <View>
-      <Button
-        title="Show Interstitial"
-        onPress={() => interstitial.show()}
-        disabled={!interstitial.isReady || interstitial.isLoading}
-      />
-      {interstitial.isLoading && <ActivityIndicator />}
-    </View>
-  );
-}
-```
+### Android Setup
 
-### 3. Banner Ads (Component)
+Add CloudX SDK and adapter dependencies to your `android/app/build.gradle`:
 
-```jsx
-import { CloudXBannerView, BannerSizes } from 'cloudx-react-native';
+```kotlin
+dependencies {
+    // CloudX Android SDK
+    implementation "io.cloudx:sdk:2.0.0"
 
-function HomeScreen() {
-  return (
-    <View style={styles.container}>
-      <Text>Your Content Here</Text>
-      
-      <CloudXBannerView
-        placement="home-banner"
-        adId="banner-1"
-        bannerSize={BannerSizes.BANNER}
-        autoRefresh={true}
-        refreshInterval={30000}
-        onAdLoaded={(event) => console.log('Banner loaded:', event.ad)}
-        onAdFailedToLoad={(event) => console.error('Banner failed:', event.error)}
-        onAdImpression={(event) => trackImpression(event.ad)}
-        onRevenuePaid={(event) => trackRevenue(event.ad)}
-        style={styles.banner}
-      />
-    </View>
-  );
+    // Adapters for ad networks (add as needed)
+    implementation "io.cloudx:adapter-cloudx:2.0.0"
+    implementation "io.cloudx:adapter-meta:2.0.0"
+    implementation "io.cloudx:adapter-vungle:2.0.0"
+    implementation "io.cloudx:adapter-inmobi:2.0.0"
 }
-
-const styles = StyleSheet.create({
-  banner: {
-    width: 320,
-    height: 50,
-    marginVertical: 10,
-  },
-});
 ```
 
----
-
-## API Reference
+> **Note:** At least one adapter is required for the SDK to serve ads.
 
-### SDK Initialization
+## Initialization
 
-#### `initialize(appKey: string | InitOptions): Promise<InitResult>`
+Initialize the SDK before loading any ads:
 
-Initialize the CloudX SDK. Must be called before using any other SDK methods.
+```typescript
+import { CloudX, CloudXLogLevel } from 'cloudx-react-native';
 
-```javascript
-// Production initialization
-const result = await CloudXSDK.initialize({
-  appKey: 'YOUR_APP_KEY',
-  testMode: false, // false = production, true = test ads
-});
+// Optional: enable verbose logging (development only)
+CloudX.setMinLogLevel(CloudXLogLevel.VERBOSE);
 
-// result = { success: boolean, message?: string }
+// 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);
+}
 ```
 
-**InitOptions:**
-- `appKey` (string, required): Your CloudX app key
-- `testMode` (boolean, optional): Enable test mode (false = production, true = test ads)
+### Initialization API
 
-**Note:** To set a hashed user ID for targeting, call `CloudXSDK.setHashedUserID()` separately before or after initialization.
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `CloudX.initialize(appKey)` | `Promise<CloudXInitializationResult>` | Initialize the SDK with your app key |
+| `CloudX.isInitialized()` | `Promise<boolean>` | Check if the SDK has been initialized |
+| `CloudX.getVersion()` | `Promise<string>` | Get the native SDK version string |
+| `CloudX.isTablet()` | `Promise<boolean>` | Check if the device is a tablet |
 
-#### `isInitialized(): Promise<boolean>`
+The `CloudXInitializationResult` contains:
+- `success: boolean` — whether initialization succeeded
+- `message?: string` — additional details on failure
 
-Check if the SDK has been initialized.
+## Ad Integration
 
-```javascript
-const initialized = await CloudXSDK.isInitialized();
-```
+### Banner Ads (Programmatic Overlay)
 
-#### `getVersion(): Promise<string>`
+Banners overlay your content at a fixed screen position:
 
-Get the CloudX SDK version.
+```typescript
+import { CloudXBannerAd, CloudXAdPosition } from 'cloudx-react-native';
 
-```javascript
-const version = await CloudXSDK.getVersion();
-console.log('CloudX SDK version:', version);
-```
+const AD_UNIT_ID = 'home_banner';
 
-#### `setLoggingEnabled(enabled: boolean): Promise<void>`
+// Set up event listeners
+CloudXBannerAd.addAdLoadedEventListener((adInfo) => {
+    console.log('Banner loaded from', adInfo.networkName);
+});
+CloudXBannerAd.addAdLoadFailedEventListener((error) => {
+    console.log('Banner failed:', error.code, error.message);
+});
+CloudXBannerAd.addAdRevenuePaidListener((adInfo) => {
+    console.log('Banner revenue:', adInfo.revenue);
+});
 
-Enable or disable verbose SDK logging (useful for debugging).
+// Create and show
+CloudXBannerAd.createAd(AD_UNIT_ID, CloudXAdPosition.BOTTOM_CENTER);
+CloudXBannerAd.showAd(AD_UNIT_ID);
 
-```javascript
-// Enable logging in development
-if (__DEV__) {
-  await CloudXSDK.setLoggingEnabled(true);
-}
+// Hide / destroy when done
+CloudXBannerAd.hideAd(AD_UNIT_ID);
+CloudXBannerAd.destroyAd(AD_UNIT_ID);
 ```
 
-#### `setEnvironment(environment: 'dev' | 'staging' | 'production'): Promise<void>`
+Auto-refresh is enabled by default. To control it manually:
 
-Set the SDK environment. Must be called **before** `initialize()`.
-
-```javascript
-await CloudXSDK.setEnvironment('staging');
-await CloudXSDK.initialize('YOUR_APP_KEY');
+```typescript
+CloudXBannerAd.stopAutoRefresh(AD_UNIT_ID);
+CloudXBannerAd.startAutoRefresh(AD_UNIT_ID);
 ```
 
----
+#### Full Banner API
 
-## User Targeting
+| Method | Description |
+|--------|-------------|
+| `createAd(adUnitId, position)` | Create a banner at the given `CloudXAdPosition` |
+| `createAdWithOffsets(adUnitId, position, xOffset, yOffset)` | Create with pixel offsets from the position anchor |
+| `showAd(adUnitId)` | Show the banner |
+| `hideAd(adUnitId)` | Hide the banner (preserves the ad) |
+| `destroyAd(adUnitId)` | Destroy the banner and release resources |
+| `updatePosition(adUnitId, position)` | Move to a new `CloudXAdPosition` |
+| `updateOffsets(adUnitId, xOffset, yOffset)` | Update pixel offsets |
+| `setBackgroundColor(adUnitId, hexColor)` | Set banner background color (e.g., `"#000000"`) |
+| `setPlacement(adUnitId, placement)` | Set placement name for reporting |
+| `setCustomData(adUnitId, customData)` | Set custom data string |
+| `startAutoRefresh(adUnitId)` | Resume auto-refresh |
+| `stopAutoRefresh(adUnitId)` | Pause auto-refresh |
 
-### Hashed User ID
+#### Banner Events
 
-```javascript
-// Set hashed user ID for targeting
-await CloudXSDK.setHashedUserID('hashed-email-or-user-id');
+| Method | Callback Parameter |
+|--------|--------------------|
+| `addAdLoadedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdLoadFailedEventListener(fn)` | `CloudXAdLoadFailedInfo` |
+| `addAdClickedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdExpandedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdCollapsedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdRevenuePaidListener(fn)` | `CloudXAdInfo` |
 
-// Get current user ID
-const userId = await CloudXSDK.getUserID();
+Each `add*` listener has a corresponding `remove*` method (e.g., `removeAdLoadedEventListener()`).
 
-// Clear user ID
-await CloudXSDK.setUserID(null);
-```
+### MREC Ads (Programmatic Overlay)
 
-### User-Level Targeting
+MRECs work identically to banners but with a 300x250 size:
 
-User-level key-values are **cleared automatically** when privacy regulations require removing personal data.
+```typescript
+import { CloudXMRECAd, CloudXAdPosition } from 'cloudx-react-native';
 
-```javascript
-import { CloudX } from 'cloudx-react-native';
+const AD_UNIT_ID = 'home_mrec';
 
-// User-specific targeting (privacy-sensitive)
-CloudX.setUserKeyValue('age', '25');
-CloudX.setUserKeyValue('interests', 'gaming');
-CloudX.setUserKeyValue('subscription', 'premium');
-```
-
-### App-Level Targeting
+CloudXMRECAd.addAdLoadedEventListener((adInfo) => {
+    console.log('MREC loaded from', adInfo.networkName);
+});
 
-App-level key-values are **NOT affected** by privacy regulations and persist across privacy changes.
+CloudXMRECAd.createAd(AD_UNIT_ID, CloudXAdPosition.CENTERED);
+CloudXMRECAd.showAd(AD_UNIT_ID);
 
-```javascript
-// App-specific targeting (persistent)
-CloudX.setAppKeyValue('app_version', '1.2.0');
-CloudX.setAppKeyValue('build_type', 'release');
-CloudX.setAppKeyValue('theme', 'dark');
+// Destroy when done
+CloudXMRECAd.destroyAd(AD_UNIT_ID);
 ```
 
-### Clear Targeting
+The MREC API surface is identical to Banner — all the same methods and events are available on `CloudXMRECAd`, including `createAdWithOffsets`, `updatePosition`, `updateOffsets`, `setBackgroundColor`, `setPlacement`, `setCustomData`, auto-refresh control, and all event listeners.
 
-```javascript
-// Clear all targeting key-values
-CloudX.clearAllKeyValues();
-```
+### Interstitial Ads
 
----
-
-## Banner Ads
-
-### Using BannerView Component (Recommended)
-
-```jsx
-import { CloudXBannerView, BannerSizes } from 'cloudx-react-native';
-
-function MyComponent() {
-  return (
-    <CloudXBannerView
-      // Required
-      placement="banner-placement"
-      adId="banner-1"
-      
-      // Optional
-      bannerSize={BannerSizes.BANNER} // BANNER, MREC, LEADERBOARD
-      autoRefresh={true}
-      refreshInterval={30000} // milliseconds
-      
-      // Event callbacks
-      onAdLoaded={(event) => console.log('Banner loaded:', event.ad)}
-      onAdFailedToLoad={(event) => console.error('Failed:', event.error)}
-      onAdShown={(event) => console.log('Banner shown')}
-      onAdImpression={(event) => console.log('Impression tracked')}
-      onAdClicked={(event) => console.log('Banner clicked')}
-      onAdExpanded={(event) => console.log('Banner expanded')}
-      onAdCollapsed={(event) => console.log('Banner collapsed')}
-      onRevenuePaid={(event) => console.log('Revenue:', event.ad.revenue)}
-      
-      // Styling
-      style={{ width: 320, height: 50 }}
-    />
-  );
-}
-```
+Full-screen ads shown at natural transition points.
 
-### Using Custom Hook
-
-```jsx
-import { useCloudXBanner } from 'cloudx-react-native';
-
-function MyComponent() {
-  const banner = useCloudXBanner({
-    placement: 'banner-placement',
-    adId: 'banner-1',
-    bannerSize: BannerSizes.BANNER,
-    autoRefresh: true,
-    onLoaded: (ad) => console.log('Banner ready'),
-    onRevenuePaid: (ad) => trackRevenue(ad),
-  });
-
-  return (
-    <View>
-      {banner.render({ style: styles.banner })}
-      {banner.isLoading && <ActivityIndicator />}
-    </View>
-  );
-}
-```
+```typescript
+import { CloudXInterstitialAd } from 'cloudx-react-native';
 
-### Imperative API
+const AD_UNIT_ID = 'level_complete';
 
-```javascript
-// Create banner
-await CloudXSDK.createBanner({
-  placement: 'banner-placement',
-  adId: 'banner-1',
-  bannerSize: BannerSizes.BANNER,
+// Set up event listeners
+CloudXInterstitialAd.addAdLoadedEventListener((adInfo) => {
+    console.log('Interstitial loaded');
+});
+CloudXInterstitialAd.addAdLoadFailedEventListener((error) => {
+    console.log('Interstitial load failed:', error.code, error.message);
+});
+CloudXInterstitialAd.addAdDisplayedEventListener((adInfo) => {
+    console.log('Interstitial displayed');
+});
+CloudXInterstitialAd.addAdFailedToDisplayEventListener((error) => {
+    console.log('Interstitial display failed:', error.code, error.message);
+});
+CloudXInterstitialAd.addAdHiddenEventListener((adInfo) => {
+    // Reload for next use
+    CloudXInterstitialAd.loadAd(AD_UNIT_ID);
+});
+CloudXInterstitialAd.addAdRevenuePaidListener((adInfo) => {
+    console.log('Revenue:', adInfo.revenue);
 });
 
-// Load banner
-await CloudXSDK.loadBanner({ adId: 'banner-1' });
-
-// Show banner (if hidden)
-await CloudXSDK.showBanner({ adId: 'banner-1' });
-
-// Hide banner (keeps it loaded)
-await CloudXSDK.hideBanner({ adId: 'banner-1' });
+// Load
+CloudXInterstitialAd.loadAd(AD_UNIT_ID);
 
-// Auto-refresh control
-await CloudXSDK.startAutoRefresh({ adId: 'banner-1' });
-await CloudXSDK.stopAutoRefresh({ adId: 'banner-1' });
+// Show when ready (with optional placement and custom data)
+const isReady = await CloudXInterstitialAd.isAdReady(AD_UNIT_ID);
+if (isReady) {
+    CloudXInterstitialAd.showAd(AD_UNIT_ID);
+    // or with placement/custom data:
+    // CloudXInterstitialAd.showAd(AD_UNIT_ID, 'level_end', 'custom_data');
+}
 
-// Destroy banner (cleanup)
-await CloudXSDK.destroyAd({ adId: 'banner-1' });
+// Destroy when done
+CloudXInterstitialAd.destroyAd(AD_UNIT_ID);
 ```
 
-### Banner Sizes
+#### Interstitial API
 
-```javascript
-export const BannerSizes = {
-  BANNER: 'BANNER',           // 320x50
-  MREC: 'MREC',              // 300x250
-  LEADERBOARD: 'LEADERBOARD', // 728x90
-};
-```
+| Method | Description |
+|--------|-------------|
+| `loadAd(adUnitId)` | Start loading an interstitial |
+| `isAdReady(adUnitId)` | Returns `Promise<boolean>` — whether an ad is ready to show |
+| `showAd(adUnitId, placement?, customData?)` | Show the loaded interstitial |
+| `destroyAd(adUnitId)` | Destroy the interstitial and release resources |
 
----
+#### Interstitial Events
 
-## Interstitial Ads
+| Method | Callback Parameter |
+|--------|--------------------|
+| `addAdLoadedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdLoadFailedEventListener(fn)` | `CloudXAdLoadFailedInfo` |
+| `addAdDisplayedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdFailedToDisplayEventListener(fn)` | `CloudXAdDisplayFailedInfo` |
+| `addAdClickedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdHiddenEventListener(fn)` | `CloudXAdInfo` |
+| `addAdRevenuePaidListener(fn)` | `CloudXAdInfo` |
 
-### Using React Hook (Recommended)
+### Rewarded Ads
 
-```jsx
-import { useCloudXInterstitial } from 'cloudx-react-native';
+Full-screen ads that grant users a reward upon completion.
 
-function GameOverScreen() {
-  const interstitial = useCloudXInterstitial({
-    placement: 'game-over-interstitial',
-    adId: 'interstitial-1',
-    
-    // Event callbacks
-    onLoaded: (ad) => {
-      console.log('Interstitial ready:', ad.placementName);
-      setAdReady(true);
-    },
-    onFailedToLoad: (error) => {
-      console.error('Failed to load:', error);
-    },
-    onShown: (ad) => {
-      console.log('Interstitial shown');
-      pauseGame();
-    },
-    onFailedToShow: (error) => {
-      console.error('Failed to show:', error);
-    },
-    onImpression: (ad) => {
-      console.log('Impression tracked:', ad.revenue);
-    },
-    onClosed: (ad) => {
-      console.log('Interstitial closed');
-      resumeGame();
-    },
-    onClicked: (ad) => {
-      console.log('Interstitial clicked');
-    },
-    onRevenuePaid: (ad) => {
-      console.log('Revenue:', ad.revenue, ad.currency);
-      trackRevenue(ad);
-    },
-  });
-
-  useEffect(() => {
-    // Auto-load on mount
-    interstitial.load();
-    
-    // Cleanup on unmount
-    return () => {
-      interstitial.destroy();
-    };
-  }, []);
-
-  return (
-    <View>
-      <Text>Game Over!</Text>
-      <Button
-        title="Continue (Watch Ad)"
-        onPress={() => interstitial.show()}
-        disabled={!interstitial.isReady || interstitial.isShowing}
-      />
-      {interstitial.isLoading && <ActivityIndicator />}
-    </View>
-  );
-}
-```
+```typescript
+import { CloudXRewardedAd } from 'cloudx-react-native';
 
-### Imperative API
+const AD_UNIT_ID = 'rewarded_coins';
 
-```javascript
-// Create interstitial
-await CloudXSDK.createInterstitial({
-  placement: 'interstitial-placement',
-  adId: 'interstitial-1',
+// Set up event listeners
+CloudXRewardedAd.addAdLoadedEventListener((adInfo) => {
+    console.log('Rewarded loaded');
+});
+CloudXRewardedAd.addAdLoadFailedEventListener((error) => {
+    console.log('Rewarded load failed:', error.code, error.message);
+});
+CloudXRewardedAd.addAdDisplayedEventListener((adInfo) => {
+    console.log('Rewarded displayed');
+});
+CloudXRewardedAd.addAdFailedToDisplayEventListener((error) => {
+    console.log('Rewarded display failed:', error.code, error.message);
+});
+CloudXRewardedAd.addAdReceivedRewardEventListener((rewardInfo) => {
+    console.log(`Earned ${rewardInfo.rewardAmount} ${rewardInfo.rewardLabel}`);
+});
+CloudXRewardedAd.addAdHiddenEventListener((adInfo) => {
+    // Reload for next use
+    CloudXRewardedAd.loadAd(AD_UNIT_ID);
+});
+CloudXRewardedAd.addAdRevenuePaidListener((adInfo) => {
+    console.log('Revenue:', adInfo.revenue);
 });
 
-// Load interstitial
-await CloudXSDK.loadInterstitial({ adId: 'interstitial-1' });
-
-// Check if ready
-const isReady = await CloudXSDK.isInterstitialReady({ adId: 'interstitial-1' });
+// Load
+CloudXRewardedAd.loadAd(AD_UNIT_ID);
 
-// Show interstitial
+// Show when ready (with optional placement and custom data)
+const isReady = await CloudXRewardedAd.isAdReady(AD_UNIT_ID);
 if (isReady) {
-  await CloudXSDK.showInterstitial({ adId: 'interstitial-1' });
+    CloudXRewardedAd.showAd(AD_UNIT_ID);
 }
 
 // Destroy when done
-await CloudXSDK.destroyAd({ adId: 'interstitial-1' });
+CloudXRewardedAd.destroyAd(AD_UNIT_ID);
 ```
 
----
+#### Rewarded API
 
-## Rewarded Ads
+| Method | Description |
+|--------|-------------|
+| `loadAd(adUnitId)` | Start loading a rewarded ad |
+| `isAdReady(adUnitId)` | Returns `Promise<boolean>` — whether an ad is ready to show |
+| `showAd(adUnitId, placement?, customData?)` | Show the loaded rewarded ad |
+| `destroyAd(adUnitId)` | Destroy the rewarded ad and release resources |
 
-### Using React Hook (Recommended)
+#### Rewarded Events
 
-```jsx
-import { useCloudXRewarded } from 'cloudx-react-native';
-
-function RewardButton() {
-  const rewarded = useCloudXRewarded({
-    placement: 'extra-lives-rewarded',
-    adId: 'rewarded-1',
-    
-    onLoaded: (ad) => console.log('Rewarded ad ready'),
-    onFailedToLoad: (error) => console.error('Failed:', error),
-    onShown: (ad) => console.log('Showing rewarded ad'),
-    onRewardEarned: (ad) => {
-      console.log('🎉 User earned reward!');
-      grantExtraLife();
-    },
-    onVideoStarted: (ad) => console.log('Video started'),
-    onVideoCompleted: (ad) => console.log('Video completed'),
-    onClosed: (ad) => console.log('Rewarded ad closed'),
-    onRevenuePaid: (ad) => trackRevenue(ad),
-  });
-
-  useEffect(() => {
-    rewarded.load();
-    return () => rewarded.destroy();
-  }, []);
-
-  return (
-    <Button
-      title="Watch Ad for Extra Life"
-      onPress={() => rewarded.show()}
-      disabled={!rewarded.isReady}
-    />
-  );
-}
-```
+| Method | Callback Parameter |
+|--------|--------------------|
+| `addAdLoadedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdLoadFailedEventListener(fn)` | `CloudXAdLoadFailedInfo` |
+| `addAdDisplayedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdFailedToDisplayEventListener(fn)` | `CloudXAdDisplayFailedInfo` |
+| `addAdClickedEventListener(fn)` | `CloudXAdInfo` |
+| `addAdHiddenEventListener(fn)` | `CloudXAdInfo` |
+| `addAdReceivedRewardEventListener(fn)` | `CloudXAdRewardInfo` |
+| `addAdRevenuePaidListener(fn)` | `CloudXAdInfo` |
 
-### Imperative API
+## React Hooks
 
-```javascript
-// Create rewarded ad
-await CloudXSDK.createRewarded({
-  placement: 'rewarded-placement',
-  adId: 'rewarded-1',
-});
+The SDK provides React hooks for declarative ad management that handle event subscriptions and cleanup automatically.
 
-// Load rewarded ad
-await CloudXSDK.loadRewarded({ adId: 'rewarded-1' });
+### useCloudXInterstitial
 
-// Check if ready
-const isReady = await CloudXSDK.isRewardedReady({ adId: 'rewarded-1' });
+```typescript
+import { useCloudXInterstitial } from 'cloudx-react-native';
 
-// Show rewarded ad
-if (isReady) {
-  await CloudXSDK.showRewarded({ adId: 'rewarded-1' });
-}
+function GameScreen() {
+    const { isLoaded, isLoading, error, load, show, destroy } =
+        useCloudXInterstitial('level_complete');
 
-// Listen for reward event
-const listener = CloudXSDK.addEventListener(
-  CloudXEventTypes.REWARD_EARNED,
-  (event) => {
-    if (event.ad.adId === 'rewarded-1') {
-      console.log('User earned reward!');
-      grantReward();
-    }
-  }
-);
-
-// Clean up
-listener.remove();
-await CloudXSDK.destroyAd({ adId: 'rewarded-1' });
-```
+    useEffect(() => {
+        load();
+    }, [load]);
 
----
-
-## Native Ads
-
-### Using React Hook (Recommended)
-
-```jsx
-import { useCloudXNative } from 'cloudx-react-native';
-
-function FeedItemAd({ index }) {
-  const nativeAd = useCloudXNative({
-    placement: 'feed-native',
-    adId: `native-${index}`,
-    
-    onLoaded: (ad) => {
-      console.log('Native ad loaded:', ad.assets);
-    },
-    onFailedToLoad: (error) => console.error('Failed:', error),
-    onImpression: (ad) => trackImpression(ad),
-    onClicked: (ad) => console.log('Native ad clicked'),
-    onRevenuePaid: (ad) => trackRevenue(ad),
-  });
-
-  useEffect(() => {
-    nativeAd.load();
-    return () => nativeAd.destroy();
-  }, []);
-
-  if (!nativeAd.isLoaded || !nativeAd.assets) {
-    return null;
-  }
-
-  return (
-    <View style={styles.nativeAd}>
-      {nativeAd.assets.iconUrl && (
-        <Image source={{ uri: nativeAd.assets.iconUrl }} style={styles.icon} />
-      )}
-      <View style={styles.content}>
-        <Text style={styles.title}>{nativeAd.assets.title}</Text>
-        <Text style={styles.body}>{nativeAd.assets.body}</Text>
-        {nativeAd.assets.callToAction && (
-          <TouchableOpacity
-            style={styles.cta}
-            onPress={() => nativeAd.click()}
-          >
-            <Text style={styles.ctaText}>{nativeAd.assets.callToAction}</Text>
-          </TouchableOpacity>
-        )}
-      </View>
-      <Text style={styles.adBadge}>Ad</Text>
-    </View>
-  );
+    return (
+        <Button
+            title={isLoading ? 'Loading...' : 'Show Ad'}
+            onPress={() => show()}
+            disabled={!isLoaded}
+        />
+    );
 }
 ```
 
-### Imperative API
+Returns `CloudXInterstitialHookResult`:
+- `isLoaded: boolean` — ad is ready to show
+- `isLoading: boolean` — load in progress
+- `error: string | null` — last error message
+- `load()` — start loading
+- `show(placement?, customData?)` — show the loaded ad
+- `destroy()` — destroy and reset state
 
-```javascript
-// Create native ad
-await CloudXSDK.createNative({
-  placement: 'native-placement',
-  adId: 'native-1',
-});
+### useCloudXRewarded
 
-// Load native ad
-await CloudXSDK.loadNative({ adId: 'native-1' });
-
-// Get native ad assets
-const assets = await CloudXSDK.getNativeAdAssets({ adId: 'native-1' });
-// assets = {
-//   title: string,
-//   body: string,
-//   callToAction: string,
-//   iconUrl: string,
-//   imageUrl: string,
-//   starRating: number,
-//   advertiser: string,
-// }
-
-// Register view for impression tracking
-await CloudXSDK.registerNativeAdView({ adId: 'native-1' });
-
-// Track click
-await CloudXSDK.trackNativeAdClick({ adId: 'native-1' });
-
-// Destroy
-await CloudXSDK.destroyAd({ adId: 'native-1' });
-```
+```typescript
+import { useCloudXRewarded } from 'cloudx-react-native';
 
----
-
-## MREC Ads
-
-MREC (Medium Rectangle) ads are 300x250 banner ads commonly used in content feeds.
-
-### Using Component
-
-```jsx
-import { CloudXBannerView, BannerSizes } from 'cloudx-react-native';
-
-function ContentFeed() {
-  return (
-    <ScrollView>
-      <Article />
-      <Article />
-      
-      {/* MREC ad between content */}
-      <CloudXBannerView
-        placement="feed-mrec"
-        adId="mrec-1"
-        bannerSize={BannerSizes.MREC}
-        autoRefresh={true}
-        onAdLoaded={(event) => console.log('MREC loaded')}
-        onRevenuePaid={(event) => trackRevenue(event.ad)}
-        style={{ width: 300, height: 250, alignSelf: 'center' }}
-      />
-      
-      <Article />
-      <Article />
-    </ScrollView>
-  );
+function RewardScreen() {
+    const { isLoaded, isLoading, error, rewardEarned, load, show } =
+        useCloudXRewarded('rewarded_coins');
+
+    useEffect(() => {
+        load();
+    }, [load]);
+
+    useEffect(() => {
+        if (rewardEarned) {
+            grantCoinsToUser();
+        }
+    }, [rewardEarned]);
+
+    return (
+        <Button
+            title="Watch Ad for Coins"
+            onPress={() => show()}
+            disabled={!isLoaded}
+        />
+    );
 }
 ```
 
----
-
-## Event Handling
-
-### Event Types
-
-```javascript
-import { CloudXEventTypes } from 'cloudx-react-native';
-
-// Banner Events
-CloudXEventTypes.BANNER_LOADED
-CloudXEventTypes.BANNER_FAILED_TO_LOAD
-CloudXEventTypes.BANNER_SHOWN
-CloudXEventTypes.BANNER_FAILED_TO_SHOW
-CloudXEventTypes.BANNER_HIDDEN
-CloudXEventTypes.BANNER_CLICKED
-CloudXEventTypes.BANNER_IMPRESSION
-CloudXEventTypes.BANNER_EXPANDED
-CloudXEventTypes.BANNER_COLLAPSED
-CloudXEventTypes.BANNER_REVENUE_PAID
-
-// Interstitial Events
-CloudXEventTypes.INTERSTITIAL_LOADED
-CloudXEventTypes.INTERSTITIAL_FAILED_TO_LOAD
-CloudXEventTypes.INTERSTITIAL_SHOWN
-CloudXEventTypes.INTERSTITIAL_FAILED_TO_SHOW
-CloudXEventTypes.INTERSTITIAL_CLOSED
-CloudXEventTypes.INTERSTITIAL_CLICKED
-CloudXEventTypes.INTERSTITIAL_IMPRESSION
-CloudXEventTypes.INTERSTITIAL_CLOSED_BY_USER
-CloudXEventTypes.INTERSTITIAL_REVENUE_PAID
-
-// Rewarded Events
-CloudXEventTypes.REWARDED_LOADED
-CloudXEventTypes.REWARDED_FAILED_TO_LOAD
-CloudXEventTypes.REWARDED_SHOWN
-CloudXEventTypes.REWARDED_FAILED_TO_SHOW
-CloudXEventTypes.REWARDED_CLOSED
-CloudXEventTypes.REWARDED_CLICKED
-CloudXEventTypes.REWARDED_IMPRESSION
-CloudXEventTypes.REWARDED_CLOSED_BY_USER
-CloudXEventTypes.REWARDED_REVENUE_PAID
-CloudXEventTypes.REWARD_EARNED
-CloudXEventTypes.REWARDED_VIDEO_STARTED
-CloudXEventTypes.REWARDED_VIDEO_COMPLETED
-
-// Native Events
-CloudXEventTypes.NATIVE_LOADED
-CloudXEventTypes.NATIVE_FAILED_TO_LOAD
-CloudXEventTypes.NATIVE_SHOWN
-CloudXEventTypes.NATIVE_CLICKED
-CloudXEventTypes.NATIVE_IMPRESSION
-CloudXEventTypes.NATIVE_REVENUE_PAID
-```
-
-### Using Event Emitter
+Returns `CloudXRewardedHookResult`:
+- `isLoaded: boolean` — ad is ready to show
+- `isLoading: boolean` — load in progress
+- `error: string | null` — last error message
+- `rewardEarned: boolean` — user completed the ad and earned a reward
+- `load()` — start loading
+- `show(placement?, customData?)` — show the loaded ad
+- `destroy()` — destroy and reset state
 
-```javascript
-import CloudXSDK, { CloudXEventTypes } from 'cloudx-react-native';
+### useCloudXBanner
 
-// Add listener
-const listener = CloudXSDK.addEventListener(
-  CloudXEventTypes.INTERSTITIAL_LOADED,
-  (event) => {
-    console.log('Ad loaded:', event.ad.adId);
-    console.log('Placement:', event.ad.placementName);
-  }
-);
+```typescript
+import { useCloudXBanner, CloudXBannerAd, CloudXAdPosition } from 'cloudx-react-native';
 
-// Remove specific listener
-listener.remove();
+function HomeScreen() {
+    const { isLoaded, error } = useCloudXBanner('home_banner');
 
-// Remove all listeners for an event
-CloudXSDK.removeAllListeners(CloudXEventTypes.INTERSTITIAL_LOADED);
+    useEffect(() => {
+        CloudXBannerAd.createAd('home_banner', CloudXAdPosition.BOTTOM_CENTER);
+        CloudXBannerAd.showAd('home_banner');
+        return () => CloudXBannerAd.destroyAd('home_banner');
+    }, []);
 
-// Remove all listeners
-CloudXSDK.removeAllListeners();
+    return <Text>{isLoaded ? 'Banner showing' : 'Loading banner...'}</Text>;
+}
 ```
 
-### Event Payload
+Returns `CloudXBannerHookResult`:
+- `isLoaded: boolean` — banner has loaded an ad
+- `error: string | null` — last error message
 
-All events receive a payload with the following structure:
+## Types Reference
 
-```typescript
-interface CloudXAdEvent {
-  ad?: CloudXAd;
-  error?: string;
-  timestamp: number;
-}
+### CloudXAdInfo
 
-interface CloudXAd {
-  adId: string;
-  placementName: string;
-  adType: 'banner' | 'interstitial' | 'rewarded' | 'native' | 'mrec';
-  revenue?: number;
-  currency?: string;
-  network?: string;
-  lineItemId?: string;
-}
+Received by most ad event callbacks:
+
+```typescript
+type CloudXAdInfo = {
+    adUnitId: string;
+    adFormat: string;       // "BANNER", "MREC", "INTERSTITIAL", "REWARDED"
+    networkName: string;
+    networkPlacement?: string | null;
+    placement?: string | null;
+    revenue: number;        // USD
+};
 ```
 
-### Using with React
+### CloudXAdLoadFailedInfo
 
-```jsx
-import { useEffect } from 'react';
-import CloudXSDK, { CloudXEventTypes } from 'cloudx-react-native';
+Received by `addAdLoadFailedEventListener`:
 
-function MyComponent() {
-  useEffect(() => {
-    const listener = CloudXSDK.addEventListener(
-      CloudXEventTypes.INTERSTITIAL_LOADED,
-      handleInterstitialLoaded
-    );
+```typescript
+type CloudXAdLoadFailedInfo = {
+    adUnitId: string;
+    code: CloudXErrorCode;
+    message?: string | null;
+};
+```
 
-    return () => {
-      listener.remove(); // Cleanup on unmount
-    };
-  }, []);
+### CloudXAdDisplayFailedInfo
 
-  const handleInterstitialLoaded = (event) => {
-    console.log('Interstitial ready:', event.ad);
-  };
+Received by `addAdFailedToDisplayEventListener`:
 
-  return <View>...</View>;
-}
+```typescript
+type CloudXAdDisplayFailedInfo = CloudXAdInfo & {
+    code: CloudXErrorCode;
+    message?: string | null;
+};
 ```
 
----
+### CloudXAdRewardInfo
 
-## Error Handling
+Received by `addAdReceivedRewardEventListener`:
 
-### Error Codes
-
-```javascript
-// Common error codes
-const ErrorCodes = {
-  NO_FILL: 'NO_FILL',                     // No ad available
-  TIMEOUT: 'TIMEOUT',                     // Request timed out
-  NETWORK_ERROR: 'NETWORK_ERROR',         // Network issue
-  INVALID_PLACEMENT: 'INVALID_PLACEMENT', // Placement not configured
-  SDK_NOT_INITIALIZED: 'SDK_NOT_INITIALIZED', // Must initialize first
-  AD_NOT_READY: 'AD_NOT_READY',          // Ad not loaded yet
-  AD_ALREADY_SHOWN: 'AD_ALREADY_SHOWN',  // Ad already displayed
-  INVALID_AD_ID: 'INVALID_AD_ID',        // Ad ID not found
+```typescript
+type CloudXAdRewardInfo = CloudXAdInfo & {
+    rewardLabel?: string | null;
+    rewardAmount: number;
 };
 ```
 
-### Handling Errors
-
-```javascript
-// Try-catch for async methods
-try {
-  await CloudXSDK.loadInterstitial({ adId: 'interstitial-1' });
-} catch (error) {
-  if (error.code === 'NO_FILL') {
-    console.log('No ad available, continue without ad');
-  } else if (error.code === 'NETWORK_ERROR') {
-    console.log('Network error, retry later');
-    setTimeout(() => retry(), 5000);
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
+### CloudXAdPosition
 
-// Error events
-CloudXSDK.addEventListener(
-  CloudXEventTypes.INTERSTITIAL_FAILED_TO_LOAD,
-  (event) => {
-    console.error('Failed to load ad:', event.error);
-    
-    // Handle specific errors
-    switch (event.error) {
-      case 'NO_FILL':
-        // Show alternative content
-        break;
-      case 'TIMEOUT':
-        // Retry with longer timeout
-        break;
-      default:
-        // Generic error handling
-    }
-  }
-);
-```
+Position constants for programmatic banner and MREC placement:
 
-### Best Practices
-
-```javascript
-async function showInterstitialSafely(adId: string) {
-  try {
-    // Check if SDK is initialized
-    const initialized = await CloudXSDK.isInitialized();
-    if (!initialized) {
-      throw new Error('SDK not initialized');
-    }
-
-    // Check if ad is ready
-    const isReady = await CloudXSDK.isInterstitialReady({ adId });
-    if (!isReady) {
-      console.log('Ad not ready, loading...');
-      await CloudXSDK.loadInterstitial({ adId });
-      // Wait for load event before showing
-      return;
-    }
-
-    // Show the ad
-    await CloudXSDK.showInterstitial({ adId });
-  } catch (error) {
-    console.error('Error showing interstitial:', error);
-    // Continue app flow without ad
-  }
+```typescript
+enum CloudXAdPosition {
+    TOP_LEFT, TOP_CENTER, TOP_RIGHT,
+    CENTER_LEFT, CENTERED, CENTER_RIGHT,
+    BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT,
 }
 ```
 
----
+## Advanced Features
 
-## Advanced Usage
+### Error Handling
 
-### Multiple Ad Instances
+All error callbacks receive an object with `code` and `message` properties:
 
-```javascript
-// Create multiple instances of the same placement
-await CloudXSDK.createInterstitial({
-  placement: 'level-complete',
-  adId: 'level-1-interstitial',
-});
+| 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` |
 
-await CloudXSDK.createInterstitial({
-  placement: 'level-complete',
-  adId: 'level-2-interstitial',
-});
+See `CloudXErrorCode` export for the full list of error codes.
 
-// Each instance is managed independently
-await CloudXSDK.loadInterstitial({ adId: 'level-1-interstitial' });
-await CloudXSDK.loadInterstitial({ adId: 'level-2-interstitial' });
-```
+### Revenue Tracking
 
-### Preloading Ads
-
-```javascript
-// Preload ads early for better UX
-async function preloadAds() {
-  // Preload interstitial
-  await CloudXSDK.createInterstitial({
-    placement: 'game-over',
-    adId: 'preloaded-interstitial',
-  });
-  await CloudXSDK.loadInterstitial({ adId: 'preloaded-interstitial' });
-
-  // Preload rewarded
-  await CloudXSDK.createRewarded({
-    placement: 'extra-life',
-    adId: 'preloaded-rewarded',
-  });
-  await CloudXSDK.loadRewarded({ adId: 'preloaded-rewarded' });
-}
+All ad formats provide revenue callbacks. The `CloudXAdInfo` object includes `revenue` (USD) and `networkName`:
 
-// Call during app initialization or loading screens
-useEffect(() => {
-  preloadAds();
-}, []);
+```typescript
+CloudXInterstitialAd.addAdRevenuePaidListener((adInfo) => {
+    trackRevenue(adInfo.revenue, adInfo.networkName, adInfo.adUnitId);
+});
 ```
 
-### Ad Frequency Capping
-
-```javascript
-// Implement your own frequency capping
-class AdFrequencyCapper {
-  constructor(maxAdsPerHour = 5) {
-    this.maxAdsPerHour = maxAdsPerHour;
-    this.adTimestamps = [];
-  }
-
-  canShowAd() {
-    const oneHourAgo = Date.now() - 60 * 60 * 1000;
-    this.adTimestamps = this.adTimestamps.filter(ts => ts > oneHourAgo);
-    return this.adTimestamps.length < this.maxAdsPerHour;
-  }
-
-  recordAdShown() {
-    this.adTimestamps.push(Date.now());
-  }
-}
+### User Targeting
 
-const frequencyCapper = new AdFrequencyCapper(5);
+```typescript
+import { CloudX } from 'cloudx-react-native';
 
-async function showInterstitialWithCapping(adId: string) {
-  if (!frequencyCapper.canShowAd()) {
-    console.log('Ad frequency cap reached');
-    return;
-  }
+// Set hashed user ID
+CloudX.setHashedUserID('hashed-user-id');
 
-  try {
-    await CloudXSDK.showInterstitial({ adId });
-    frequencyCapper.recordAdShown();
-  } catch (error) {
-    console.error('Failed to show ad:', error);
-  }
-}
-```
+// Set custom key-value pairs
+CloudX.setUserKeyValue('age_group', '25-34');
+CloudX.setAppKeyValue('app_version', '1.0.0');
 
-### Revenue Tracking
-
-```javascript
-// Track revenue from all ad types
-CloudXSDK.addEventListener(
-  CloudXEventTypes.INTERSTITIAL_REVENUE_PAID,
-  (event) => trackRevenue(event.ad)
-);
-
-CloudXSDK.addEventListener(
-  CloudXEventTypes.REWARDED_REVENUE_PAID,
-  (event) => trackRevenue(event.ad)
-);
-
-CloudXSDK.addEventListener(
-  CloudXEventTypes.BANNER_REVENUE_PAID,
-  (event) => trackRevenue(event.ad)
-);
-
-function trackRevenue(ad: CloudXAd) {
-  if (ad.revenue && ad.currency) {
-    // Send to analytics
-    Analytics.logRevenue({
-      amount: ad.revenue,
-      currency: ad.currency,
-      adNetwork: ad.network,
-      adType: ad.adType,
-      placement: ad.placementName,
-    });
-
-    console.log(
-      `💰 Revenue: ${ad.currency} ${ad.revenue} from ${ad.network}`
-    );
-  }
-}
+// Clear all custom key-values
+CloudX.clearAllKeyValues();
 ```
 
----
-
-## React Hooks API
-
-### useCloudXInterstitial
+### App Tracking Transparency (iOS)
 
 ```typescript
-interface UseInterstitialOptions {
-  placement: string;
-  adId: string;
-  onLoaded?: (ad: CloudXAd) => void;
-  onFailedToLoad?: (error: string) => void;
-  onShown?: (ad: CloudXAd) => void;
-  onFailedToShow?: (error: string) => void;
-  onClosed?: (ad: CloudXAd) => void;
-  onClicked?: (ad: CloudXAd) => void;
-  onImpression?: (ad: CloudXAd) => void;
-  onRevenuePaid?: (ad: CloudXAd) => void;
-  autoLoad?: boolean; // Default: false
-}
+import { requestTrackingAuthorization, getTrackingAuthorizationStatus, CloudXATTStatus } from 'cloudx-react-native';
 
-interface UseInterstitialResult {
-  isReady: boolean;
-  isLoading: boolean;
-  isShowing: boolean;
-  error: string | null;
-  load: () => Promise<void>;
-  show: () => Promise<void>;
-  destroy: () => Promise<void>;
+const status = await requestTrackingAuthorization();
+if (status === CloudXATTStatus.AUTHORIZED) {
+    console.log('Tracking authorized');
 }
-
-const interstitial = useCloudXInterstitial(options);
 ```
 
-### useCloudXRewarded
+> **Note:** Call `requestTrackingAuthorization()` before `CloudX.initialize()` for best ad targeting results.
 
-```typescript
-interface UseRewardedOptions extends UseInterstitialOptions {
-  onRewardEarned?: (ad: CloudXAd) => void;
-  onVideoStarted?: (ad: CloudXAd) => void;
-  onVideoCompleted?: (ad: CloudXAd) => void;
-}
+ATT status values: `AUTHORIZED`, `DENIED`, `RESTRICTED`, `NOT_DETERMINED`, `NOT_REQUIRED`.
 
-interface UseRewardedResult extends UseInterstitialResult {
-  // Same as interstitial
-}
+On Android or iOS < 14, `requestTrackingAuthorization()` returns `NOT_REQUIRED`.
 
-const rewarded = useCloudXRewarded(options);
-```
+### Test Mode
 
-### useCloudXBanner
+Test mode is **server-controlled** via device whitelisting:
 
-```typescript
-interface UseBannerOptions {
-  placement: string;
-  adId: string;
-  bannerSize?: BannerSize;
-  autoRefresh?: boolean;
-  refreshInterval?: number;
-  onLoaded?: (ad: CloudXAd) => void;
-  onFailedToLoad?: (error: string) => void;
-  onShown?: (ad: CloudXAd) => void;
-  onImpression?: (ad: CloudXAd) => void;
-  onClicked?: (ad: CloudXAd) => void;
-  onRevenuePaid?: (ad: CloudXAd) => void;
-}
-
-interface UseBannerResult {
-  isLoaded: boolean;
-  isVisible: boolean;
-  error: string | null;
-  render: (props?: ViewProps) => React.ReactElement;
-  show: () => Promise<void>;
-  hide: () => Promise<void>;
-  destroy: () => Promise<void>;
-}
+1. Initialize the SDK with verbose logging enabled
+2. Find your device advertising ID in the console logs
+3. Add the device to your whitelist on the CloudX dashboard
 
-const banner = useCloudXBanner(options);
-```
-
-### useCloudXNative
+### Debug Logging
 
 ```typescript
-interface UseNativeOptions {
-  placement: string;
-  adId: string;
-  onLoaded?: (ad: CloudXAd) => void;
-  onFailedToLoad?: (error: string) => void;
-  onImpression?: (ad: CloudXAd) => void;
-  onClicked?: (ad: CloudXAd) => void;
-  onRevenuePaid?: (ad: CloudXAd) => void;
-}
+import { CloudX, CloudXLogLevel } from 'cloudx-react-native';
 
-interface UseNativeResult {
-  isLoaded: boolean;
-  assets: NativeAdAssets | null;
-  error: string | null;
-  load: () => Promise<void>;
-  click: () => Promise<void>;
-  destroy: () => Promise<void>;
-}
+// Enable verbose logging (call before initialize)
+CloudX.setMinLogLevel(CloudXLogLevel.VERBOSE);
 
-const nativeAd = useCloudXNative(options);
+// Available levels: VERBOSE, DEBUG, INFO, WARN, ERROR, NONE
 ```
 
----
-
-## TypeScript Support
+### Visual Debugging
 
-The SDK is fully typed with TypeScript definitions included.
+Enable visual debugging overlays to see ad unit boundaries and network info:
 
 ```typescript
-import CloudXSDK, {
-  CloudXAd,
-  CloudXAdEvent,
-  CloudXEventTypes,
-  BannerSizes,
-  CloudXBannerView,
-  useCloudXInterstitial,
-  useCloudXRewarded,
-  useCloudXBanner,
-  useCloudXNative,
-} from 'cloudx-react-native';
-
-// All types are exported and fully documented
+CloudX.setVisualDebuggingEnabled(true);
 ```
 
----
-
 ## Platform Support
 
 | Platform | Status | Minimum Version |
 |----------|--------|-----------------|
-| iOS | ✅ Supported | iOS 14.0+ |
-| Android | 🚧 Coming Soon | API 21+ (Android 5.0+) |
+| iOS | Supported | iOS 13.0+ |
+| Android | Supported | API 23+ |
 
 ### Requirements
 
-#### iOS
-- iOS 14.0 or higher
-- CocoaPods
-- Xcode 13.0+
-
-#### Android 
-- Android API 21 (Android 5.0) or higher
-- Gradle 8.0+
-- Kotlin 1.8+
-
-#### React Native
 - React Native 0.70+
 - React 18.0+
-- TypeScript 4.5+ (optional but recommended)
+- TypeScript 4.5+ (recommended)
+- Xcode 14.0+ / CocoaPods (iOS)
+- Gradle 8.0+ / Kotlin 1.8+ (Android)
 
----
+### Native SDK Versions (2.0.0)
 
-## Troubleshooting
-
-### SDK Not Initializing
-
-```javascript
-// Make sure to await initialization with explicit testMode
-const result = await CloudXSDK.initialize({
-  appKey: 'YOUR_APP_KEY',
-  testMode: false, // Explicit for production
-});
-if (!result.success) {
-  console.error('Initialization failed:', result.message);
-}
-
-// Check iOS setup
-// 1. Verify CloudXCore pod is installed
-// 2. Run `pod install` in ios/ directory
-// 3. Check Info.plist has required permissions
-```
-
-### Ads Not Loading
-
-```javascript
-// 1. Check SDK is initialized
-const initialized = await CloudXSDK.isInitialized();
-
-// 2. Enable logging to see detailed errors
-await CloudXSDK.setLoggingEnabled(true);
-
-// 3. Check placement is configured in CloudX dashboard
+| Platform | Dependency | Version |
+|----------|-----------|---------|
+| iOS | CloudXCore | ~> 2.2.0-beta |
+| Android | io.cloudx:sdk | 2.0.0 |
 
-// 4. Verify network connectivity
-
-// 5. Check for error events
-CloudXSDK.addEventListener(
-  CloudXEventTypes.INTERSTITIAL_FAILED_TO_LOAD,
-  (event) => console.error('Load error:', event.error)
-);
-```
+## Troubleshooting
 
-### Memory Leaks
-
-```javascript
-// Always destroy ads when done
-useEffect(() => {
-  return () => {
-    CloudXSDK.destroyAd({ adId: 'my-ad' });
-  };
-}, []);
-
-// Remove event listeners
-useEffect(() => {
-  const listener = CloudXSDK.addEventListener(...);
-  return () => listener.remove();
-}, []);
-```
+### React Native 0.84.0 — TurboModuleRegistry crash
 
----
+React Native 0.84.0 has a known issue where `TurboModuleRegistry.getEnforcing(...)` fails with:
 
-## Examples
+> `TurboModuleRegistry.getEnforcing(...): 'PlatformConstants' could not be found. Verify that a module by this name is registered in the native binary.`
 
-Complete example application is available in the [example/](example/) directory.
+This is a React Native framework bug, not a CloudX SDK issue. It manifests as a red screen crash on app launch:
 
-```bash
-# Run example app
-cd example
-npm install
-cd ios && pod install && cd ..
-npm run ios
-```
+![RN 0.84.0 TurboModule crash](docs/images/rn-084-turbomodule-crash.png)
 
----
+**Workaround:** Use React Native 0.83.x or wait for the fix in a later 0.84.x patch release. The CloudX SDK is fully compatible with RN 0.70 through 0.83.
 
 ## Documentation
 
-- **[SDK Audit](SDK_AUDIT.md)**: Detailed comparison with Flutter SDK and implementation roadmap
-- **[API Reference](https://docs.cloudx.io/react-native)**: Complete API documentation
-- **[iOS Integration Guide](https://docs.cloudx.io/ios)**: CloudX iOS SDK documentation
-
----
+- **[Integration Guide](https://docs.cloudx.io/en/react-native/integration)**: Complete integration documentation
+- **[Changelog](https://docs.cloudx.io/en/react-native/changelog)**: Release history
 
 ## Support
 
-For technical support and questions:
-
-- 📧 **Email**: support@cloudx.io
-- 🐛 **Issues**: [GitHub Issues](https://github.com/cloudx-io/cloudx-react-native/issues)
-- 📚 **Docs**: [docs.cloudx.io](https://docs.cloudx.io)
+For support, contact mobile@cloudx.io
 
----
+- Email: mobile@cloudx.io
+- Issues: [GitHub Issues](https://github.com/cloudx-io/cloudx-react-native/issues)
 
 ## License
 
-This project is licensed under the Elastic License 2.0 - see the [LICENSE](LICENSE) file for details.
-
----
-
-## Changelog
-
-See [RELEASES](https://github.com/cloudx-io/cloudx-react-native/releases) for detailed changelog and version history.
+This project is licensed under the Elastic License 2.0 — see the [LICENSE](LICENSE) file for details.