cloudx-react-native 3.10.1 → 3.11.1

package/android/src/test/java/com/cloudxreactnative/CloudXNativeAdPreloadTest.kt

@@ -0,0 +1,351 @@
+package com.cloudxreactnative
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.WritableMap
+import io.cloudx.sdk.CloudX
+import io.cloudx.sdk.CloudXAd
+import io.cloudx.sdk.CloudXAdFormat
+import io.cloudx.sdk.CloudXNativeAdLoader
+import io.mockk.every
+import io.mockk.mockk
+import io.mockk.mockkStatic
+import io.mockk.unmockkAll
+import io.mockk.verify
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.test.UnconfinedTestDispatcher
+import kotlinx.coroutines.test.resetMain
+import kotlinx.coroutines.test.setMain
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+
+@OptIn(ExperimentalCoroutinesApi::class)
+class CloudXNativeAdPreloadTest {
+
+    @Before
+    fun setUp() {
+        Dispatchers.setMain(UnconfinedTestDispatcher())
+        mockkStatic(CloudX::class)
+        mockkStatic(Arguments::class)
+        every { Arguments.createMap() } answers { mockk<WritableMap>(relaxed = true) }
+    }
+
+    @After
+    fun tearDown() {
+        unmockkAll()
+        Dispatchers.resetMain()
+    }
+
+    private fun mockAd(unitId: String = "unit-1"): CloudXAd {
+        val ad = mockk<CloudXAd>(relaxed = true)
+        val format = mockk<CloudXAdFormat>(relaxed = true)
+        every { format.name } returns "NATIVE"
+        every { ad.adUnitId } returns unitId
+        every { ad.adFormat } returns format
+        every { ad.networkName } returns "test-network"
+        every { ad.revenue } returns 0.05
+        every { ad.adValues } returns emptyMap()
+        every { ad.nativeAd } returns null
+        return ad
+    }
+
+    @Test
+    fun `loadNativeAd registers holder and getHolder retrieves it`() {
+        val context = mockk<ReactApplicationContext>(relaxed = true)
+        every { context.runOnUiQueueThread(any()) } answers { firstArg<Runnable>().run() }
+        val module = CloudXModuleImpl(context)
+
+        every { CloudX.isInitialized() } returns true
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val listenerSlot = io.mockk.slot<io.cloudx.sdk.CloudXNativeAdListener>()
+        every { loader.nativeAdListener = capture(listenerSlot) } returns Unit
+        every { CloudX.createNativeAdLoader(any(), any()) } returns loader
+
+        val promise = mockk<Promise>(relaxed = true)
+        val options = FakeReadableMap(emptyMap())
+
+        module.loadNativeAd("ad-unit-1", options, promise)
+
+        verify(exactly = 1) { loader.loadAd() }
+
+        val holder = listenerSlot.captured as CloudXNativeAdHolder
+        assertEquals("ad-unit-1", holder.adUnitId)
+        val nativeAdId = holder.nativeAdId
+        assertNotNull(nativeAdId)
+
+        val foundHolder = module.getHolder(nativeAdId)
+        assertSame(holder, foundHolder)
+
+        // Simulate successful ad load
+        val ad = mockAd("ad-unit-1")
+        holder.onNativeAdLoaded(null, ad)
+
+        verify(exactly = 1) { promise.resolve(any()) }
+    }
+
+    @Test
+    fun `destroy is idempotent and releases loader and ad`() {
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val ad = mockAd()
+        val onEvent = mockk<(String, WritableMap) -> Unit>(relaxed = true)
+
+        val holder = CloudXNativeAdHolder(
+            nativeAdId = "test-id",
+            adUnitId = "unit-1",
+            loader = loader,
+            onEvent = onEvent
+        )
+        holder.ad = ad
+
+        assertFalse(holder.isDestroyed)
+
+        // First destroy
+        holder.destroy()
+
+        assertTrue(holder.isDestroyed)
+        assertNull(holder.ad)
+        verify(exactly = 1) { loader.destroy(ad) }
+        verify(exactly = 1) { loader.destroy() }
+        verify(exactly = 1) { loader.nativeAdListener = null }
+        verify(exactly = 1) { loader.revenueListener = null }
+
+        // Second destroy (idempotent)
+        holder.destroy()
+
+        verify(exactly = 1) { loader.destroy(ad) }
+        verify(exactly = 1) { loader.destroy() }
+    }
+
+    @Test
+    fun `destroy while bound notifies bound view`() {
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val view = mockk<CloudXNativeAdView>(relaxed = true)
+        val onEvent = mockk<(String, WritableMap) -> Unit>(relaxed = true)
+
+        val holder = CloudXNativeAdHolder(
+            nativeAdId = "test-id",
+            adUnitId = "unit-1",
+            loader = loader,
+            onEvent = onEvent
+        )
+        holder.bindView(view)
+        assertSame(view, holder.boundView?.get())
+
+        holder.destroy()
+
+        verify(exactly = 1) { view.onBoundNativeAdDestroyed() }
+        assertNull(holder.boundView)
+    }
+
+    @Test
+    fun `latest-bind-wins clears previous view without event`() {
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val view1 = mockk<CloudXNativeAdView>(relaxed = true)
+        val view2 = mockk<CloudXNativeAdView>(relaxed = true)
+        val onEvent = mockk<(String, WritableMap) -> Unit>(relaxed = true)
+
+        val holder = CloudXNativeAdHolder(
+            nativeAdId = "test-id",
+            adUnitId = "unit-1",
+            loader = loader,
+            onEvent = onEvent
+        )
+
+        // Bind first view
+        holder.bindView(view1)
+        assertSame(view1, holder.boundView?.get())
+        verify(exactly = 0) { view1.clearRenderedAd() }
+
+        // Bind second view (latest wins)
+        holder.bindView(view2)
+        assertSame(view2, holder.boundView?.get())
+        verify(exactly = 1) { view1.clearRenderedAd() }
+        verify(exactly = 0) { view2.clearRenderedAd() }
+    }
+
+    @Test
+    fun `expiry before the impression emits expired once, clears the bound view and retains tombstone`() {
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val ad = mockAd("unit-1")
+        val view = mockk<CloudXNativeAdView>(relaxed = true)
+        val events = mutableListOf<String>()
+
+        val holder = CloudXNativeAdHolder(
+            nativeAdId = "test-id",
+            adUnitId = "unit-1",
+            loader = loader,
+            onEvent = { eventName, _ -> events.add(eventName) }
+        )
+        holder.ad = ad
+        // Rendered into a view but never seen: no impression yet.
+        holder.bindView(view)
+        assertFalse(holder.impressed)
+
+        // First expiry
+        holder.onNativeAdExpired(ad)
+
+        assertTrue(holder.expired)
+        assertNull(holder.ad)
+        assertNull(holder.boundView)
+        verify(exactly = 1) { view.onBoundNativeAdExpired() }
+        verify(exactly = 1) { loader.destroy(ad) }
+        assertEquals(listOf(CloudXAdEvents.ON_NATIVE_AD_EXPIRED_EVENT), events)
+
+        // Second expiry: should not emit again
+        holder.onNativeAdExpired(ad)
+
+        assertEquals(1, events.size)
+    }
+
+    @Test
+    fun `expiry after the impression is ignored`() {
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val ad = mockAd("unit-1")
+        val events = mutableListOf<String>()
+
+        val holder = CloudXNativeAdHolder(
+            nativeAdId = "test-id",
+            adUnitId = "unit-1",
+            loader = loader,
+            onEvent = { eventName, _ -> events.add(eventName) }
+        )
+        holder.ad = ad
+        // CloudX reports an impression with its revenue.
+        holder.onAdRevenuePaid(ad)
+        assertTrue(holder.impressed)
+
+        holder.onNativeAdExpired(ad)
+
+        assertTrue(holder.expired)
+        // Ad must NOT be destroyed or nulled out because it has been seen
+        assertSame(ad, holder.ad)
+        verify(exactly = 0) { loader.destroy(any<CloudXAd>()) }
+        assertEquals(listOf(CloudXAdEvents.ON_NATIVE_AD_REVENUE_PAID), events)
+    }
+
+    @Test
+    fun `an Activity going away keeps preloaded ads, invalidate releases them`() {
+        val context = mockk<ReactApplicationContext>(relaxed = true)
+        every { context.runOnUiQueueThread(any()) } answers { firstArg<Runnable>().run() }
+        val module = CloudXModuleImpl(context)
+
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val slot = io.mockk.slot<io.cloudx.sdk.CloudXNativeAdListener>()
+        every { loader.nativeAdListener = capture(slot) } returns Unit
+        every { CloudX.isInitialized() } returns true
+        every { CloudX.createNativeAdLoader(any(), any()) } returns loader
+
+        module.loadNativeAd("unit-1", FakeReadableMap(emptyMap()), mockk<Promise>(relaxed = true))
+        val holder = slot.captured as CloudXNativeAdHolder
+
+        // A configuration change, or leaving the app and coming back: the
+        // Activity is destroyed while JS, and the handle, live on.
+        module.onHostDestroy()
+
+        assertFalse(holder.isDestroyed)
+        assertSame(holder, module.getHolder(holder.nativeAdId))
+        verify(exactly = 0) { loader.destroy() }
+
+        module.invalidate()
+
+        assertTrue(holder.isDestroyed)
+        assertNull(module.getHolder(holder.nativeAdId))
+        verify(exactly = 1) { loader.destroy() }
+    }
+
+    @Test
+    fun `module invalidate destroys all registered holders`() {
+        val context = mockk<ReactApplicationContext>(relaxed = true)
+        every { context.runOnUiQueueThread(any()) } answers { firstArg<Runnable>().run() }
+        val module = CloudXModuleImpl(context)
+
+        val loader1 = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val loader2 = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val slot1 = io.mockk.slot<io.cloudx.sdk.CloudXNativeAdListener>()
+        val slot2 = io.mockk.slot<io.cloudx.sdk.CloudXNativeAdListener>()
+        every { loader1.nativeAdListener = capture(slot1) } returns Unit
+        every { loader2.nativeAdListener = capture(slot2) } returns Unit
+        every { CloudX.isInitialized() } returns true
+        every { CloudX.createNativeAdLoader(any(), any()) } returnsMany listOf(loader1, loader2)
+
+        val promise1 = mockk<Promise>(relaxed = true)
+        val promise2 = mockk<Promise>(relaxed = true)
+        val options = FakeReadableMap(emptyMap())
+
+        module.loadNativeAd("unit-1", options, promise1)
+        module.loadNativeAd("unit-2", options, promise2)
+
+        val holder1 = slot1.captured as CloudXNativeAdHolder
+        val holder2 = slot2.captured as CloudXNativeAdHolder
+
+        assertNotNull(module.getHolder(holder1.nativeAdId))
+        assertNotNull(module.getHolder(holder2.nativeAdId))
+
+        // Invalidate
+        module.invalidate()
+
+        assertTrue(holder1.isDestroyed)
+        assertTrue(holder2.isDestroyed)
+        verify(exactly = 1) { loader1.destroy() }
+        verify(exactly = 1) { loader2.destroy() }
+
+        assertNull(module.getHolder(holder1.nativeAdId))
+        assertNull(module.getHolder(holder2.nativeAdId))
+    }
+
+    @Test
+    fun `destroyNativeAd destroys holder and removes from registry`() {
+        val context = mockk<ReactApplicationContext>(relaxed = true)
+        every { context.runOnUiQueueThread(any()) } answers { firstArg<Runnable>().run() }
+        val module = CloudXModuleImpl(context)
+
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val slot = io.mockk.slot<io.cloudx.sdk.CloudXNativeAdListener>()
+        every { loader.nativeAdListener = capture(slot) } returns Unit
+        every { CloudX.isInitialized() } returns true
+        every { CloudX.createNativeAdLoader(any(), any()) } returns loader
+
+        val loadPromise = mockk<Promise>(relaxed = true)
+        module.loadNativeAd("unit-1", FakeReadableMap(emptyMap()), loadPromise)
+
+        val holder = slot.captured as CloudXNativeAdHolder
+        val nativeAdId = holder.nativeAdId
+
+        module.destroyNativeAd(nativeAdId)
+
+        assertTrue(holder.isDestroyed)
+        assertNull(module.getHolder(nativeAdId))
+    }
+
+    @Test
+    fun `holder click revenue and closed events route to onEvent with nativeAdId`() {
+        val loader = mockk<CloudXNativeAdLoader>(relaxed = true)
+        val ad = mockAd("unit-1")
+        val events = mutableListOf<Pair<String, WritableMap>>()
+
+        val holder = CloudXNativeAdHolder(
+            nativeAdId = "test-id",
+            adUnitId = "unit-1",
+            loader = loader,
+            onEvent = { eventName, map -> events.add(eventName to map) }
+        )
+
+        holder.onNativeAdClicked(ad)
+        holder.onAdRevenuePaid(ad)
+        holder.onNativeAdClosed(ad)
+
+        assertEquals(3, events.size)
+        assertEquals(CloudXAdEvents.ON_NATIVE_AD_CLICKED_EVENT, events[0].first)
+        assertEquals(CloudXAdEvents.ON_NATIVE_AD_REVENUE_PAID, events[1].first)
+        assertEquals(CloudXAdEvents.ON_NATIVE_AD_CLOSED_EVENT, events[2].first)
+    }
+}

