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

package/ios/CloudX.mm

@@ -0,0 +1,1406 @@
+//
+//  CloudX.mm
+//  cloudx-react-native
+//
+
+#import "CloudX.h"
+#import <React/RCTUtils.h>
+
+
+@interface UIColor (CLXUtils)
++ (nullable UIColor *)clx_colorWithHexString:(NSString *)hexString;
+@end
+
+@interface CloudX()
+
+// A simple BOOL tracks initialization state. Concurrent initialize calls are serialized
+// by methodQueue (main queue), making the check-then-set atomic. The "initializing"
+// middle state is unnecessary here because
+// CloudXCore's own completion block handles any duplicate init attempts internally.
+@property (nonatomic, assign, getter=isPluginInitialized) BOOL pluginInitialized;
+
+// Fullscreen ad storage — lazily created on first load/show, keyed by ad unit ID.
+@property (nonatomic, strong) NSMutableDictionary<NSString *, CLXInterstitial *> *interstitials;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, CLXRewarded *> *rewardedAds;
+
+// Overlay banner/MREC state — each ad unit ID owns exactly one CLXBannerAdView,
+// positioned window-level via NSLayoutConstraints against the root view controller.
+@property (nonatomic, strong) NSMutableDictionary<NSString *, CLXBannerAdView *> *adViews;
+// CLXBannerType stored as NSNumber so didFailToLoadAd: can route the event to the
+// correct JS listener without a CLXAd object (that callback only receives adUnitId).
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSNumber *> *adViewAdFormats;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSString *> *adViewPositions;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSValue *> *adViewOffsets;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSArray<NSLayoutConstraint *> *> *adViewConstraints;
+@property (nonatomic, strong) NSMutableArray<NSString *> *adUnitIdentifiersToShowAfterCreate;
+// One safe-area background UIView per ad unit ID. Each banner/MREC that is positioned
+// at TOP_CENTER or BOTTOM_CENTER with a publisher background color gets its own view so
+// multiple simultaneous overlay ads don't compete for a single shared view.
+@property (nonatomic, strong) NSMutableDictionary<NSString *, UIView *> *safeAreaBackgrounds;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, UIColor *> *publisherBannerBackgroundColors;
+
+@property (nonatomic, assign) BOOL hasListeners;
+
+@end
+
+@implementation CloudX
+
+static NSString *const SDK_TAG = @"CloudXCore";
+static NSString *const TAG = @"CloudX";
+
+static NSString *const ON_BANNER_AD_LOADED_EVENT        = @"OnBannerAdLoadedEvent";
+static NSString *const ON_BANNER_AD_LOAD_FAILED_EVENT   = @"OnBannerAdLoadFailedEvent";
+static NSString *const ON_BANNER_AD_CLICKED_EVENT       = @"OnBannerAdClickedEvent";
+static NSString *const ON_BANNER_AD_COLLAPSED_EVENT     = @"OnBannerAdCollapsedEvent";
+static NSString *const ON_BANNER_AD_EXPANDED_EVENT      = @"OnBannerAdExpandedEvent";
+static NSString *const ON_BANNER_AD_REVENUE_PAID        = @"OnBannerAdRevenuePaid";
+
+static NSString *const ON_MREC_AD_LOADED_EVENT          = @"OnMRecAdLoadedEvent";
+static NSString *const ON_MREC_AD_LOAD_FAILED_EVENT     = @"OnMRecAdLoadFailedEvent";
+static NSString *const ON_MREC_AD_CLICKED_EVENT         = @"OnMRecAdClickedEvent";
+static NSString *const ON_MREC_AD_COLLAPSED_EVENT       = @"OnMRecAdCollapsedEvent";
+static NSString *const ON_MREC_AD_EXPANDED_EVENT        = @"OnMRecAdExpandedEvent";
+static NSString *const ON_MREC_AD_REVENUE_PAID          = @"OnMRecAdRevenuePaid";
+
+static NSString *const ON_INTERSTITIAL_LOADED_EVENT          = @"OnInterstitialLoadedEvent";
+static NSString *const ON_INTERSTITIAL_LOAD_FAILED_EVENT     = @"OnInterstitialLoadFailedEvent";
+static NSString *const ON_INTERSTITIAL_CLICKED_EVENT         = @"OnInterstitialClickedEvent";
+static NSString *const ON_INTERSTITIAL_DISPLAYED_EVENT       = @"OnInterstitialDisplayedEvent";
+static NSString *const ON_INTERSTITIAL_DISPLAY_FAILED_EVENT  = @"OnInterstitialDisplayFailedEvent";
+static NSString *const ON_INTERSTITIAL_HIDDEN_EVENT          = @"OnInterstitialHiddenEvent";
+static NSString *const ON_INTERSTITIAL_AD_REVENUE_PAID       = @"OnInterstitialAdRevenuePaid";
+
+static NSString *const ON_REWARDED_AD_LOADED_EVENT           = @"OnRewardedAdLoadedEvent";
+static NSString *const ON_REWARDED_AD_LOAD_FAILED_EVENT      = @"OnRewardedAdLoadFailedEvent";
+static NSString *const ON_REWARDED_AD_CLICKED_EVENT          = @"OnRewardedAdClickedEvent";
+static NSString *const ON_REWARDED_AD_DISPLAYED_EVENT        = @"OnRewardedAdDisplayedEvent";
+static NSString *const ON_REWARDED_AD_DISPLAY_FAILED_EVENT   = @"OnRewardedAdDisplayFailedEvent";
+static NSString *const ON_REWARDED_AD_HIDDEN_EVENT           = @"OnRewardedAdHiddenEvent";
+static NSString *const ON_REWARDED_AD_RECEIVED_REWARD_EVENT  = @"OnRewardedAdReceivedRewardEvent";
+static NSString *const ON_REWARDED_AD_REVENUE_PAID           = @"OnRewardedAdRevenuePaid";
+
+static NSString *const TOP_CENTER    = @"top_center";
+static NSString *const TOP_LEFT      = @"top_left";
+static NSString *const TOP_RIGHT     = @"top_right";
+static NSString *const CENTERED      = @"centered";
+static NSString *const CENTER_LEFT   = @"center_left";
+static NSString *const CENTER_RIGHT  = @"center_right";
+static NSString *const BOTTOM_LEFT   = @"bottom_left";
+static NSString *const BOTTOM_CENTER = @"bottom_center";
+static NSString *const BOTTOM_RIGHT  = @"bottom_right";
+
+static CloudX *CloudXShared;
+
+RCT_EXPORT_MODULE(CloudX)
+
++ (BOOL)requiresMainQueueSetup
+{
+    return YES;
+}
+
+- (dispatch_queue_t)methodQueue
+{
+    return dispatch_get_main_queue();
+}
+
++ (CloudX *)shared
+{
+    return CloudXShared;
+}
+
+- (instancetype)init
+{
+    self = [super init];
+    if ( self )
+    {
+        CloudXShared = self;
+
+        self.interstitials = [NSMutableDictionary dictionaryWithCapacity: 2];
+        self.rewardedAds   = [NSMutableDictionary dictionaryWithCapacity: 2];
+
+        self.adViews                         = [NSMutableDictionary dictionaryWithCapacity: 2];
+        self.adViewAdFormats                 = [NSMutableDictionary dictionaryWithCapacity: 2];
+        self.adViewPositions                 = [NSMutableDictionary dictionaryWithCapacity: 2];
+        self.adViewOffsets                   = [NSMutableDictionary dictionaryWithCapacity: 2];
+        self.adViewConstraints               = [NSMutableDictionary dictionaryWithCapacity: 2];
+        self.adUnitIdentifiersToShowAfterCreate = [NSMutableArray arrayWithCapacity: 2];
+        self.safeAreaBackgrounds              = [NSMutableDictionary dictionaryWithCapacity: 2];
+        self.publisherBannerBackgroundColors = [NSMutableDictionary dictionaryWithCapacity: 2];
+    }
+    return self;
+}
+
+#pragma mark - Initialization
+
+RCT_EXPORT_METHOD(isInitialized:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+    resolve(@([self isPluginInitialized] && [CloudXCore shared].isInitialized));
+}
+
+RCT_EXPORT_METHOD(initialize:(NSString *)pluginVersion appKey:(NSString *)appKey resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+    if ( [self isPluginInitialized] )
+    {
+        resolve(@{@"success": @(YES)});
+        return;
+    }
+
+    self.pluginInitialized = YES;
+
+    [self log: @"Initializing CloudX React Native v%@...", pluginVersion];
+
+    if ( !appKey || appKey.length == 0 )
+    {
+        reject(RCTErrorUnspecified, @"Unable to initialize CloudX SDK - no SDK key provided!", nil);
+        return;
+    }
+
+    CLXInitializationConfiguration *initConfig = [CLXInitializationConfiguration configurationWithAppKey: appKey builderBlock:^(CLXInitializationConfigurationBuilder *builder) {
+        builder.pluginVersion = [@"React-Native-" stringByAppendingString: pluginVersion];
+    }];
+
+    [[CloudXCore shared] initializeWithConfiguration: initConfig completion:^(CLXSdkConfiguration *sdkConfiguration, CLXError *error) {
+        if ( error )
+        {
+            NSString *message = error.userInfo[NSLocalizedDescriptionKey] ?: @"Unknown initialization error";
+            [self log: @"SDK initialization failed: %@", message];
+            resolve(@{@"success": @(NO), @"message": message});
+            return;
+        }
+        [self log: @"SDK initialized"];
+        resolve(@{@"success": @(YES)});
+    }];
+}
+
+#pragma mark - General Public API
+
+RCT_EXPORT_METHOD(isTablet:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+    resolve(@([UIDevice currentDevice].userInterfaceIdiom == UIUserInterfaceIdiomPad));
+}
+
+RCT_EXPORT_METHOD(getVersion:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+    resolve([CloudXCore shared].sdkVersion ?: @"");
+}
+
+RCT_EXPORT_METHOD(setMinLogLevel:(NSString *)level)
+{
+    [CloudXCore setMinLogLevel: [self logLevelFromString: level]];
+}
+
+RCT_EXPORT_METHOD(setVisualDebuggingEnabled:(BOOL)enabled)
+{
+    [CloudXCore setVisualDebuggingEnabled: enabled];
+}
+
+RCT_EXPORT_METHOD(setHashedUserID:(NSString *)hashedUserID)
+{
+    [[CloudXCore shared] setHashedUserID: hashedUserID];
+}
+
+RCT_EXPORT_METHOD(setUserKeyValue:(NSString *)key value:(NSString *)value)
+{
+    [[CloudXCore shared] setUserKeyValue: key value: value];
+}
+
+RCT_EXPORT_METHOD(setAppKeyValue:(NSString *)key value:(NSString *)value)
+{
+    [[CloudXCore shared] setAppKeyValue: key value: value];
+}
+
+RCT_EXPORT_METHOD(clearAllKeyValues)
+{
+    [[CloudXCore shared] clearAllKeyValues];
+}
+
+#pragma mark - Banners
+
+RCT_EXPORT_METHOD(createBanner:(NSString *)adUnitIdentifier position:(NSString *)bannerPosition)
+{
+    [self createAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT atPosition: bannerPosition withOffset: CGPointZero];
+}
+
+RCT_EXPORT_METHOD(createBannerWithOffsets:(NSString *)adUnitIdentifier position:(NSString *)bannerPosition xOffset:(double)xOffset yOffset:(double)yOffset)
+{
+    [self createAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT atPosition: bannerPosition withOffset: CGPointMake(xOffset, yOffset)];
+}
+
+RCT_EXPORT_METHOD(setBannerBackgroundColor:(NSString *)adUnitIdentifier hexColorString:(NSString *)hexColorString)
+{
+    [self setAdViewBackgroundColorForAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT hexColorCode: hexColorString];
+}
+
+RCT_EXPORT_METHOD(setBannerPlacement:(NSString *)adUnitIdentifier placement:(nullable NSString *)placement)
+{
+    [self setAdViewPlacement: placement forAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+RCT_EXPORT_METHOD(setBannerCustomData:(NSString *)adUnitIdentifier customData:(nullable NSString *)customData)
+{
+    [self setAdViewCustomData: customData forAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+RCT_EXPORT_METHOD(updateBannerPosition:(NSString *)adUnitIdentifier position:(NSString *)bannerPosition)
+{
+    CGPoint existingOffset = [self.adViewOffsets[adUnitIdentifier] CGPointValue];
+    [self updateAdViewPosition: bannerPosition withOffset: existingOffset forAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+RCT_EXPORT_METHOD(updateBannerOffsets:(NSString *)adUnitIdentifier xOffset:(double)xOffset yOffset:(double)yOffset)
+{
+    [self updateAdViewPosition: self.adViewPositions[adUnitIdentifier] withOffset: CGPointMake(xOffset, yOffset) forAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+RCT_EXPORT_METHOD(startBannerAutoRefresh:(NSString *)adUnitIdentifier)
+{
+    [self startAutoRefresh: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+RCT_EXPORT_METHOD(stopBannerAutoRefresh:(NSString *)adUnitIdentifier)
+{
+    [self stopAutoRefresh: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+RCT_EXPORT_METHOD(showBanner:(NSString *)adUnitIdentifier)
+{
+    [self showAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+RCT_EXPORT_METHOD(hideBanner:(NSString *)adUnitIdentifier)
+{
+    [self hideAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+RCT_EXPORT_METHOD(destroyBanner:(NSString *)adUnitIdentifier)
+{
+    [self destroyAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: DEVICE_SPECIFIC_ADVIEW_AD_FORMAT];
+}
+
+#pragma mark - MRECs
+
+RCT_EXPORT_METHOD(createMREC:(NSString *)adUnitIdentifier position:(NSString *)mrecPosition)
+{
+    [self createAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC atPosition: mrecPosition withOffset: CGPointZero];
+}
+
+RCT_EXPORT_METHOD(createMRECWithOffsets:(NSString *)adUnitIdentifier position:(NSString *)mrecPosition xOffset:(double)xOffset yOffset:(double)yOffset)
+{
+    [self createAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC atPosition: mrecPosition withOffset: CGPointMake(xOffset, yOffset)];
+}
+
+RCT_EXPORT_METHOD(setMRECPlacement:(NSString *)adUnitIdentifier placement:(nullable NSString *)placement)
+{
+    [self setAdViewPlacement: placement forAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+RCT_EXPORT_METHOD(setMRECCustomData:(NSString *)adUnitIdentifier customData:(nullable NSString *)customData)
+{
+    [self setAdViewCustomData: customData forAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+RCT_EXPORT_METHOD(updateMRECPosition:(NSString *)adUnitIdentifier position:(NSString *)mrecPosition)
+{
+    CGPoint existingOffset = [self.adViewOffsets[adUnitIdentifier] CGPointValue];
+    [self updateAdViewPosition: mrecPosition withOffset: existingOffset forAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+RCT_EXPORT_METHOD(updateMRECOffsets:(NSString *)adUnitIdentifier xOffset:(double)xOffset yOffset:(double)yOffset)
+{
+    [self updateAdViewPosition: self.adViewPositions[adUnitIdentifier] withOffset: CGPointMake(xOffset, yOffset) forAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+RCT_EXPORT_METHOD(setMRECBackgroundColor:(NSString *)adUnitIdentifier hexColorString:(NSString *)hexColorString)
+{
+    [self setAdViewBackgroundColorForAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC hexColorCode: hexColorString];
+}
+
+RCT_EXPORT_METHOD(startMRECAutoRefresh:(NSString *)adUnitIdentifier)
+{
+    [self startAutoRefresh: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+RCT_EXPORT_METHOD(stopMRECAutoRefresh:(NSString *)adUnitIdentifier)
+{
+    [self stopAutoRefresh: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+RCT_EXPORT_METHOD(showMREC:(NSString *)adUnitIdentifier)
+{
+    [self showAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+RCT_EXPORT_METHOD(hideMREC:(NSString *)adUnitIdentifier)
+{
+    [self hideAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+RCT_EXPORT_METHOD(destroyMREC:(NSString *)adUnitIdentifier)
+{
+    [self destroyAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: CLXBannerTypeMREC];
+}
+
+#pragma mark - Interstitials
+
+RCT_EXPORT_METHOD(loadInterstitial:(NSString *)adUnitIdentifier)
+{
+    [self log: @"🔴 loadInterstitial called from JS — adUnitId: %@", adUnitIdentifier];
+    CLXInterstitial *interstitial = [self retrieveInterstitialForAdUnitIdentifier: adUnitIdentifier];
+    [interstitial load];
+}
+
+RCT_EXPORT_METHOD(isInterstitialReady:(NSString *)adUnitIdentifier resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+    CLXInterstitial *interstitial = [self retrieveInterstitialForAdUnitIdentifier: adUnitIdentifier];
+    resolve(@([interstitial isReady]));
+}
+
+RCT_EXPORT_METHOD(showInterstitial:(NSString *)adUnitIdentifier placement:(nullable NSString *)placement customData:(nullable NSString *)customData)
+{
+    UIViewController *vc = [self topViewController];
+    if ( !vc )
+    {
+        [self log: @"showInterstitial: no visible view controller — emitting display failure"];
+        NSDictionary *body = @{@"adUnitId": adUnitIdentifier ?: @"",
+                               @"code":     @(-1),
+                               @"message":  @"No visible view controller to present interstitial from"};
+        [self sendReactNativeEventWithName: ON_INTERSTITIAL_DISPLAY_FAILED_EVENT body: body];
+        return;
+    }
+
+    CLXInterstitial *interstitial = [self retrieveInterstitialForAdUnitIdentifier: adUnitIdentifier];
+    [interstitial showFromViewController: vc placement: placement customData: customData];
+}
+
+RCT_EXPORT_METHOD(destroyInterstitial:(NSString *)adUnitIdentifier)
+{
+    [self log: @"Destroying interstitial with ad unit identifier \"%@\"", adUnitIdentifier];
+
+    CLXInterstitial *interstitial = self.interstitials[adUnitIdentifier];
+    if ( interstitial )
+    {
+        interstitial.delegate = nil;
+        interstitial.revenueDelegate = nil;
+        [interstitial destroy];
+        [self.interstitials removeObjectForKey: adUnitIdentifier];
+    }
+}
+
+#pragma mark - Rewarded
+
+RCT_EXPORT_METHOD(loadRewarded:(NSString *)adUnitIdentifier)
+{
+    [self log: @"🔴 loadRewarded called from JS — adUnitId: %@", adUnitIdentifier];
+    CLXRewarded *rewardedAd = [self retrieveRewardedAdForAdUnitIdentifier: adUnitIdentifier];
+    [rewardedAd load];
+}
+
+RCT_EXPORT_METHOD(isRewardedReady:(NSString *)adUnitIdentifier resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+    CLXRewarded *rewardedAd = [self retrieveRewardedAdForAdUnitIdentifier: adUnitIdentifier];
+    resolve(@([rewardedAd isReady]));
+}
+
+RCT_EXPORT_METHOD(showRewarded:(NSString *)adUnitIdentifier placement:(nullable NSString *)placement customData:(nullable NSString *)customData)
+{
+    UIViewController *vc = [self topViewController];
+    if ( !vc )
+    {
+        [self log: @"showRewarded: no visible view controller — emitting display failure"];
+        NSDictionary *body = @{@"adUnitId": adUnitIdentifier ?: @"",
+                               @"code":     @(-1),
+                               @"message":  @"No visible view controller to present rewarded ad from"};
+        [self sendReactNativeEventWithName: ON_REWARDED_AD_DISPLAY_FAILED_EVENT body: body];
+        return;
+    }
+
+    CLXRewarded *rewardedAd = [self retrieveRewardedAdForAdUnitIdentifier: adUnitIdentifier];
+    [rewardedAd showFromViewController: vc placement: placement customData: customData];
+}
+
+RCT_EXPORT_METHOD(destroyRewarded:(NSString *)adUnitIdentifier)
+{
+    [self log: @"Destroying rewarded ad with ad unit identifier \"%@\"", adUnitIdentifier];
+
+    CLXRewarded *rewardedAd = self.rewardedAds[adUnitIdentifier];
+    if ( rewardedAd )
+    {
+        rewardedAd.delegate = nil;
+        rewardedAd.revenueDelegate = nil;
+        [rewardedAd destroy];
+        [self.rewardedAds removeObjectForKey: adUnitIdentifier];
+    }
+}
+
+#pragma mark - Ad Callbacks
+
+- (void)didLoadAd:(CLXAd *)ad
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        NSString *name;
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat == CLXAdFormatBanner || adFormat == CLXAdFormatMREC )
+        {
+            CLXBannerType bannerType = ( adFormat == CLXAdFormatMREC ) ? CLXBannerTypeMREC : CLXBannerTypeW320H50;
+            CLXBannerAdView *adView = [self retrieveAdViewForAdUnitIdentifier: ad.adUnitId adFormat: bannerType];
+            adView.userInteractionEnabled = YES;
+
+            name = ( adFormat == CLXAdFormatMREC ) ? ON_MREC_AD_LOADED_EVENT : ON_BANNER_AD_LOADED_EVENT;
+            [self positionAdViewForAd: ad];
+
+            if ( adView && adView.isHidden )
+            {
+                [adView stopAutoRefresh];
+            }
+        }
+        else if ( adFormat == CLXAdFormatInterstitial )
+        {
+            name = ON_INTERSTITIAL_LOADED_EVENT;
+        }
+        else if ( adFormat == CLXAdFormatRewarded )
+        {
+            name = ON_REWARDED_AD_LOADED_EVENT;
+        }
+        else
+        {
+            [self logInvalidAdFormat: adFormat];
+            return;
+        }
+
+        [self sendReactNativeEventWithName: name body: [self adInfoForAd: ad]];
+    });
+}
+
+- (void)didFailToLoadAd:(NSString *)adUnitId error:(CLXError *)error
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( !adUnitId )
+        {
+            [self log: @"didFailToLoadAd received nil adUnitId — broadcasting to all fullscreen listeners. Error: %@", error];
+            // Nil adUnitId means the core SDK couldn't resolve the ad unit.
+            // Broadcast failure to all registered fullscreen ads so JS pendingShow state resets.
+            for ( NSString *key in self.interstitials )
+            {
+                [self sendReactNativeEventWithName: ON_INTERSTITIAL_LOAD_FAILED_EVENT
+                                              body: [self adLoadFailedInfoForAd: key withError: error]];
+            }
+            for ( NSString *key in self.rewardedAds )
+            {
+                [self sendReactNativeEventWithName: ON_REWARDED_AD_LOAD_FAILED_EVENT
+                                              body: [self adLoadFailedInfoForAd: key withError: error]];
+            }
+            return;
+        }
+
+        NSString *name;
+        if ( self.adViews[adUnitId] )
+        {
+            CLXBannerType adFormat = (CLXBannerType)[self.adViewAdFormats[adUnitId] integerValue];
+            name = ( adFormat == CLXBannerTypeMREC ) ? ON_MREC_AD_LOAD_FAILED_EVENT : ON_BANNER_AD_LOAD_FAILED_EVENT;
+        }
+        else if ( self.interstitials[adUnitId] )
+        {
+            name = ON_INTERSTITIAL_LOAD_FAILED_EVENT;
+        }
+        else if ( self.rewardedAds[adUnitId] )
+        {
+            name = ON_REWARDED_AD_LOAD_FAILED_EVENT;
+        }
+        else
+        {
+            [self log: @"didFailToLoadAd — adUnitId '%@' not found in any dictionary (keys: adViews=%@, interstitials=%@, rewardedAds=%@)",
+             adUnitId, self.adViews.allKeys, self.interstitials.allKeys, self.rewardedAds.allKeys];
+            return;
+        }
+
+        [self sendReactNativeEventWithName: name body: [self adLoadFailedInfoForAd: adUnitId withError: error]];
+    });
+}
+
+- (void)didClickAd:(CLXAd *)ad
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        NSString *name;
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat == CLXAdFormatBanner )
+        {
+            name = ON_BANNER_AD_CLICKED_EVENT;
+        }
+        else if ( adFormat == CLXAdFormatMREC )
+        {
+            name = ON_MREC_AD_CLICKED_EVENT;
+        }
+        else if ( adFormat == CLXAdFormatInterstitial )
+        {
+            name = ON_INTERSTITIAL_CLICKED_EVENT;
+        }
+        else if ( adFormat == CLXAdFormatRewarded )
+        {
+            name = ON_REWARDED_AD_CLICKED_EVENT;
+        }
+        else
+        {
+            [self logInvalidAdFormat: adFormat];
+            return;
+        }
+
+        [self sendReactNativeEventWithName: name body: [self adInfoForAd: ad]];
+    });
+}
+
+- (void)didDisplayAd:(CLXAd *)ad
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat != CLXAdFormatInterstitial && adFormat != CLXAdFormatRewarded ) return;
+
+        NSString *name;
+        if ( adFormat == CLXAdFormatInterstitial )
+        {
+            name = ON_INTERSTITIAL_DISPLAYED_EVENT;
+        }
+        else
+        {
+            name = ON_REWARDED_AD_DISPLAYED_EVENT;
+        }
+
+        [self sendReactNativeEventWithName: name body: [self adInfoForAd: ad]];
+    });
+}
+
+- (void)didFailToDisplayAd:(CLXAd *)ad error:(CLXError *)error
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat != CLXAdFormatInterstitial && adFormat != CLXAdFormatRewarded ) return;
+
+        NSString *name;
+        if ( adFormat == CLXAdFormatInterstitial )
+        {
+            name = ON_INTERSTITIAL_DISPLAY_FAILED_EVENT;
+        }
+        else
+        {
+            name = ON_REWARDED_AD_DISPLAY_FAILED_EVENT;
+        }
+
+        [self sendReactNativeEventWithName: name body: [self adDisplayFailedInfoForAd: ad withError: error]];
+    });
+}
+
+- (void)didHideAd:(CLXAd *)ad
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat != CLXAdFormatInterstitial && adFormat != CLXAdFormatRewarded ) return;
+
+        NSString *name;
+        if ( adFormat == CLXAdFormatInterstitial )
+        {
+            name = ON_INTERSTITIAL_HIDDEN_EVENT;
+        }
+        else
+        {
+            name = ON_REWARDED_AD_HIDDEN_EVENT;
+        }
+
+        [self sendReactNativeEventWithName: name body: [self adInfoForAd: ad]];
+    });
+}
+
+- (void)didExpandAd:(CLXAd *)ad
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat != CLXAdFormatBanner && adFormat != CLXAdFormatMREC )
+        {
+            [self logInvalidAdFormat: adFormat];
+            return;
+        }
+
+        [self sendReactNativeEventWithName: ( adFormat == CLXAdFormatMREC ) ? ON_MREC_AD_EXPANDED_EVENT : ON_BANNER_AD_EXPANDED_EVENT
+                                      body: [self adInfoForAd: ad]];
+    });
+}
+
+- (void)didCollapseAd:(CLXAd *)ad
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat != CLXAdFormatBanner && adFormat != CLXAdFormatMREC )
+        {
+            [self logInvalidAdFormat: adFormat];
+            return;
+        }
+
+        [self sendReactNativeEventWithName: ( adFormat == CLXAdFormatMREC ) ? ON_MREC_AD_COLLAPSED_EVENT : ON_BANNER_AD_COLLAPSED_EVENT
+                                      body: [self adInfoForAd: ad]];
+    });
+}
+
+- (void)didPayRevenueForAd:(CLXAd *)ad
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        NSString *name;
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat == CLXAdFormatBanner )
+        {
+            name = ON_BANNER_AD_REVENUE_PAID;
+        }
+        else if ( adFormat == CLXAdFormatMREC )
+        {
+            name = ON_MREC_AD_REVENUE_PAID;
+        }
+        else if ( adFormat == CLXAdFormatInterstitial )
+        {
+            name = ON_INTERSTITIAL_AD_REVENUE_PAID;
+        }
+        else if ( adFormat == CLXAdFormatRewarded )
+        {
+            name = ON_REWARDED_AD_REVENUE_PAID;
+        }
+        else
+        {
+            [self logInvalidAdFormat: adFormat];
+            return;
+        }
+
+        [self sendReactNativeEventWithName: name body: [self adInfoForAd: ad]];
+    });
+}
+
+- (void)didRewardUserForAd:(CLXAd *)ad withReward:(CLXReward *)reward
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        CLXAdFormat adFormat = ad.adFormat;
+        if ( adFormat != CLXAdFormatRewarded )
+        {
+            [self logInvalidAdFormat: adFormat];
+            return;
+        }
+
+        NSString *rewardLabel  = reward ? reward.label : @"";
+        NSInteger rewardAmount = reward ? reward.amount : 0;
+
+        NSMutableDictionary *body = [@{@"rewardLabel":  rewardLabel,
+                                       @"rewardAmount": @(rewardAmount)} mutableCopy];
+        [body addEntriesFromDictionary: [self adInfoForAd: ad]];
+
+        [self sendReactNativeEventWithName: ON_REWARDED_AD_RECEIVED_REWARD_EVENT body: body];
+    });
+}
+
+#pragma mark - Internal Methods
+
+- (void)executeOnMainQueue:(dispatch_block_t)block
+{
+    if ( [NSThread isMainThread] )
+    {
+        block();
+    }
+    else
+    {
+        dispatch_async(dispatch_get_main_queue(), block);
+    }
+}
+
+- (void)createAdViewWithAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat atPosition:(NSString *)adViewPosition withOffset:(CGPoint)offset
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Creating %ld with ad unit identifier \"%@\", position: \"%@\", and offset: %@", (long)adFormat, adUnitIdentifier, adViewPosition, NSStringFromCGPoint(offset)];
+
+        CLXBannerAdView *adView = [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat atPosition: adViewPosition withOffset: offset];
+        adView.hidden = YES;
+        self.safeAreaBackgrounds[adUnitIdentifier].hidden = YES;
+
+        self.adViewAdFormats[adUnitIdentifier] = @(adFormat);
+        [self positionAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+
+        [adView load];
+
+        // If showBanner/showMRec arrived before createBanner/createMRec finished,
+        // the identifier was queued; flush it now that the view exists.
+        if ( [self.adUnitIdentifiersToShowAfterCreate containsObject: adUnitIdentifier] )
+        {
+            [self showAdViewWithAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+            [self.adUnitIdentifiersToShowAfterCreate removeObject: adUnitIdentifier];
+        }
+    }];
+}
+
+- (void)setAdViewBackgroundColorForAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat hexColorCode:(NSString *)hexColorCode
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Setting %ld with ad unit identifier \"%@\" to color: \"%@\"", (long)adFormat, adUnitIdentifier, hexColorCode];
+
+        UIColor *convertedColor;
+        // FF000000 is opaque black, which UIColor renders identically to clearColor
+        // when composited. Nudge to FF000001 so the view is visibly black, not transparent.
+        if ( [hexColorCode containsString: @"FF000000"] )
+        {
+            convertedColor = [UIColor clx_colorWithHexString: @"FF000001"];
+        }
+        else
+        {
+            convertedColor = [UIColor clx_colorWithHexString: hexColorCode];
+        }
+
+        CLXBannerAdView *view = [self retrieveOrCreateBannerViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+        self.publisherBannerBackgroundColors[adUnitIdentifier] = convertedColor;
+        self.safeAreaBackgrounds[adUnitIdentifier].backgroundColor = view.backgroundColor = convertedColor;
+    }];
+}
+
+- (void)setAdViewPlacement:(nullable NSString *)placement forAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Setting placement \"%@\" for %ld with ad unit identifier \"%@\"", placement, (long)adFormat, adUnitIdentifier];
+
+        CLXBannerAdView *adView = [self retrieveOrCreateBannerViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+        adView.placement = placement;
+    }];
+}
+
+- (void)setAdViewCustomData:(nullable NSString *)customData forAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Setting custom data \"%@\" for %ld with ad unit identifier \"%@\"", customData, (long)adFormat, adUnitIdentifier];
+
+        CLXBannerAdView *adView = [self retrieveOrCreateBannerViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+        adView.customData = customData;
+    }];
+}
+
+- (void)updateAdViewPosition:(NSString *)adViewPosition withOffset:(CGPoint)offset forAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+        self.adViewPositions[adUnitIdentifier] = adViewPosition;
+        self.adViewOffsets[adUnitIdentifier]   = [NSValue valueWithCGPoint: offset];
+        [self positionAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+    }];
+}
+
+- (void)startAutoRefresh:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Starting auto refresh %ld with ad unit identifier \"%@\"", (long)adFormat, adUnitIdentifier];
+
+        CLXBannerAdView *view = [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+        [view startAutoRefresh];
+    }];
+}
+
+- (void)stopAutoRefresh:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Stopping auto refresh %ld with ad unit identifier \"%@\"", (long)adFormat, adUnitIdentifier];
+
+        CLXBannerAdView *view = [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+        [view stopAutoRefresh];
+    }];
+}
+
+- (void)showAdViewWithAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Showing %ld with ad unit identifier \"%@\"", (long)adFormat, adUnitIdentifier];
+
+        CLXBannerAdView *view = [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+        if ( !view )
+        {
+            [self log: @"%ld does not exist for ad unit identifier %@. Deferring show.", (long)adFormat, adUnitIdentifier];
+            [self.adUnitIdentifiersToShowAfterCreate addObject: adUnitIdentifier];
+        }
+
+        self.safeAreaBackgrounds[adUnitIdentifier].hidden = NO;
+        view.hidden = NO;
+
+        [view startAutoRefresh];
+    }];
+}
+
+- (void)hideAdViewWithAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Hiding %ld with ad unit identifier \"%@\"", (long)adFormat, adUnitIdentifier];
+        [self.adUnitIdentifiersToShowAfterCreate removeObject: adUnitIdentifier];
+
+        CLXBannerAdView *view = [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+        view.hidden = YES;
+        self.safeAreaBackgrounds[adUnitIdentifier].hidden = YES;
+
+        [view stopAutoRefresh];
+    }];
+}
+
+- (void)destroyAdViewWithAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+        [self log: @"Destroying %ld with ad unit identifier \"%@\"", (long)adFormat, adUnitIdentifier];
+
+        [self.adUnitIdentifiersToShowAfterCreate removeObject: adUnitIdentifier];
+
+        CLXBannerAdView *view = [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+        view.delegate        = nil;
+        view.revenueDelegate = nil;
+
+        NSArray<NSLayoutConstraint *> *activeConstraints = self.adViewConstraints[adUnitIdentifier];
+        [NSLayoutConstraint deactivateConstraints: activeConstraints];
+
+        [view destroy];
+        [view removeFromSuperview];
+
+        UIView *safeAreaBg = self.safeAreaBackgrounds[adUnitIdentifier];
+        [NSLayoutConstraint deactivateConstraints: safeAreaBg.constraints];
+        [safeAreaBg removeFromSuperview];
+
+        [self.adViews removeObjectForKey:              adUnitIdentifier];
+        [self.adViewPositions removeObjectForKey:      adUnitIdentifier];
+        [self.adViewOffsets removeObjectForKey:        adUnitIdentifier];
+        [self.adViewAdFormats removeObjectForKey:      adUnitIdentifier];
+        [self.adViewConstraints removeObjectForKey:              adUnitIdentifier];
+        [self.safeAreaBackgrounds removeObjectForKey:            adUnitIdentifier];
+        [self.publisherBannerBackgroundColors removeObjectForKey: adUnitIdentifier];
+    }];
+}
+
+- (CLXInterstitial *)retrieveInterstitialForAdUnitIdentifier:(NSString *)adUnitIdentifier
+{
+    CLXInterstitial *result = self.interstitials[adUnitIdentifier];
+    if ( !result )
+    {
+        result = [[CloudXCore shared] createInterstitialWithAdUnitId: adUnitIdentifier];
+        result.delegate        = self;
+        result.revenueDelegate = self;
+
+        self.interstitials[adUnitIdentifier] = result;
+    }
+
+    return result;
+}
+
+- (CLXRewarded *)retrieveRewardedAdForAdUnitIdentifier:(NSString *)adUnitIdentifier
+{
+    CLXRewarded *result = self.rewardedAds[adUnitIdentifier];
+    if ( !result )
+    {
+        result = [[CloudXCore shared] createRewardedWithAdUnitId: adUnitIdentifier];
+        result.delegate        = self;
+        result.revenueDelegate = self;
+
+        self.rewardedAds[adUnitIdentifier] = result;
+    }
+
+    return result;
+}
+
+- (nullable CLXBannerAdView *)retrieveAdViewForAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    return [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat atPosition: nil withOffset: CGPointZero];
+}
+
+- (CLXBannerAdView *)retrieveOrCreateBannerViewForAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    NSString *resolvedPosition = self.adViewPositions[adUnitIdentifier];
+    if ( !resolvedPosition || resolvedPosition.length == 0 )
+    {
+        // Use a stable default when setters run before create/show.
+        resolvedPosition = CENTERED;
+    }
+
+    NSValue *resolvedOffsetValue = self.adViewOffsets[adUnitIdentifier];
+    CGPoint resolvedOffset = resolvedOffsetValue ? [resolvedOffsetValue CGPointValue] : CGPointZero;
+
+    return [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier
+                                          adFormat: adFormat
+                                        atPosition: resolvedPosition
+                                        withOffset: resolvedOffset];
+}
+
+- (nullable CLXBannerAdView *)retrieveAdViewForAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat atPosition:(nullable NSString *)adViewPosition withOffset:(CGPoint)offset
+{
+    if ( ![NSThread isMainThread] )
+    {
+        __block CLXBannerAdView *result = nil;
+        dispatch_sync(dispatch_get_main_queue(), ^{
+            result = [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat atPosition: adViewPosition withOffset: offset];
+        });
+        return result;
+    }
+
+    CLXBannerAdView *result = self.adViews[adUnitIdentifier];
+    // Only create a new view when a position is supplied; nil position means
+    // "read-only" lookup (e.g. from delegate callbacks or setter helpers).
+    if ( !result && adViewPosition )
+    {
+        if ( adFormat == CLXBannerTypeMREC )
+        {
+            result = [[CloudXCore shared] createMRECWithAdUnitId: adUnitIdentifier];
+        }
+        else
+        {
+            result = [[CloudXCore shared] createBannerWithAdUnitId: adUnitIdentifier];
+        }
+
+        result.delegate        = self;
+        result.revenueDelegate = self;
+        result.userInteractionEnabled = NO;
+        result.translatesAutoresizingMaskIntoConstraints = NO;
+
+        self.adViews[adUnitIdentifier]        = result;
+        self.adViewPositions[adUnitIdentifier] = adViewPosition;
+        self.adViewOffsets[adUnitIdentifier]   = [NSValue valueWithCGPoint: offset];
+
+        UIView *rootView = [self topViewController].view;
+        if ( rootView )
+        {
+            [rootView addSubview: result];
+        }
+        else
+        {
+            [self log: @"retrieveAdView: no visible root view for ad unit \"%@\"", adUnitIdentifier];
+        }
+    }
+
+    return result;
+}
+
+- (void)positionAdViewForAd:(CLXAd *)ad
+{
+    [self executeOnMainQueue:^{
+        CLXBannerType bannerType = ( ad.adFormat == CLXAdFormatMREC ) ? CLXBannerTypeMREC : CLXBannerTypeW320H50;
+        [self positionAdViewForAdUnitIdentifier: ad.adUnitId adFormat: bannerType];
+    }];
+}
+
+- (void)positionAdViewForAdUnitIdentifier:(NSString *)adUnitIdentifier adFormat:(CLXBannerType)adFormat
+{
+    [self executeOnMainQueue:^{
+    CLXBannerAdView *adView     = [self retrieveAdViewForAdUnitIdentifier: adUnitIdentifier adFormat: adFormat];
+    NSString        *adViewPosition = self.adViewPositions[adUnitIdentifier];
+
+    NSValue *adViewOffsetValue = self.adViewOffsets[adUnitIdentifier];
+    CGPoint  adViewOffset      = [adViewOffsetValue CGPointValue];
+    CGFloat  xOffset           = adViewOffset.x;
+    CGFloat  yOffset           = adViewOffset.y;
+
+    if ( [adViewPosition containsString: @"right"] )
+    {
+        xOffset = -xOffset;
+    }
+
+    if ( [adViewPosition containsString: @"bottom"] )
+    {
+        yOffset = -yOffset;
+    }
+
+    UIView *superview = adView.superview;
+    if ( !superview ) return;
+
+    NSArray<NSLayoutConstraint *> *activeConstraints = self.adViewConstraints[adUnitIdentifier];
+    [NSLayoutConstraint deactivateConstraints: activeConstraints];
+
+    // Lazily create the per-ad-unit safe-area background on first position call.
+    UIView *safeAreaBg = self.safeAreaBackgrounds[adUnitIdentifier];
+    if ( !safeAreaBg )
+    {
+        safeAreaBg = [[UIView alloc] init];
+        safeAreaBg.hidden = YES;
+        safeAreaBg.backgroundColor = self.publisherBannerBackgroundColors[adUnitIdentifier] ?: UIColor.clearColor;
+        safeAreaBg.translatesAutoresizingMaskIntoConstraints = NO;
+        safeAreaBg.userInteractionEnabled = NO;
+        self.safeAreaBackgrounds[adUnitIdentifier] = safeAreaBg;
+    }
+
+    if ( ![superview.subviews containsObject: safeAreaBg] )
+    {
+        [safeAreaBg removeFromSuperview];
+        [superview insertSubview: safeAreaBg belowSubview: adView];
+    }
+
+    [NSLayoutConstraint deactivateConstraints: safeAreaBg.constraints];
+    safeAreaBg.hidden = adView.hidden;
+
+    CGFloat adViewHeight = [self adViewHeightForFormat: adFormat];
+    CGFloat adViewWidth;
+
+    if ( [adViewPosition isEqual: TOP_CENTER] || [adViewPosition isEqual: BOTTOM_CENTER] )
+    {
+        adViewWidth = CGRectGetWidth(superview.bounds);
+    }
+    else
+    {
+        adViewWidth = [self adViewWidthForFormat: adFormat];
+    }
+
+    CGSize adViewSize = CGSizeMake(adViewWidth, adViewHeight);
+
+    NSMutableArray<NSLayoutConstraint *> *constraints = [NSMutableArray arrayWithObject: [adView.heightAnchor constraintEqualToConstant: adViewSize.height]];
+
+    UILayoutGuide *layoutGuide = superview.safeAreaLayoutGuide;
+
+    // TOP_CENTER / BOTTOM_CENTER with a publisher background color and no offset:
+    // extend the safe-area background view beyond the layout guide so the color
+    // bleeds into the notch/home-indicator region and looks like a solid bar.
+    if ( [adViewPosition isEqual: TOP_CENTER] || [adViewPosition isEqual: BOTTOM_CENTER] )
+    {
+        if ( self.publisherBannerBackgroundColors[adUnitIdentifier] && adFormat != CLXBannerTypeMREC && CGPointEqualToPoint(adViewOffset, CGPointZero) )
+        {
+            [constraints addObjectsFromArray: @[[adView.widthAnchor constraintEqualToConstant: adViewWidth],
+                                                [adView.centerXAnchor constraintEqualToAnchor: layoutGuide.centerXAnchor],
+                                                [safeAreaBg.widthAnchor constraintEqualToConstant: adViewWidth],
+                                                [safeAreaBg.centerXAnchor constraintEqualToAnchor: layoutGuide.centerXAnchor]]];
+
+            if ( [adViewPosition isEqual: TOP_CENTER] )
+            {
+                [constraints addObjectsFromArray: @[[adView.topAnchor constraintEqualToAnchor: layoutGuide.topAnchor],
+                                                    [safeAreaBg.topAnchor constraintEqualToAnchor: superview.topAnchor],
+                                                    [safeAreaBg.bottomAnchor constraintEqualToAnchor: adView.topAnchor]]];
+            }
+            else
+            {
+                [constraints addObjectsFromArray: @[[adView.bottomAnchor constraintEqualToAnchor: layoutGuide.bottomAnchor],
+                                                    [safeAreaBg.topAnchor constraintEqualToAnchor: adView.bottomAnchor],
+                                                    [safeAreaBg.bottomAnchor constraintEqualToAnchor: superview.bottomAnchor]]];
+            }
+        }
+        else
+        {
+            safeAreaBg.hidden = YES;
+
+            [constraints addObjectsFromArray: @[[adView.widthAnchor constraintEqualToConstant: adViewWidth],
+                                                [adView.centerXAnchor constraintEqualToAnchor: layoutGuide.centerXAnchor]]];
+
+            if ( [adViewPosition isEqual: TOP_CENTER] )
+            {
+                [constraints addObject: [adView.topAnchor constraintEqualToAnchor: layoutGuide.topAnchor constant: yOffset]];
+            }
+            else
+            {
+                [constraints addObject: [adView.bottomAnchor constraintEqualToAnchor: layoutGuide.bottomAnchor constant: yOffset]];
+            }
+        }
+    }
+    else
+    {
+        safeAreaBg.hidden = YES;
+
+        [constraints addObject: [adView.widthAnchor constraintEqualToConstant: adViewWidth]];
+
+        if ( [adViewPosition isEqual: TOP_LEFT] )
+        {
+            [constraints addObjectsFromArray: @[[adView.topAnchor constraintEqualToAnchor: layoutGuide.topAnchor constant: yOffset],
+                                                [adView.leftAnchor constraintEqualToAnchor: superview.leftAnchor constant: xOffset]]];
+        }
+        else if ( [adViewPosition isEqual: TOP_RIGHT] )
+        {
+            [constraints addObjectsFromArray: @[[adView.topAnchor constraintEqualToAnchor: layoutGuide.topAnchor constant: yOffset],
+                                                [adView.rightAnchor constraintEqualToAnchor: superview.rightAnchor constant: xOffset]]];
+        }
+        else if ( [adViewPosition isEqual: CENTER_LEFT] )
+        {
+            [constraints addObjectsFromArray: @[[adView.centerYAnchor constraintEqualToAnchor: layoutGuide.centerYAnchor constant: yOffset],
+                                                [adView.leftAnchor constraintEqualToAnchor: superview.leftAnchor constant: xOffset]]];
+        }
+        else if ( [adViewPosition isEqual: CENTERED] )
+        {
+            [constraints addObjectsFromArray: @[[adView.centerXAnchor constraintEqualToAnchor: layoutGuide.centerXAnchor constant: xOffset],
+                                                [adView.centerYAnchor constraintEqualToAnchor: layoutGuide.centerYAnchor constant: yOffset]]];
+        }
+        else if ( [adViewPosition isEqual: CENTER_RIGHT] )
+        {
+            [constraints addObjectsFromArray: @[[adView.centerYAnchor constraintEqualToAnchor: layoutGuide.centerYAnchor constant: yOffset],
+                                                [adView.rightAnchor constraintEqualToAnchor: superview.rightAnchor constant: xOffset]]];
+        }
+        else if ( [adViewPosition isEqual: BOTTOM_LEFT] )
+        {
+            [constraints addObjectsFromArray: @[[adView.bottomAnchor constraintEqualToAnchor: layoutGuide.bottomAnchor constant: yOffset],
+                                                [adView.leftAnchor constraintEqualToAnchor: superview.leftAnchor constant: xOffset]]];
+        }
+        else if ( [adViewPosition isEqual: BOTTOM_RIGHT] )
+        {
+            [constraints addObjectsFromArray: @[[adView.bottomAnchor constraintEqualToAnchor: layoutGuide.bottomAnchor constant: yOffset],
+                                                [adView.rightAnchor constraintEqualToAnchor: superview.rightAnchor constant: xOffset]]];
+        }
+        else
+        {
+            [self log: @"Unrecognized ad view position: \"%@\", defaulting to bottom_center", adViewPosition];
+            [constraints addObjectsFromArray: @[[adView.bottomAnchor constraintEqualToAnchor: layoutGuide.bottomAnchor],
+                                                [adView.centerXAnchor constraintEqualToAnchor: layoutGuide.centerXAnchor]]];
+        }
+    }
+
+    self.adViewConstraints[adUnitIdentifier] = constraints;
+
+    [NSLayoutConstraint activateConstraints: constraints];
+    }];
+}
+
+- (CGFloat)adViewWidthForFormat:(CLXBannerType)adFormat
+{
+    if ( adFormat == CLXBannerTypeMREC ) return 300.0;
+    return ([UIDevice currentDevice].userInterfaceIdiom == UIUserInterfaceIdiomPad) ? 728.0 : 320.0;
+}
+
+- (CGFloat)adViewHeightForFormat:(CLXBannerType)adFormat
+{
+    if ( adFormat == CLXBannerTypeMREC ) return 250.0;
+    return ([UIDevice currentDevice].userInterfaceIdiom == UIUserInterfaceIdiomPad) ? 90.0 : 50.0;
+}
+
+- (UIViewController *)topViewController
+{
+    return [self deepestPresentedViewControllerFrom: [self keyWindowRootViewController]];
+}
+
+/// Scene-based key-window lookup (iOS 13+). Returns the root view controller of the
+/// foreground-active scene's key window, resolving the window at call time so callers
+/// never hold a stale reference.
+- (nullable UIViewController *)keyWindowRootViewController
+{
+    for ( UIScene *scene in UIApplication.sharedApplication.connectedScenes )
+    {
+        if ( scene.activationState != UISceneActivationStateForegroundActive ) continue;
+        if ( ![scene isKindOfClass: [UIWindowScene class]] ) continue;
+
+        UIWindowScene *windowScene = (UIWindowScene *)scene;
+        for ( UIWindow *window in windowScene.windows )
+        {
+            if ( window.isKeyWindow ) return window.rootViewController;
+        }
+    }
+    return nil;
+}
+
+/// Walks the view-controller containment hierarchy to find the deepest visible leaf.
+/// Needed because UIKit rejects `presentViewController:` calls on a VC that already
+/// has a presented child. Terminates when no deeper child exists (next becomes nil).
+- (nullable UIViewController *)deepestPresentedViewControllerFrom:(nullable UIViewController *)root
+{
+    UIViewController *vc   = nil;
+    UIViewController *next = root;
+
+    while ( next )
+    {
+        vc   = next;
+        next = vc.presentedViewController;
+
+        if ( !next && [vc isKindOfClass: [UINavigationController class]] )
+        {
+            UINavigationController *nav = (UINavigationController *)vc;
+            next = nav.topViewController;
+        }
+
+        if ( !next && [vc isKindOfClass: [UITabBarController class]] )
+        {
+            UITabBarController *tab = (UITabBarController *)vc;
+            next = tab.selectedViewController;
+        }
+    }
+
+    return vc;
+}
+
+- (CLXLogLevel)logLevelFromString:(NSString *)level
+{
+    NSString *lower = [level lowercaseString];
+    if ( [lower isEqualToString: @"verbose"] ) return CLXLogLevelVerbose;
+    if ( [lower isEqualToString: @"debug"] )   return CLXLogLevelDebug;
+    if ( [lower isEqualToString: @"info"] )    return CLXLogLevelInfo;
+    if ( [lower isEqualToString: @"warn"] )    return CLXLogLevelWarn;
+    if ( [lower isEqualToString: @"error"] )   return CLXLogLevelError;
+    if ( [lower isEqualToString: @"none"] )    return CLXLogLevelNone;
+    return CLXLogLevelInfo;
+}
+
+- (void)logInvalidAdFormat:(CLXAdFormat)adFormat
+{
+    NSLog(@"[%@] [%@] invalid ad format: %ld, from %@", SDK_TAG, TAG, (long)adFormat, [NSThread callStackSymbols]);
+}
+
+- (void)log:(NSString *)format, ...
+{
+    va_list valist;
+    va_start(valist, format);
+    NSString *message = [[NSString alloc] initWithFormat: format arguments: valist];
+    va_end(valist);
+
+    NSLog(@"[%@] [%@] %@", SDK_TAG, TAG, message);
+}
+
+#pragma mark - Ad Info
+
+- (NSDictionary<NSString *, id> *)adInfoForAd:(CLXAd *)ad
+{
+    return @{@"adUnitId":         ad.adUnitId ?: @"",
+             @"adFormat":         [self adFormatStringForAd: ad],
+             @"networkName":      ad.networkName ?: @"",
+             @"networkPlacement": ad.networkPlacement ?: @"",
+             @"placement":        ad.placement ?: @"",
+             @"revenue":          ad.revenue ?: @(0)};
+}
+
+- (NSDictionary<NSString *, id> *)adLoadFailedInfoForAd:(NSString *)adUnitIdentifier withError:(nullable CLXError *)error
+{
+    return error ?
+    @{@"adUnitId": adUnitIdentifier,
+      @"code":     @(error.code),
+      @"message":  error.localizedDescription ?: @""}
+    :
+    @{@"adUnitId": adUnitIdentifier,
+      @"code":     @(CLXErrorCodeInternalError),
+      @"message":  @""};
+}
+
+- (NSDictionary<NSString *, id> *)adDisplayFailedInfoForAd:(CLXAd *)ad withError:(CLXError *)error
+{
+    NSMutableDictionary *body = [@{@"code":    @(error.code),
+                                   @"message": error.localizedDescription ?: @""} mutableCopy];
+    [body addEntriesFromDictionary: [self adInfoForAd: ad]];
+    return body;
+}
+
+- (NSString *)adFormatStringForAd:(CLXAd *)ad
+{
+    switch ( ad.adFormat )
+    {
+        case CLXAdFormatBanner:       return @"BANNER";
+        case CLXAdFormatMREC:         return @"MREC";
+        case CLXAdFormatInterstitial: return @"INTERSTITIAL";
+        case CLXAdFormatRewarded:     return @"REWARDED";
+        default:                      return @"";
+    }
+}
+
+#pragma mark - React Native Event Bridge
+
+- (void)sendReactNativeEventWithName:(NSString *)name body:(NSDictionary<NSString *, id> *)body
+{
+    [self sendEventWithName: name body: body];
+}
+
+- (NSArray<NSString *> *)supportedEvents
+{
+    return @[ON_MREC_AD_LOADED_EVENT,
+             ON_MREC_AD_LOAD_FAILED_EVENT,
+             ON_MREC_AD_CLICKED_EVENT,
+             ON_MREC_AD_COLLAPSED_EVENT,
+             ON_MREC_AD_EXPANDED_EVENT,
+             ON_MREC_AD_REVENUE_PAID,
+
+             ON_BANNER_AD_LOADED_EVENT,
+             ON_BANNER_AD_LOAD_FAILED_EVENT,
+             ON_BANNER_AD_CLICKED_EVENT,
+             ON_BANNER_AD_COLLAPSED_EVENT,
+             ON_BANNER_AD_EXPANDED_EVENT,
+             ON_BANNER_AD_REVENUE_PAID,
+
+             ON_INTERSTITIAL_LOADED_EVENT,
+             ON_INTERSTITIAL_LOAD_FAILED_EVENT,
+             ON_INTERSTITIAL_CLICKED_EVENT,
+             ON_INTERSTITIAL_DISPLAYED_EVENT,
+             ON_INTERSTITIAL_DISPLAY_FAILED_EVENT,
+             ON_INTERSTITIAL_HIDDEN_EVENT,
+             ON_INTERSTITIAL_AD_REVENUE_PAID,
+
+             ON_REWARDED_AD_LOADED_EVENT,
+             ON_REWARDED_AD_LOAD_FAILED_EVENT,
+             ON_REWARDED_AD_CLICKED_EVENT,
+             ON_REWARDED_AD_DISPLAYED_EVENT,
+             ON_REWARDED_AD_DISPLAY_FAILED_EVENT,
+             ON_REWARDED_AD_HIDDEN_EVENT,
+             ON_REWARDED_AD_RECEIVED_REWARD_EVENT,
+             ON_REWARDED_AD_REVENUE_PAID];
+}
+
+- (NSDictionary *)constantsToExport
+{
+    return @{@"ON_MREC_AD_LOADED_EVENT":        ON_MREC_AD_LOADED_EVENT,
+             @"ON_MREC_AD_LOAD_FAILED_EVENT":   ON_MREC_AD_LOAD_FAILED_EVENT,
+             @"ON_MREC_AD_CLICKED_EVENT":        ON_MREC_AD_CLICKED_EVENT,
+             @"ON_MREC_AD_COLLAPSED_EVENT":      ON_MREC_AD_COLLAPSED_EVENT,
+             @"ON_MREC_AD_EXPANDED_EVENT":       ON_MREC_AD_EXPANDED_EVENT,
+             @"ON_MREC_AD_REVENUE_PAID":         ON_MREC_AD_REVENUE_PAID,
+
+             @"ON_BANNER_AD_LOADED_EVENT":       ON_BANNER_AD_LOADED_EVENT,
+             @"ON_BANNER_AD_LOAD_FAILED_EVENT":  ON_BANNER_AD_LOAD_FAILED_EVENT,
+             @"ON_BANNER_AD_CLICKED_EVENT":       ON_BANNER_AD_CLICKED_EVENT,
+             @"ON_BANNER_AD_COLLAPSED_EVENT":     ON_BANNER_AD_COLLAPSED_EVENT,
+             @"ON_BANNER_AD_EXPANDED_EVENT":      ON_BANNER_AD_EXPANDED_EVENT,
+             @"ON_BANNER_AD_REVENUE_PAID":        ON_BANNER_AD_REVENUE_PAID,
+
+             @"ON_INTERSTITIAL_LOADED_EVENT":         ON_INTERSTITIAL_LOADED_EVENT,
+             @"ON_INTERSTITIAL_LOAD_FAILED_EVENT":    ON_INTERSTITIAL_LOAD_FAILED_EVENT,
+             @"ON_INTERSTITIAL_CLICKED_EVENT":         ON_INTERSTITIAL_CLICKED_EVENT,
+             @"ON_INTERSTITIAL_DISPLAYED_EVENT":       ON_INTERSTITIAL_DISPLAYED_EVENT,
+             @"ON_INTERSTITIAL_DISPLAY_FAILED_EVENT":  ON_INTERSTITIAL_DISPLAY_FAILED_EVENT,
+             @"ON_INTERSTITIAL_HIDDEN_EVENT":          ON_INTERSTITIAL_HIDDEN_EVENT,
+             @"ON_INTERSTITIAL_AD_REVENUE_PAID":       ON_INTERSTITIAL_AD_REVENUE_PAID,
+
+             @"ON_REWARDED_AD_LOADED_EVENT":          ON_REWARDED_AD_LOADED_EVENT,
+             @"ON_REWARDED_AD_LOAD_FAILED_EVENT":     ON_REWARDED_AD_LOAD_FAILED_EVENT,
+             @"ON_REWARDED_AD_CLICKED_EVENT":          ON_REWARDED_AD_CLICKED_EVENT,
+             @"ON_REWARDED_AD_DISPLAYED_EVENT":        ON_REWARDED_AD_DISPLAYED_EVENT,
+             @"ON_REWARDED_AD_DISPLAY_FAILED_EVENT":   ON_REWARDED_AD_DISPLAY_FAILED_EVENT,
+             @"ON_REWARDED_AD_HIDDEN_EVENT":           ON_REWARDED_AD_HIDDEN_EVENT,
+             @"ON_REWARDED_AD_RECEIVED_REWARD_EVENT":  ON_REWARDED_AD_RECEIVED_REWARD_EVENT,
+             @"ON_REWARDED_AD_REVENUE_PAID":           ON_REWARDED_AD_REVENUE_PAID,
+
+             @"TOP_CENTER_POSITION":    TOP_CENTER,
+             @"TOP_LEFT_POSITION":      TOP_LEFT,
+             @"TOP_RIGHT_POSITION":     TOP_RIGHT,
+             @"CENTERED_POSITION":      CENTERED,
+             @"CENTER_LEFT_POSITION":   CENTER_LEFT,
+             @"CENTER_RIGHT_POSITION":  CENTER_RIGHT,
+             @"BOTTOM_LEFT_POSITION":   BOTTOM_LEFT,
+             @"BOTTOM_CENTER_POSITION": BOTTOM_CENTER,
+             @"BOTTOM_RIGHT_POSITION":  BOTTOM_RIGHT};
+}
+
+- (NSDictionary *)getConstants
+{
+    return [self constantsToExport];
+}
+
+- (void)startObserving
+{
+    self.hasListeners = YES;
+}
+
+- (void)stopObserving
+{
+    self.hasListeners = NO;
+}
+
+#ifdef RCT_NEW_ARCH_ENABLED
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:(const facebook::react::ObjCTurboModule::InitParams &)params
+{
+    return std::make_shared<facebook::react::NativeCloudXSpecJSI>(params);
+}
+#endif
+
+@end
+
+@implementation UIColor (CLXUtils)
+
+// Parses 6-digit (#RRGGBB) and 8-digit (#AARRGGBB) hex color strings into UIColor.
+// The AARRGGBB byte order matches Android's Color.parseColor convention, keeping
+// the cross-platform API surface consistent for JS callers.
++ (nullable UIColor *)clx_colorWithHexString:(NSString *)hexString
+{
+    NSString *hex = [hexString stringByReplacingOccurrencesOfString: @"#" withString: @""];
+    if ( hex.length == 6 ) hex = [@"FF" stringByAppendingString: hex];
+    if ( hex.length != 8 ) return nil;
+
+    unsigned int argb = 0;
+    [[NSScanner scannerWithString: hex] scanHexInt: &argb];
+
+    CGFloat alpha = ((argb >> 24) & 0xFF) / 255.0;
+    CGFloat red   = ((argb >> 16) & 0xFF) / 255.0;
+    CGFloat green = ((argb >> 8)  & 0xFF) / 255.0;
+    CGFloat blue  =  (argb        & 0xFF) / 255.0;
+
+    return [UIColor colorWithRed: red green: green blue: blue alpha: alpha];
+}
+
+@end