cloudx-react-native 3.10.0 → 3.11.0

package/ios/CloudXNativeAdView.mm

@@ -0,0 +1,979 @@
+//
+//  CloudXNativeAdView.mm
+//  cloudx-react-native
+//
+
+#import "CloudXNativeAdView.h"
+#import "CloudX.h"
+#import <React/RCTLog.h>
+// Supplies `UIView.reactTag`, which Paper uses instead of `UIView.tag`.
+#import <React/UIView+React.h>
+
+#ifdef RCT_NEW_ARCH_ENABLED
+#import <react/renderer/components/CloudXSpec/ComponentDescriptors.h>
+#import <react/renderer/components/CloudXSpec/EventEmitters.h>
+#import <react/renderer/components/CloudXSpec/Props.h>
+#import <react/renderer/components/CloudXSpec/RCTComponentViewHelpers.h>
+#import <React/RCTConversions.h>
+#import "RCTFabricComponentsPlugins.h"
+
+using namespace facebook::react;
+
+/*
+ * Fills a generated NativeAdInfo-style event struct from the NSDictionary the
+ * ad delegate builds. onAdLoaded/onAdClicked/onAdExpired/onAdClosed/
+ * onAdRevenuePaid all share this field set (see EventEmitters.h), so this
+ * macro keeps the five emitter blocks in sync.
+ */
+#define CLX_FILL_NATIVE_ADINFO(result, event) \
+    result.adUnitId         = std::string([(event[@"adUnitId"] ?: @"") UTF8String]); \
+    result.adFormat         = std::string([(event[@"adFormat"] ?: @"") UTF8String]); \
+    result.networkName      = std::string([(event[@"networkName"] ?: @"") UTF8String]); \
+    result.networkPlacement = std::string([(event[@"networkPlacement"] ?: @"") UTF8String]); \
+    result.placement        = std::string([(event[@"placement"] ?: @"") UTF8String]); \
+    result.creativeId       = std::string([(event[@"creativeId"] ?: @"") UTF8String]); \
+    result.revenue          = [event[@"revenue"] doubleValue]; \
+    result.adValuesJson     = std::string([(event[@"adValuesJson"] ?: @"") UTF8String]); \
+    result.nativeAdJson     = std::string([(event[@"nativeAdJson"] ?: @"") UTF8String]);
+
+static id CLXNativeIdFromFollyDynamic(const folly::dynamic &dynamicValue)
+{
+    switch ( dynamicValue.type() )
+    {
+        case folly::dynamic::NULLT:
+            return [NSNull null];
+        case folly::dynamic::BOOL:
+            return @(dynamicValue.getBool());
+        case folly::dynamic::INT64:
+            return @(dynamicValue.getInt());
+        case folly::dynamic::DOUBLE:
+            return @(dynamicValue.getDouble());
+        case folly::dynamic::STRING:
+            return [[NSString alloc] initWithBytes: dynamicValue.c_str() length: dynamicValue.size() encoding: NSUTF8StringEncoding] ?: @"";
+        case folly::dynamic::ARRAY: {
+            NSMutableArray *array = [NSMutableArray arrayWithCapacity: dynamicValue.size()];
+            for ( const auto &item : dynamicValue )
+            {
+                [array addObject: CLXNativeIdFromFollyDynamic(item) ?: [NSNull null]];
+            }
+            return [array copy];
+        }
+        case folly::dynamic::OBJECT: {
+            NSMutableDictionary<NSString *, id> *dictionary = [NSMutableDictionary dictionaryWithCapacity: dynamicValue.size()];
+            for ( const auto &item : dynamicValue.items() )
+            {
+                id key = CLXNativeIdFromFollyDynamic(item.first);
+                if ( ![key isKindOfClass: [NSString class]] ) continue;
+                dictionary[key] = CLXNativeIdFromFollyDynamic(item.second) ?: [NSNull null];
+            }
+            return [dictionary copy];
+        }
+    }
+
+    return [NSNull null];
+}
+
+// CloudXNativeAdViewProps declares extraParameters and localExtraParameters as
+// two distinct generated struct types with an identical {key, value} shape;
+// share one conversion instead of writing it out twice.
+template <typename StructT>
+static NSArray<NSDictionary<NSString *, id> *> *CLXEntryArrayFromNativeAdViewStructs(const std::vector<StructT> &entries)
+{
+    NSMutableArray<NSDictionary<NSString *, id> *> *result = [NSMutableArray arrayWithCapacity: entries.size()];
+    for ( const auto &entry : entries )
+    {
+        NSString *key = [NSString stringWithUTF8String: entry.key.c_str()] ?: @"";
+        id value = CLXNativeIdFromFollyDynamic(entry.value) ?: [NSNull null];
+        [result addObject: @{@"key": key, @"value": value}];
+    }
+    return [result copy];
+}
+
+@interface CloudXNativeAdView () <RCTCloudXNativeAdViewViewProtocol>
+#else
+@interface CloudXNativeAdView ()
+#endif
+
+@property (nonatomic, copy) NSArray<NSDictionary<NSString *, id> *> *extraParameterEntries;
+@property (nonatomic, copy) NSArray<NSDictionary<NSString *, id> *> *localExtraParameterEntries;
+
+/// Per-host loader. Created lazily when @c adUnitId is known so each mounted
+/// component has its own load pipeline and delegate routing — sharing one
+/// loader across concurrently-mounted hosts for the same ad unit would cause
+/// delegate reassignment (callbacks delivered to whichever host attached
+/// most recently) and duplicate-load rejection (hosts beyond the first never
+/// load).
+@property (nonatomic, strong, nullable) CLXNativeAdLoader *nativeAdLoader;
+
+/// Bumped whenever in-flight work for this host becomes invalid — a destroyAd
+/// or a live re-target. Delegate callbacks read it at entry, before their hop
+/// to the main queue, and drop themselves if it has moved since. Without this
+/// an auction already in flight when the host was destroyed still rendered a
+/// view and fired onAdLoaded. Atomic because callbacks may arrive on any
+/// thread while the main thread advances it.
+@property (atomic, assign) NSUInteger loadGeneration;
+
+/// Currently-rendered template view. Nil when the JS layer is driving a
+/// manual render.
+@property (nonatomic, strong, nullable) CLXNativeAdView *currentNativeView;
+
+/// The CLXAd backing @c currentNativeView . Tracked separately so a template
+/// reload can destroy the ad being replaced even when @c pendingManualAd has
+/// already been overwritten. Nil in manual mode.
+@property (nonatomic, strong, nullable) CLXAd *currentTemplateAd;
+
+/// The most recently loaded ad. Held so @c renderNativeAd can wire up click
+/// tracking after the JS layer finishes binding asset views.
+@property (nonatomic, strong, nullable) CLXAd *pendingManualAd;
+
+/// Publisher-supplied clickable subviews, collected by @c updateAssetView .
+@property (nonatomic, strong) NSMutableArray<UIView *> *clickableViews;
+/// Tap path for container-clickable adapters in manual mode. See
+/// -clx_updateContainerClickRecognizerForAd:.
+@property (nonatomic, strong, nullable) UITapGestureRecognizer *containerClickRecognizer;
+
+/// Maps asset role name to the publisher-supplied UIView. Used so a re-bind
+/// of the same role replaces the prior entry without leaving stale
+/// references in @c clickableViews .
+@property (nonatomic, strong) NSMutableDictionary<NSString *, UIView *> *assetViewsByRole;
+
+/// SDK-inserted media/options subviews added into the publisher's asset
+/// containers during manual binding. Tracked so a reload or destroy can pull
+/// them back out; without this, successive reloads stack multiple
+/// mediaView/optionsView instances inside the same container.
+@property (nonatomic, strong) NSMutableArray<UIView *> *insertedSDKSubviews;
+
+@property (nonatomic, assign) BOOL hasRequestedLoad;
+
+@end
+
+@implementation CloudXNativeAdView
+
+- (void)commonInit
+{
+    _extraParameterEntries = @[];
+    _localExtraParameterEntries = @[];
+    _clickableViews = [NSMutableArray array];
+    _assetViewsByRole = [NSMutableDictionary dictionary];
+    _insertedSDKSubviews = [NSMutableArray array];
+}
+
+#ifdef RCT_NEW_ARCH_ENABLED
+
++ (ComponentDescriptorProvider)componentDescriptorProvider
+{
+    return concreteComponentDescriptorProvider<CloudXNativeAdViewComponentDescriptor>();
+}
+
+- (instancetype)initWithFrame:(CGRect)frame
+{
+    self = [super initWithFrame: frame];
+    if ( self )
+    {
+        [self commonInit];
+        static const auto defaultProps = std::make_shared<const CloudXNativeAdViewProps>();
+        _props = defaultProps;
+        [self setupEventHandlers];
+    }
+    return self;
+}
+
+/*
+ * On Fabric the RCTDirectEventBlock properties are not wired by a view manager,
+ * so point each block at the generated C++ EventEmitter. The delegate callbacks
+ * below always call self.onXxxEvent(dict) regardless of architecture.
+ */
+- (void)setupEventHandlers
+{
+    __weak CloudXNativeAdView *weakSelf = self;
+
+    self.onAdLoadedEvent = ^(NSDictionary *event) {
+        CloudXNativeAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXNativeAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXNativeAdViewEventEmitter::OnAdLoadedEvent result;
+        CLX_FILL_NATIVE_ADINFO(result, event);
+        emitter->onAdLoadedEvent(result);
+    };
+
+    self.onAdClickedEvent = ^(NSDictionary *event) {
+        CloudXNativeAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXNativeAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXNativeAdViewEventEmitter::OnAdClickedEvent result;
+        CLX_FILL_NATIVE_ADINFO(result, event);
+        emitter->onAdClickedEvent(result);
+    };
+
+    self.onAdExpiredEvent = ^(NSDictionary *event) {
+        CloudXNativeAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXNativeAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXNativeAdViewEventEmitter::OnAdExpiredEvent result;
+        CLX_FILL_NATIVE_ADINFO(result, event);
+        emitter->onAdExpiredEvent(result);
+    };
+
+    self.onAdClosedEvent = ^(NSDictionary *event) {
+        CloudXNativeAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXNativeAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXNativeAdViewEventEmitter::OnAdClosedEvent result;
+        CLX_FILL_NATIVE_ADINFO(result, event);
+        emitter->onAdClosedEvent(result);
+    };
+
+    self.onAdRevenuePaidEvent = ^(NSDictionary *event) {
+        CloudXNativeAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXNativeAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXNativeAdViewEventEmitter::OnAdRevenuePaidEvent result;
+        CLX_FILL_NATIVE_ADINFO(result, event);
+        emitter->onAdRevenuePaidEvent(result);
+    };
+
+    self.onAdLoadFailedEvent = ^(NSDictionary *event) {
+        CloudXNativeAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXNativeAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXNativeAdViewEventEmitter::OnAdLoadFailedEvent result;
+        result.adUnitId = std::string([(event[@"adUnitId"] ?: @"") UTF8String]);
+        result.code     = [event[@"code"] doubleValue];
+        result.message  = std::string([(event[@"message"] ?: @"") UTF8String]);
+        emitter->onAdLoadFailedEvent(result);
+    };
+
+    self.onAdDisplayFailedEvent = ^(NSDictionary *event) {
+        CloudXNativeAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXNativeAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXNativeAdViewEventEmitter::OnAdDisplayFailedEvent result;
+        result.adUnitId = std::string([(event[@"adUnitId"] ?: @"") UTF8String]);
+        result.code     = [event[@"code"] doubleValue];
+        result.message  = std::string([(event[@"message"] ?: @"") UTF8String]);
+        emitter->onAdDisplayFailedEvent(result);
+    };
+}
+
+- (void)updateProps:(Props::Shared const &)props oldProps:(Props::Shared const &)oldProps
+{
+    const auto &oldViewProps = *std::static_pointer_cast<CloudXNativeAdViewProps const>(_props);
+    const auto &newViewProps = *std::static_pointer_cast<CloudXNativeAdViewProps const>(props);
+
+    if ( oldViewProps.adUnitId != newViewProps.adUnitId )
+    {
+        self.adUnitId = RCTNSStringFromString(newViewProps.adUnitId);
+    }
+    if ( oldViewProps.templateName != newViewProps.templateName )
+    {
+        self.templateName = RCTNSStringFromStringNilIfEmpty(newViewProps.templateName);
+    }
+    if ( oldViewProps.placement != newViewProps.placement )
+    {
+        self.placement = RCTNSStringFromStringNilIfEmpty(newViewProps.placement);
+    }
+    if ( oldViewProps.customData != newViewProps.customData )
+    {
+        self.customData = RCTNSStringFromStringNilIfEmpty(newViewProps.customData);
+    }
+    if ( oldViewProps.disableVideoFullScreen != newViewProps.disableVideoFullScreen )
+    {
+        self.disableVideoFullScreen = newViewProps.disableVideoFullScreen;
+    }
+    if ( oldViewProps.startVideoUnmuted != newViewProps.startVideoUnmuted )
+    {
+        self.startVideoUnmuted = newViewProps.startVideoUnmuted;
+    }
+    if ( oldViewProps.hideVideoMediaControls != newViewProps.hideVideoMediaControls )
+    {
+        self.hideVideoMediaControls = newViewProps.hideVideoMediaControls;
+    }
+    if ( oldViewProps.manualRender != newViewProps.manualRender )
+    {
+        self.manualRender = newViewProps.manualRender;
+    }
+
+    /*
+     * CloudXNativeAdViewExtraParametersStruct/LocalExtraParametersStruct
+     * contain folly::dynamic, so the generated props do not support a simple
+     * old/new equality guard like the scalar props above (see CloudXAdView's
+     * identical rationale). Applying is idempotent — values are only read
+     * again at the next loadAd.
+     */
+    [self setExtraParametersFromEntryArray: CLXEntryArrayFromNativeAdViewStructs(newViewProps.extraParameters)];
+    [self setLocalExtraParametersFromEntryArray: CLXEntryArrayFromNativeAdViewStructs(newViewProps.localExtraParameters)];
+
+    [super updateProps: props oldProps: oldProps];
+}
+
+- (void)handleCommand:(const NSString *)commandName args:(const NSArray *)args
+{
+    RCTCloudXNativeAdViewHandleCommand(self, commandName, args);
+}
+
+- (void)prepareForRecycle
+{
+    [super prepareForRecycle];
+
+    static const auto defaultProps = std::make_shared<const CloudXNativeAdViewProps>();
+    _props = defaultProps;
+
+    // Unlike CloudXAdView (whose SDK-owned ad view is created and destroyed
+    // together with each mount), this host's CLXNativeAdLoader is a
+    // persistent, stateful per-instance object. A recycled Fabric view must
+    // never leak the prior mount's ad/loader state into the next mount.
+    // destroyAd detaches the delegates, destroys the loader and nils it.
+    [self destroyAd];
+
+    self.adUnitId = nil;
+    self.templateName = nil;
+    self.placement = nil;
+    self.customData = nil;
+    self.disableVideoFullScreen = NO;
+    self.startVideoUnmuted = NO;
+    self.hideVideoMediaControls = NO;
+    self.manualRender = NO;
+    self.extraParameterEntries = @[];
+    self.localExtraParameterEntries = @[];
+    self.hasRequestedLoad = NO;
+}
+
+#else
+
+- (instancetype)init
+{
+    self = [super init];
+    if ( self )
+    {
+        [self commonInit];
+    }
+    return self;
+}
+
+#endif // RCT_NEW_ARCH_ENABLED
+
+#pragma mark - Property setters (shared; Paper view manager sets these via KVC)
+
+- (void)setAdUnitId:(NSString *)adUnitId
+{
+    NSString *normalized = [adUnitId copy];
+    if ( [normalized isEqual: _adUnitId] ) return;
+
+    // First-time set (no loader yet): just store the value. didMoveToWindow /
+    // loadIfNeeded loads once the view is attached.
+    if ( !self.nativeAdLoader )
+    {
+        _adUnitId = normalized;
+        return;
+    }
+
+    // Live re-target — parity with Android's setAdUnitId. destroyAd detaches
+    // and destroys the loader bound to the previous ad unit, so its in-flight
+    // auction cannot keep rendering into this host, and it clears
+    // hasRequestedLoad so the new unit is allowed to load.
+    [self destroyAd];
+
+    _adUnitId = normalized;
+
+    if ( !self.window ) return;
+
+    // The sibling props — placement, customData, the video flags and the extra
+    // parameters — are applied AFTER adUnitId in the same update pass (Fabric
+    // updateProps: in declaration order; Paper via KVC in the view manager's
+    // order). Loading synchronously here therefore configured the loader from
+    // the PREVIOUS unit's values. Deferring to the end of this main-thread
+    // turn makes the load independent of prop ordering on both architectures.
+    NSUInteger generation = self.loadGeneration;
+    __weak __typeof(self) weakSelf = self;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        __typeof(self) strongSelf = weakSelf;
+        if ( !strongSelf || generation != strongSelf.loadGeneration ) return;
+        [strongSelf loadIfNeeded];
+    });
+}
+
+- (void)setExtraParametersFromEntryArray:(nullable NSArray<NSDictionary<NSString *, id> *> *)extraParameters
+{
+    self.extraParameterEntries = extraParameters ?: @[];
+}
+
+- (void)setLocalExtraParametersFromEntryArray:(nullable NSArray<NSDictionary<NSString *, id> *> *)localExtraParameters
+{
+    self.localExtraParameterEntries = localExtraParameters ?: @[];
+}
+
+#pragma mark - Ad view lifecycle
+
+- (void)didMoveToWindow
+{
+    [super didMoveToWindow];
+    // RN sets all view properties before the view is inserted into the
+    // hierarchy, so manualRender is settled by the time this callback fires.
+    // Auto-load runs in both render modes; the mode only controls how
+    // didLoadNativeAd:forAd: presents the result.
+    if ( self.window ) [self loadIfNeeded];
+}
+
+- (CLXNativeAdLoader *)resolveLoader
+{
+    if ( self.adUnitId.length == 0 ) return nil;
+
+    if ( !self.nativeAdLoader )
+    {
+        // A dedicated loader per host so concurrent mounts for the same ad
+        // unit do not collide on delegate registration or loadAd gating.
+        self.nativeAdLoader = [[CloudXCore shared] createNativeAdLoaderWithAdUnitIdentifier: self.adUnitId];
+        self.nativeAdLoader.nativeAdDelegate = self;
+        self.nativeAdLoader.revenueDelegate  = self;
+    }
+
+    return self.nativeAdLoader;
+}
+
+- (void)loadIfNeeded
+{
+    if ( self.hasRequestedLoad || self.adUnitId.length == 0 ) return;
+
+    CLXNativeAdLoader *loader = [self resolveLoader];
+    if ( !loader ) return;
+
+    loader.placement              = self.placement;
+    loader.customData             = self.customData;
+    loader.disableVideoFullScreen = self.disableVideoFullScreen;
+    loader.startVideoUnmuted      = self.startVideoUnmuted;
+    loader.hideVideoMediaControls = self.hideVideoMediaControls;
+
+    [self applyExtraParametersToLoader: loader];
+
+    self.hasRequestedLoad = YES;
+    [loader loadAd];
+}
+
+- (void)applyExtraParametersToLoader:(CLXNativeAdLoader *)loader
+{
+    // JS null crosses the bridge as NSNull; normalize to nil so the loader
+    // never receives NSNull.
+    //
+    // extraParameters are bid-level auction signals (setExtraParameter:value:);
+    // localExtraParameters are adapter-only and never sent in the bid request
+    // (setLocalExtraParameterForKey:value:) — see CLXNativeAdLoader.h.
+    for ( NSDictionary *entry in self.extraParameterEntries )
+    {
+        NSString *key = [entry[@"key"] isKindOfClass: [NSString class]] ? entry[@"key"] : nil;
+        if ( key.length == 0 ) continue;
+        id value = entry[@"value"];
+        if ( value == [NSNull null] ) value = nil;
+        [loader setExtraParameter: key value: value];
+    }
+
+    for ( NSDictionary *entry in self.localExtraParameterEntries )
+    {
+        NSString *key = [entry[@"key"] isKindOfClass: [NSString class]] ? entry[@"key"] : nil;
+        if ( key.length == 0 ) continue;
+        id value = entry[@"value"];
+        if ( value == [NSNull null] ) value = nil;
+        [loader setLocalExtraParameterForKey: key value: value];
+    }
+}
+
+#pragma mark - Commands
+//
+// Method names match RCTCloudXNativeAdViewViewProtocol exactly, so Fabric's
+// generated command dispatch calls these directly (see handleCommand:args:
+// above) and the Old Architecture manager's UIManager-block handlers
+// (CloudXNativeAdViewManager.mm) call the identical selectors.
+
+- (void)loadAd
+{
+    // Explicit JS-driven (re)load bypasses the "already requested" guard used
+    // by the didMoveToWindow auto-load.
+    self.hasRequestedLoad = NO;
+    [self loadIfNeeded];
+}
+
+/// Depth-first search for a descendant carrying `reactTag`.
+///
+/// The two renderers store the React tag differently: Fabric mirrors it into
+/// `UIView.tag`, while Paper keeps it only in the `reactTag` associated object.
+/// Checking both is what makes asset binding work on either architecture.
+static UIView *clx_findDescendantWithReactTag(UIView *root, NSInteger reactTag)
+{
+    if ( root.tag == reactTag ) return root;
+    NSNumber *paperTag = root.reactTag;
+    if ( paperTag != nil && paperTag.integerValue == reactTag ) return root;
+
+    for ( UIView *subview in root.subviews )
+    {
+        UIView *found = clx_findDescendantWithReactTag(subview, reactTag);
+        if ( found ) return found;
+    }
+    return nil;
+}
+
+- (nullable UIView *)clx_descendantWithReactTag:(NSInteger)reactTag
+{
+    if ( reactTag == 0 ) return nil;
+    return clx_findDescendantWithReactTag(self, reactTag);
+}
+
+- (void)updateAssetView:(NSInteger)assetViewTag assetName:(NSString *)assetName
+{
+    if ( assetName.length == 0 ) return;
+
+    // Post-destroy / pre-load calls must be observable no-ops: without an ad
+    // there is no nativeAd to populate from, and dereferencing it would
+    // crash or silently bind against a stale ad.
+    if ( !self.pendingManualAd )
+    {
+        [[CloudX shared] log: @"updateAssetView ignored — no loaded ad (post-destroy or pre-load). role=%@", assetName];
+        return;
+    }
+
+    // Descendant lookup, not RCTUIManager/bridge-based resolution: Fabric has
+    // no bridge.uiManager, so this must work by walking this host's own view
+    // hierarchy on both architectures. `viewWithTag:` alone is not enough —
+    // Paper keeps the React tag in the `reactTag` associated object and never
+    // in `UIView.tag`, so it resolves nothing there.
+    UIView *view = [self clx_descendantWithReactTag: assetViewTag];
+    if ( !view ) return;
+
+    // If a prior binding for this role exists, drop the old reference from
+    // clickableViews so only the current view is registered for clicks.
+    UIView *prior = self.assetViewsByRole[assetName];
+    if ( prior ) [self.clickableViews removeObjectIdenticalTo: prior];
+
+    self.assetViewsByRole[assetName] = view;
+
+    CLXNativeAd *nativeAd = self.pendingManualAd.nativeAd;
+
+    // Deliberately no `view.tag = CLXNativeAdViewTag*` here. Those constants are
+    // only read off a CLXNativeAdView container, which manual mode never uses,
+    // so stamping them bought nothing — and it overwrote the React tag, so a
+    // re-bind of the same mounted layout resolved nothing and the next ad got
+    // no media, no options view and an empty clickable list.
+    if ( [assetName isEqualToString: @"TitleView"] )
+    {
+        if ( nativeAd.title.length > 0 ) [self.clickableViews addObject: view];
+    }
+    else if ( [assetName isEqualToString: @"AdvertiserView"] )
+    {
+        if ( nativeAd.advertiser.length > 0 ) [self.clickableViews addObject: view];
+    }
+    else if ( [assetName isEqualToString: @"BodyView"] )
+    {
+        if ( nativeAd.body.length > 0 ) [self.clickableViews addObject: view];
+    }
+    else if ( [assetName isEqualToString: @"CallToActionView"] )
+    {
+        if ( nativeAd.callToAction.length > 0 ) [self.clickableViews addObject: view];
+    }
+    else if ( [assetName isEqualToString: @"IconView"] )
+    {
+        [self.clickableViews addObject: view];
+    }
+    else if ( [assetName isEqualToString: @"OptionsView"] )
+    {
+        // Adapter-provided options view is hosted as a subview of the
+        // publisher's container so click-through + ad-choices behavior
+        // stays under the SDK's control.
+        if ( nativeAd.optionsView )
+        {
+            nativeAd.optionsView.frame = view.bounds;
+            nativeAd.optionsView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+            [view addSubview: nativeAd.optionsView];
+            [self.insertedSDKSubviews addObject: nativeAd.optionsView];
+        }
+    }
+    else if ( [assetName isEqualToString: @"MediaView"] )
+    {
+        if ( nativeAd.mediaView )
+        {
+            nativeAd.mediaView.frame = view.bounds;
+            nativeAd.mediaView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+            [view addSubview: nativeAd.mediaView];
+            [self.insertedSDKSubviews addObject: nativeAd.mediaView];
+        }
+        [self.clickableViews addObject: view];
+    }
+    else if ( [assetName isEqualToString: @"StarRatingView"] )
+    {
+        // Not clickable; the rating is decorative.
+    }
+}
+
+- (void)renderNativeAd
+{
+    CLXAd *ad = self.pendingManualAd;
+    if ( !ad || !ad.nativeAd )
+    {
+        CLXError *error = [CLXError errorWithCode: CLXErrorCodeAdapterInternalError
+                                       description: @"renderNativeAd called before ad loaded"];
+        if ( self.onAdDisplayFailedEvent ) self.onAdDisplayFailedEvent([self loadFailedDictForAdUnit: self.adUnitId ?: @"" error: error]);
+        return;
+    }
+    if ( ad.nativeAd.isExpired )
+    {
+        CLXError *error = [CLXError errorWithCode: CLXErrorCodeAdapterAdExpired
+                                       description: @"renderNativeAd: ad expired"];
+        if ( self.onAdDisplayFailedEvent ) self.onAdDisplayFailedEvent([self loadFailedDictForAdUnit: ad.adUnitId ?: @"" error: error]);
+        return;
+    }
+
+    // Publisher drove the render — a lingering template view from a prior
+    // load would sit beneath their subviews. Remove it so only the manual
+    // hierarchy is visible.
+    if ( self.currentNativeView )
+    {
+        [self.currentNativeView removeFromSuperview];
+        self.currentNativeView = nil;
+    }
+
+    NSArray<UIView *> *clickables = [self.clickableViews copy];
+    UIView *container = self;
+
+    void (^prepareBlock)(void) = ^{
+        BOOL registered = [ad.nativeAd prepareForInteractionClickableViews: clickables withContainer: container];
+        if ( registered )
+        {
+            [self clx_updateContainerClickRecognizerForAd: ad];
+            return;
+        }
+
+        // A load that cannot register click/impression tracking is a display
+        // failure: the ad renders but never produces revenue. onAdLoadedEvent
+        // has already fired by the time renderNativeAd is invoked, so
+        // surface the failure here to make it observable (mirrors Android).
+        [[CloudX shared] log: @"Native ad failed to register click/impression tracking — emitting onAdDisplayFailedEvent. adUnitId=%@", ad.adUnitId ?: @""];
+        CLXError *error = [CLXError errorWithCode: CLXErrorCodeAdapterInternalError
+                                       description: @"Native ad failed to register click/impression tracking"];
+        if ( self.onAdDisplayFailedEvent ) self.onAdDisplayFailedEvent([self loadFailedDictForAdUnit: ad.adUnitId ?: @"" error: error]);
+    };
+
+    // Interaction registration touches UIKit; always marshal to the main queue.
+    if ( ![NSThread isMainThread] )
+    {
+        dispatch_async(dispatch_get_main_queue(), prepareBlock);
+    }
+    else
+    {
+        prepareBlock();
+    }
+}
+
+/// Installs or removes the container tap path for the current ad.
+///
+/// Adapters that report `isContainerClickable` do not use the per-asset
+/// clickable views: they expect a tap anywhere on the container to be routed
+/// through `performClick`. The SDK's own native ad view installs that gesture
+/// when it renders, but manual mode registers the publisher's container
+/// instead and never goes through that path — so those ads rendered and could
+/// never register a click. Installing it here restores the click path without
+/// disturbing adapters that track the asset views themselves.
+- (void)clx_updateContainerClickRecognizerForAd:(CLXAd *)ad
+{
+    if ( self.containerClickRecognizer )
+    {
+        [self removeGestureRecognizer: self.containerClickRecognizer];
+        self.containerClickRecognizer = nil;
+    }
+
+    if ( ![ad.nativeAd isContainerClickable] ) return;
+
+    UITapGestureRecognizer *tap =
+        [[UITapGestureRecognizer alloc] initWithTarget: self action: @selector(clx_handleContainerTap:)];
+    // The publisher's own controls stay interactive; this only observes taps.
+    tap.cancelsTouchesInView = NO;
+    self.containerClickRecognizer = tap;
+    [self addGestureRecognizer: tap];
+}
+
+- (void)clx_handleContainerTap:(UITapGestureRecognizer *)recognizer
+{
+    CLXNativeAd *nativeAd = self.pendingManualAd.nativeAd;
+    if ( !nativeAd || nativeAd.isExpired ) return;
+    [nativeAd performClick];
+}
+
+- (void)destroyAd
+{
+    // Invalidate first: a load already in flight belongs to the generation
+    // being torn down, and its callback must not render into this host.
+    self.loadGeneration++;
+
+    CLXAd *pendingAd  = self.pendingManualAd;
+    CLXAd *templateAd = self.currentTemplateAd;
+
+    // Deliberately NOT resolveLoader — that lazily creates a loader, so a
+    // destroy with nothing loaded used to construct the very pipeline it was
+    // asked to tear down.
+    CLXNativeAdLoader *loader = self.nativeAdLoader;
+    if ( loader )
+    {
+        // Detach before destroying so the SDK cannot deliver a pending load
+        // into a host that has already been cleared.
+        loader.nativeAdDelegate = nil;
+        loader.revenueDelegate  = nil;
+
+        if ( pendingAd ) [loader destroyAd: pendingAd];
+        if ( templateAd && templateAd != pendingAd ) [loader destroyAd: templateAd];
+        [loader destroy];
+
+        self.nativeAdLoader = nil;
+    }
+    self.pendingManualAd   = nil;
+    self.currentTemplateAd = nil;
+
+    [self.currentNativeView removeFromSuperview];
+    self.currentNativeView = nil;
+
+    [self removeSDKInsertedSubviews];
+    [self.clickableViews removeAllObjects];
+    [self.assetViewsByRole removeAllObjects];
+
+    // The container tap path belongs to the ad being torn down; leaving it
+    // attached would route taps to a destroyed ad.
+    if ( self.containerClickRecognizer )
+    {
+        [self removeGestureRecognizer: self.containerClickRecognizer];
+        self.containerClickRecognizer = nil;
+    }
+
+    self.hasRequestedLoad = NO;
+}
+
+- (void)removeSDKInsertedSubviews
+{
+    for ( UIView *subview in self.insertedSDKSubviews )
+    {
+        [subview removeFromSuperview];
+    }
+    [self.insertedSDKSubviews removeAllObjects];
+}
+
+- (void)dealloc
+{
+    // The loader is owned by this host. Destroying it releases the SDK-side
+    // ad pipeline and cancels any in-flight auction so nothing calls back
+    // into the zombie delegate. Keep strong local references across the
+    // async hop — the block intentionally does not capture self. Capture the
+    // loaded ad(s) too so every ad this host loaded is destroyed before the
+    // loader itself goes away; otherwise the SDK-side ad leaks.
+    CLXNativeAdLoader *loader = _nativeAdLoader;
+    CLXAd *pendingAd  = _pendingManualAd;
+    CLXAd *templateAd = _currentTemplateAd;
+    if ( !loader ) return;
+
+    loader.nativeAdDelegate = nil;
+    loader.revenueDelegate = nil;
+
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( pendingAd ) [loader destroyAd: pendingAd];
+        if ( templateAd && templateAd != pendingAd ) [loader destroyAd: templateAd];
+        [loader destroy];
+    });
+}
+
+#pragma mark - Event payloads
+
+- (NSDictionary<NSString *, id> *)adInfoDictForAd:(CLXAd *)ad
+{
+    NSString *adValuesJson = @"";
+    if ( ad.adValues )
+    {
+        NSData *data = [NSJSONSerialization dataWithJSONObject: ad.adValues options: 0 error: nil];
+        if ( data )
+        {
+            adValuesJson = [[NSString alloc] initWithData: data encoding: NSUTF8StringEncoding] ?: @"";
+        }
+    }
+
+    NSString *nativeAdJson = @"";
+    if ( ad.nativeAd )
+    {
+        NSDictionary<NSString *, id> *metadata = [[CloudX shared] nativeAdMetadataForAd: ad];
+        NSData *data = [NSJSONSerialization dataWithJSONObject: metadata options: 0 error: nil];
+        if ( data )
+        {
+            nativeAdJson = [[NSString alloc] initWithData: data encoding: NSUTF8StringEncoding] ?: @"";
+        }
+    }
+
+    return @{@"adUnitId":         ad.adUnitId ?: @"",
+             @"adFormat":         @"NATIVE",
+             @"networkName":      ad.networkName ?: @"",
+             @"networkPlacement": ad.networkPlacement ?: @"",
+             @"placement":        ad.placement ?: @"",
+             @"creativeId":       ad.creativeIdentifier ?: @"",
+             @"revenue":          ad.revenue ?: @(0),
+             @"adValuesJson":     adValuesJson,
+             @"nativeAdJson":     nativeAdJson};
+}
+
+- (NSDictionary<NSString *, id> *)loadFailedDictForAdUnit:(NSString *)adUnitId error:(nullable CLXError *)error
+{
+    return @{@"adUnitId": adUnitId ?: (self.adUnitId ?: @""),
+             @"code":     error ? @(error.code) : @(CLXErrorCodeInternalError),
+             @"message":  error.localizedDescription ?: @""};
+}
+
+#pragma mark - CLXNativeAdDelegate
+
+- (void)didLoadNativeAd:(nullable CLXNativeAdView *)nativeAdView forAd:(CLXAd *)ad
+{
+    // Snapshot the generation before the hop; see loadGeneration.
+    NSUInteger generation = self.loadGeneration;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( generation != self.loadGeneration ) return;
+
+        // Capture the ads being replaced before overwriting them; every
+        // loaded ad must be destroyed or it leaks.
+        CLXAd *prevPending  = self.pendingManualAd;
+        CLXAd *prevTemplate = self.currentTemplateAd;
+        // The generation guard above means this host was not torn down, so the
+        // loader that produced this callback is still the current one. Reading
+        // it directly avoids resolveLoader lazily building a replacement.
+        CLXNativeAdLoader *loader = self.nativeAdLoader;
+
+        self.pendingManualAd = ad;
+        [self.clickableViews removeAllObjects];
+        [self.assetViewsByRole removeAllObjects];
+        [self removeSDKInsertedSubviews];
+
+        // Drop the previous ad's container tap path along with its other
+        // bindings: the replacement ad may not be container-clickable. It is
+        // reinstalled by the next successful interaction registration.
+        if ( self.containerClickRecognizer )
+        {
+            [self removeGestureRecognizer: self.containerClickRecognizer];
+            self.containerClickRecognizer = nil;
+        }
+
+        // Destroy the ad(s) being replaced. Guard against destroying the
+        // freshly-loaded ad and against double-destroying the same object
+        // (pending and template can reference the same CLXAd in template mode).
+        if ( prevPending && prevPending != ad && loader ) [loader destroyAd: prevPending];
+        if ( prevTemplate && prevTemplate != ad && prevTemplate != prevPending && loader ) [loader destroyAd: prevTemplate];
+
+        if ( !self.manualRender )
+        {
+            // Template mode: render the server-provided view or build one
+            // from the publisher-selected template. renderNativeAdView:
+            // wires up impression and click tracking on the template's
+            // typed outlets.
+            CLXNativeAdView *view = nativeAdView;
+            BOOL rendered = YES;
+            if ( !view )
+            {
+                NSString *name = self.templateName.length > 0 ? self.templateName : @"medium_template";
+                view = [CLXNativeAdView viewFromAd: ad.nativeAd withTemplate: name];
+                rendered = loader ? [loader renderNativeAdView: view withAd: ad] : NO;
+            }
+
+            if ( !rendered )
+            {
+                // Template render failed — the ad is expired or invalid. Do
+                // not add the view, do not fire onAdLoadedEvent; surface the
+                // failure so it is observable.
+                [self.currentNativeView removeFromSuperview];
+                self.currentNativeView = nil;
+                self.currentTemplateAd = nil;
+                [[CloudX shared] log: @"Native template render failed (ad expired or invalid) — emitting onAdLoadFailedEvent. adUnitId=%@", ad.adUnitId ?: @""];
+                CLXError *error = [CLXError errorWithCode: CLXErrorCodeAdapterAdExpired
+                                               description: @"template render failed; ad expired or invalid"];
+                if ( self.onAdLoadFailedEvent ) self.onAdLoadFailedEvent([self loadFailedDictForAdUnit: ad.adUnitId ?: @"" error: error]);
+                return;
+            }
+
+            [self.currentNativeView removeFromSuperview];
+            self.currentNativeView = view;
+            self.currentTemplateAd = ad;
+
+            view.translatesAutoresizingMaskIntoConstraints = NO;
+            [self addSubview: view];
+            [NSLayoutConstraint activateConstraints: @[
+                [view.topAnchor     constraintEqualToAnchor: self.topAnchor],
+                [view.bottomAnchor  constraintEqualToAnchor: self.bottomAnchor],
+                [view.leadingAnchor constraintEqualToAnchor: self.leadingAnchor],
+                [view.trailingAnchor constraintEqualToAnchor: self.trailingAnchor],
+            ]];
+        }
+        else
+        {
+            // Manual mode: the publisher's children drive the visual layout. We
+            // hold pendingManualAd so the subsequent updateAssetView +
+            // renderNativeAd commands can populate text, attach media /
+            // options views, and register click + impression tracking against
+            // the publisher's subviews.
+            self.currentTemplateAd = nil;
+        }
+
+        if ( self.onAdLoadedEvent ) self.onAdLoadedEvent([self adInfoDictForAd: ad]);
+    });
+}
+
+- (void)didFailToLoadNativeAdForAdUnitIdentifier:(NSString *)adUnitId error:(CLXError *)error
+{
+    // Snapshot the generation before the hop; see loadGeneration.
+    NSUInteger generation = self.loadGeneration;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( generation != self.loadGeneration ) return;
+        self.hasRequestedLoad = NO;
+        // The template-render failure path logs; this one did not, so a load
+        // failure reached JS while leaving no trace in the device log.
+        [[CloudX shared] log: @"Native ad load failed. adUnitId=%@ code=%ld message=%@",
+                              adUnitId ?: @"", (long)(error ? error.code : CLXErrorCodeInternalError),
+                              error.localizedDescription ?: @""];
+        if ( self.onAdLoadFailedEvent ) self.onAdLoadFailedEvent([self loadFailedDictForAdUnit: adUnitId error: error]);
+    });
+}
+
+- (void)didClickNativeAd:(CLXAd *)ad
+{
+    // Snapshot the generation before the hop; see loadGeneration.
+    NSUInteger generation = self.loadGeneration;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( generation != self.loadGeneration ) return;
+        if ( self.onAdClickedEvent ) self.onAdClickedEvent([self adInfoDictForAd: ad]);
+    });
+}
+
+- (void)didExpireNativeAd:(CLXAd *)ad
+{
+    // Snapshot the generation before the hop; see loadGeneration.
+    NSUInteger generation = self.loadGeneration;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( generation != self.loadGeneration ) return;
+        if ( self.onAdExpiredEvent ) self.onAdExpiredEvent([self adInfoDictForAd: ad]);
+    });
+}
+
+- (void)didCloseNativeAd:(CLXAd *)ad
+{
+    // Snapshot the generation before the hop; see loadGeneration.
+    NSUInteger generation = self.loadGeneration;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( generation != self.loadGeneration ) return;
+        if ( self.onAdClosedEvent ) self.onAdClosedEvent([self adInfoDictForAd: ad]);
+    });
+}
+
+#pragma mark - CLXAdRevenueDelegate
+
+- (void)didPayRevenueForAd:(CLXAd *)ad
+{
+    // Snapshot the generation before the hop; see loadGeneration.
+    NSUInteger generation = self.loadGeneration;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( generation != self.loadGeneration ) return;
+        if ( self.onAdRevenuePaidEvent ) self.onAdRevenuePaidEvent([self adInfoDictForAd: ad]);
+    });
+}
+
+@end
+
+#ifdef RCT_NEW_ARCH_ENABLED
+Class<RCTComponentViewProtocol> CloudXNativeAdViewCls(void)
+{
+    return [CloudXNativeAdView class];
+}
+#endif