package/android/src/test/java/com/cloudxreactnative/FakeReadable.kt

@@ -58,7 +58,7 @@ internal class FakeReadableMap(private val values: Map<String, Any?>) : Readable
     override fun getDynamic(name: String): Dynamic =
         throw UnsupportedOperationException("not used by the bridge")
 
-    override fun toHashMap(): HashMap<String, Any?> =
+    override fun toHashMap(): HashMap<String, Any> =
         throw UnsupportedOperationException("not used by the bridge")
 }
 
@@ -96,6 +96,6 @@ internal class FakeReadableArray(private val values: List<Any?>) : ReadableArray
     override fun getDynamic(index: Int): Dynamic =
         throw UnsupportedOperationException("not used by the bridge")
 
-    override fun toArrayList(): ArrayList<Any?> =
+    override fun toArrayList(): ArrayList<Any> =
         throw UnsupportedOperationException("not used by the bridge")
 }

package/cloudx-react-native.podspec

@@ -14,7 +14,7 @@ Pod::Spec.new do |s|
 
   s.requires_arc = true
 
-  s.dependency "CloudXCore", "~> 3.10.0"
+  s.dependency "CloudXCore", "~> 3.11.0"
 
   s.source_files = "ios/**/*.{h,mm}"
   s.resource_bundles = { 'CloudXReactNativePrivacy' => ['ios/PrivacyInfo.xcprivacy'] }

package/ios/CloudX.h

@@ -9,6 +9,13 @@
 
 #define DEVICE_SPECIFIC_ADVIEW_AD_FORMAT CLXBannerTypeW320H50
 
+@class CloudXNativeAdHolder;
+
+extern NSString *const ON_NATIVE_AD_CLICKED_EVENT;
+extern NSString *const ON_NATIVE_AD_EXPIRED_EVENT;
+extern NSString *const ON_NATIVE_AD_CLOSED_EVENT;
+extern NSString *const ON_NATIVE_AD_REVENUE_PAID;
+
 #ifdef RCT_NEW_ARCH_ENABLED
 #import <CloudXSpec/CloudXSpec.h>
 @interface CloudX : RCTEventEmitter<NativeCloudXSpec, CLXInterstitialDelegate, CLXAppOpenDelegate, CLXRewardedDelegate, CLXBannerDelegate, CLXAdRevenueDelegate>
@@ -21,8 +28,13 @@ NS_ASSUME_NONNULL_BEGIN
 
 @property (nonatomic, strong, readonly, class) CloudX *shared;
 
+/** Preloaded native ads held for this module's JS context, keyed by nativeAdId. Main thread only. */
+@property (nonatomic, strong, readonly) NSMutableDictionary<NSString *, CloudXNativeAdHolder *> *nativeAdHolders;
+
 - (void)log:(NSString *)format, ...;
 
+- (void)sendReactNativeEventWithName:(NSString *)name body:(NSDictionary<NSString *, id> *)body;
+
 /**
  * Builds the standard ad-info event payload from a @c CLXAd object.
  * Shared by native delegate callbacks so the JS layer always receives

package/ios/CloudX.mm

@@ -5,6 +5,7 @@
 
 #import "CloudX.h"
 #import "CloudXExtraParameters.h"
+#import "CloudXNativeAdHolder.h"
 #import <React/RCTUtils.h>
 #import <math.h>
 
@@ -61,6 +62,7 @@
 @property (nonatomic, strong) NSMutableDictionary<NSString *, CLXInterstitial *> *interstitials;
 @property (nonatomic, strong) NSMutableDictionary<NSString *, CLXAppOpen *> *appOpenAds;
 @property (nonatomic, strong) NSMutableDictionary<NSString *, CLXRewarded *> *rewardedAds;
+@property (nonatomic, strong, readwrite) NSMutableDictionary<NSString *, CloudXNativeAdHolder *> *nativeAdHolders;
 
 // Overlay banner/MREC state — each ad unit ID owns exactly one CLXBannerAdView,
 // positioned window-level via NSLayoutConstraints against the root view controller.
@@ -127,6 +129,11 @@ static NSString *const ON_REWARDED_AD_HIDDEN_EVENT           = @"OnRewardedAdHid
 static NSString *const ON_REWARDED_AD_RECEIVED_REWARD_EVENT  = @"OnRewardedAdReceivedRewardEvent";
 static NSString *const ON_REWARDED_AD_REVENUE_PAID           = @"OnRewardedAdRevenuePaid";
 
+NSString *const ON_NATIVE_AD_CLICKED_EVENT = @"OnNativeAdClickedEvent";
+NSString *const ON_NATIVE_AD_EXPIRED_EVENT = @"OnNativeAdExpiredEvent";
+NSString *const ON_NATIVE_AD_CLOSED_EVENT  = @"OnNativeAdClosedEvent";
+NSString *const ON_NATIVE_AD_REVENUE_PAID  = @"OnNativeAdRevenuePaid";
+
 static NSString *const TOP_CENTER    = @"top_center";
 static NSString *const TOP_LEFT      = @"top_left";
 static NSString *const TOP_RIGHT     = @"top_right";
@@ -176,6 +183,7 @@ RCT_EXPORT_MODULE(CloudX)
         self.interstitials = [NSMutableDictionary dictionaryWithCapacity: 2];
         self.appOpenAds    = [NSMutableDictionary dictionaryWithCapacity: 2];
         self.rewardedAds   = [NSMutableDictionary dictionaryWithCapacity: 2];
+        self.nativeAdHolders = [NSMutableDictionary dictionary];
 
         self.adViews                       = [NSMutableDictionary dictionaryWithCapacity: 2];
         self.adViewAdFormats                 = [NSMutableDictionary dictionaryWithCapacity: 2];
@@ -223,6 +231,10 @@ RCT_EXPORT_MODULE(CloudX)
         {
             [self teardownAdViewForAdUnitIdentifier: adUnitIdentifier];
         }
+
+        // Only this module's own holders: by the time this block runs after a
+        // reload, the new module may already hold ads for the new JS context.
+        [CloudXNativeAdHolder destroyAllHoldersInRegistry: self.nativeAdHolders];
     } );
 }
 
@@ -654,6 +666,77 @@ RCT_EXPORT_METHOD(destroyRewarded:(NSString *)adUnitIdentifier)
     }
 }
 
+#pragma mark - Native (Preload)
+
+- (void)applyOptions:(NSDictionary<NSString *, id> *)options toNativeAdLoader:(CLXNativeAdLoader *)loader
+{
+    NSDictionary *opts = [options isKindOfClass: [NSDictionary class]] ? options : @{};
+    NSString *(^string)(NSString *) = ^NSString *(NSString *key) {
+        id value = opts[key];
+        return [value isKindOfClass: [NSString class]] ? value : nil;
+    };
+    BOOL (^flag)(NSString *) = ^BOOL(NSString *key) {
+        id value = opts[key];
+        return [value respondsToSelector: @selector(boolValue)] && [value boolValue];
+    };
+    NSArray *(^entries)(NSString *) = ^NSArray *(NSString *key) {
+        id value = opts[key];
+        return [value isKindOfClass: [NSArray class]] ? value : nil;
+    };
+
+    [CloudXNativeAdHolder configureLoader: loader
+                                placement: string(@"placement")
+                               customData: string(@"customData")
+                   disableVideoFullScreen: flag(@"disableVideoFullScreen")
+                        startVideoUnmuted: flag(@"startVideoUnmuted")
+                   hideVideoMediaControls: flag(@"hideVideoMediaControls")
+                    extraParameterEntries: entries(@"extraParameters")
+               localExtraParameterEntries: entries(@"localExtraParameters")];
+}
+
+RCT_EXPORT_METHOD(loadNativeAd:(NSString *)adUnitId
+                       options:(NSDictionary<NSString *, id> *)options
+                       resolve:(RCTPromiseResolveBlock)resolve
+                        reject:(RCTPromiseRejectBlock)reject)
+{
+    if ( ![self isPluginInitialized] || ![CloudXCore shared].isInitialized )
+    {
+        reject(@"200", @"CloudX SDK is not initialized", nil);
+        return;
+    }
+
+    if ( adUnitId.length == 0 )
+    {
+        reject(@"300", @"Invalid or empty adUnitId", nil);
+        return;
+    }
+
+    NSString *nativeAdId = [[NSUUID UUID] UUIDString];
+    CLXNativeAdLoader *loader = [[CloudXCore shared] createNativeAdLoaderWithAdUnitIdentifier: adUnitId];
+    [self applyOptions: options toNativeAdLoader: loader];
+
+    CloudXNativeAdHolder *holder = [[CloudXNativeAdHolder alloc] initWithNativeAdId: nativeAdId
+                                                                           adUnitId: adUnitId
+                                                                             loader: loader];
+    loader.nativeAdDelegate = holder;
+    loader.revenueDelegate  = holder;
+    holder.resolveBlock = resolve;
+    holder.rejectBlock  = reject;
+
+    [CloudXNativeAdHolder registerHolder: holder];
+
+    [loader loadAd];
+}
+
+RCT_EXPORT_METHOD(destroyNativeAd:(NSString *)nativeAdId)
+{
+    if ( nativeAdId.length == 0 ) return;
+    CloudXNativeAdHolder *holder = [CloudXNativeAdHolder holderForId: nativeAdId];
+    if ( !holder ) return;
+    [holder destroy];
+    [CloudXNativeAdHolder removeHolderForId: nativeAdId];
+}
+
 #pragma mark - Ad Callbacks
 
 - (void)didLoadAd:(CLXAd *)ad
@@ -2219,7 +2302,12 @@ static const CGFloat kCloudXNativeIconMaxDimension = 96.0;
              ON_REWARDED_AD_DISPLAY_FAILED_EVENT,
              ON_REWARDED_AD_HIDDEN_EVENT,
              ON_REWARDED_AD_RECEIVED_REWARD_EVENT,
-             ON_REWARDED_AD_REVENUE_PAID];
+             ON_REWARDED_AD_REVENUE_PAID,
+
+             ON_NATIVE_AD_CLICKED_EVENT,
+             ON_NATIVE_AD_EXPIRED_EVENT,
+             ON_NATIVE_AD_CLOSED_EVENT,
+             ON_NATIVE_AD_REVENUE_PAID];
 }
 
 - (NSDictionary *)constantsToExport
@@ -2263,6 +2351,11 @@ static const CGFloat kCloudXNativeIconMaxDimension = 96.0;
              @"ON_REWARDED_AD_RECEIVED_REWARD_EVENT":  ON_REWARDED_AD_RECEIVED_REWARD_EVENT,
              @"ON_REWARDED_AD_REVENUE_PAID":           ON_REWARDED_AD_REVENUE_PAID,
 
+             @"ON_NATIVE_AD_CLICKED_EVENT":           ON_NATIVE_AD_CLICKED_EVENT,
+             @"ON_NATIVE_AD_EXPIRED_EVENT":           ON_NATIVE_AD_EXPIRED_EVENT,
+             @"ON_NATIVE_AD_CLOSED_EVENT":            ON_NATIVE_AD_CLOSED_EVENT,
+             @"ON_NATIVE_AD_REVENUE_PAID":            ON_NATIVE_AD_REVENUE_PAID,
+
              @"TOP_CENTER_POSITION":    TOP_CENTER,
              @"TOP_LEFT_POSITION":      TOP_LEFT,
              @"TOP_RIGHT_POSITION":     TOP_RIGHT,

package/ios/CloudXNativeAdHolder.h

@@ -0,0 +1,66 @@
+//
+//  CloudXNativeAdHolder.h
+//  cloudx-react-native
+//
+//  Retains a preloaded native ad and its loader, routes lifecycle/revenue
+//  events to the module event emitter, and manages view binding.
+//
+
+#import <Foundation/Foundation.h>
+#import <CloudXCore/CloudXCore.h>
+#import <React/RCTBridgeModule.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class CloudXNativeAdView;
+
+@interface CloudXNativeAdHolder : NSObject <CLXNativeAdDelegate, CLXAdRevenueDelegate>
+
+@property (nonatomic, copy, readonly) NSString *nativeAdId;
+@property (nonatomic, copy, readonly) NSString *adUnitId;
+@property (nonatomic, strong, readonly) CLXNativeAdLoader *loader;
+
+@property (nonatomic, strong, nullable) CLXAd *ad;
+@property (nonatomic, assign, getter=isExpired) BOOL expired;
+// Set by the ad's first revenue, which CloudX reports on its impression.
+// Rendering alone does not count, so a rendered ad that nobody saw still
+// reports its expiry.
+@property (nonatomic, assign, readonly, getter=isImpressed) BOOL impressed;
+@property (nonatomic, weak, nullable) CloudXNativeAdView *boundView;
+
+@property (nonatomic, copy, nullable) RCTPromiseResolveBlock resolveBlock;
+@property (nonatomic, copy, nullable) RCTPromiseRejectBlock rejectBlock;
+
+- (instancetype)initWithNativeAdId:(NSString *)nativeAdId
+                          adUnitId:(NSString *)adUnitId
+                            loader:(CLXNativeAdLoader *)loader NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
+
+- (void)destroy;
+
+/**
+ * Applies load-time options to a native ad loader. Shared by the module's
+ * preload path and the view's auto-load path so both configure loaders
+ * identically. Extra parameters arrive as `{key, value}` entry arrays, the one
+ * wire format both callers receive from JS.
+ */
++ (void)configureLoader:(CLXNativeAdLoader *)loader
+              placement:(nullable NSString *)placement
+             customData:(nullable NSString *)customData
+ disableVideoFullScreen:(BOOL)disableVideoFullScreen
+      startVideoUnmuted:(BOOL)startVideoUnmuted
+ hideVideoMediaControls:(BOOL)hideVideoMediaControls
+  extraParameterEntries:(nullable NSArray<NSDictionary *> *)extraParameterEntries
+localExtraParameterEntries:(nullable NSArray<NSDictionary *> *)localExtraParameterEntries;
+
+#pragma mark - Registry (main-thread confined, owned by the current CloudX module)
+
++ (void)registerHolder:(CloudXNativeAdHolder *)holder;
++ (nullable CloudXNativeAdHolder *)holderForId:(NSString *)nativeAdId;
++ (void)removeHolderForId:(NSString *)nativeAdId;
+/** Destroys and removes every holder in `registry`. */
++ (void)destroyAllHoldersInRegistry:(NSMutableDictionary<NSString *, CloudXNativeAdHolder *> *)registry;
+
+@end
+
+NS_ASSUME_NONNULL_END