cloudx-react-native 3.10.0 → 3.10.1

package/android/src/main/java/com/cloudxreactnative/CloudXNativeAdView.kt

@@ -0,0 +1,718 @@
+package com.cloudxreactnative
+
+import android.graphics.drawable.BitmapDrawable
+import android.util.Log
+import android.view.View
+import android.view.View.MeasureSpec
+import android.view.ViewGroup
+import android.widget.ImageView
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.views.view.ReactViewGroup
+import io.cloudx.sdk.CloudX
+import io.cloudx.sdk.CloudXAd
+import io.cloudx.sdk.CloudXAdRevenueListener
+import io.cloudx.sdk.CloudXError
+import io.cloudx.sdk.CloudXErrorCode
+import io.cloudx.sdk.CloudXNativeAd
+import io.cloudx.sdk.CloudXNativeAdListener
+import io.cloudx.sdk.CloudXNativeAdLoader
+import io.cloudx.sdk.CloudXNativeAdView as SdkNativeAdView
+import io.cloudx.sdk.CloudXNativeAdViewBinder
+import io.cloudx.sdk.toCloudXError
+import org.json.JSONObject
+
+/**
+ * In-tree native ad view component. Supports two render modes:
+ *
+ * - Template (default): the bundled SDK templates (small / medium / media-banner
+ *   / vertical-media) are inflated and populated by the SDK.
+ * - Manual: when the JS layer binds asset-view refs via `updateAssetView` and
+ *   calls `renderNativeAd`, this view populates the publisher-supplied views
+ *   from `ad.nativeAd.*` getters and calls
+ *   `ad.nativeAd.prepareForInteraction(clickableViews, this)` so impression
+ *   and click tracking are wired up against the publisher's own layout.
+ *
+ * Extends [ReactViewGroup] (not [FrameLayout], the base used by the in-tree
+ * banner/MREC [CloudXAdView]) because, unlike a banner, this component can
+ * host real React-declared children in manual mode: `ReactViewGroup` makes
+ * `onLayout`/`requestLayout` no-ops so React Native's `NativeViewHierarchyManager`
+ * keeps authority over their Yoga-computed frames. Extending a plain `ViewGroup`
+ * here would let Android's own layout pass resize every RN-managed asset view
+ * (title, icon, media, CTA) to `MATCH_PARENT` on the next re-layout, stacking
+ * them at identical bounds and burying the CTA.
+ *
+ * A dedicated [CloudXNativeAdLoader] is created per view instance rather than
+ * shared per ad unit. Sharing a loader across concurrent mounts for the same ad
+ * unit produces two defects: (1) delegate reassignment — each new view's
+ * `loader.nativeAdListener = this` overwrites the previous view's registration,
+ * so callbacks are delivered to whichever view attached most recently; (2)
+ * duplicate-load rejection — the SDK serializes `loadAd` on a single loader, so
+ * concurrent mounts beyond the first get an immediate "load already in
+ * progress" failure and stay stuck.
+ */
+class CloudXNativeAdView(private val reactContext: ThemedReactContext) : ReactViewGroup(reactContext), CloudXNativeAdListener, CloudXAdRevenueListener {
+
+    private companion object {
+        const val TAG = "CloudXNativeAdView"
+
+        /**
+         * Delay before the second sizing pass on an inserted media view. Some
+         * networks attach their media surface asynchronously after the binder
+         * returns, so the next-frame pass can still measure an empty view.
+         */
+        const val MEDIA_VIEW_RESIZE_RETRY_MS = 500L
+    }
+
+    var adUnitId: String? = null
+        set(value) {
+            if (field == value) return
+            field = value
+            // The @ReactProp setters for `adUnitId` and `manualRender` fire in
+            // declaration order, so eagerly loading from this setter would run
+            // before `manualRender` has been applied — locking the view into
+            // the template load path even when the publisher mounted asset-view
+            // children. Defer to `onAttachedToWindow`, which RN guarantees to
+            // fire after all props are set.
+            //
+            // A change AFTER a loader exists is a live re-target: the old
+            // loader belongs to the old ad unit and must not keep serving
+            // callbacks for this view.
+            if (attachedLoader != null) {
+                releaseLoaderState()
+                // The same ordering trap described above applies to the
+                // re-target: `placement`, `customData`, the video flags and the
+                // extra parameters are applied AFTER `adUnitId`, so loading
+                // synchronously here configured the new loader from the
+                // previous unit's values. Post it instead, so the load runs
+                // once the whole prop update has been applied.
+                val target = value
+                if (isAttachedToWindow) {
+                    post { if (adUnitId == target && isAttachedToWindow) loadIfPossible() }
+                }
+            }
+        }
+
+    var templateName: String? = null
+
+    var placement: String? = null
+        set(value) {
+            field = value
+            currentLoader()?.setPlacement(value)
+        }
+
+    var customData: String? = null
+        set(value) {
+            field = value
+            currentLoader()?.setCustomData(value)
+        }
+
+    var disableVideoFullScreen: Boolean = false
+        set(value) {
+            field = value
+            currentLoader()?.isVideoFullScreenDisabled = value
+        }
+
+    var startVideoUnmuted: Boolean = false
+        set(value) {
+            field = value
+            currentLoader()?.isStartVideoUnmuted = value
+        }
+
+    var hideVideoMediaControls: Boolean = false
+        set(value) {
+            field = value
+            currentLoader()?.isVideoMediaControlsHidden = value
+        }
+
+    /**
+     * Controls how the loaded ad is rendered. When true, this view skips the
+     * template binder and lets the JS layer drive layout through
+     * `updateAssetView` + `renderNativeAd`. Auto-load itself runs in both
+     * render modes.
+     */
+    var manualRender: Boolean = false
+
+    var extraParameters: Map<String, Any?> = emptyMap()
+        set(value) {
+            field = value
+            applyExtraParametersIfReady()
+        }
+
+    var localExtraParameters: Map<String, Any?> = emptyMap()
+        set(value) {
+            field = value
+            applyExtraParametersIfReady()
+        }
+
+    private var appliedExtraParameterKeys: Set<String> = emptySet()
+    private var appliedLocalExtraParameterKeys: Set<String> = emptySet()
+
+    private var attachedLoader: CloudXNativeAdLoader? = null
+    private var hostedAdView: SdkNativeAdView? = null
+    private var loadRequested: Boolean = false
+
+    /**
+     * Ad delivered by the current load cycle, if any. Used to distinguish
+     * post-load failures (render/adapter errors after a successful load,
+     * surfaced to JS as `onAdDisplayFailedEvent`) from genuine load failures
+     * (`onAdLoadFailedEvent`).
+     */
+    private var loadedCycleAd: CloudXAd? = null
+
+    /**
+     * Most recently loaded ad in manual mode. Held so `renderNativeAd` can
+     * register click+impression tracking once the JS layer finishes binding
+     * asset views.
+     */
+    private var pendingManualAd: CloudXAd? = null
+
+    /** Publisher-supplied clickable subviews, collected by `updateAssetView`. */
+    private val clickableViews: MutableList<View> = mutableListOf()
+
+    /**
+     * Maps asset role name to the publisher-supplied view. Used so a re-bind
+     * of the same role replaces the prior entry without leaving stale
+     * references in `clickableViews`.
+     */
+    private val assetViewsByRole: MutableMap<String, View> = mutableMapOf()
+
+    /**
+     * SDK-owned media/options views inserted into the publisher's asset
+     * containers during manual binding. Tracked so a reload or a destroy can
+     * pull them back out; without this, successive load cycles stack multiple
+     * SDK views inside the same container. Mirrors iOS's `insertedSDKSubviews`.
+     */
+    private val insertedSdkViews: MutableList<View> = mutableListOf()
+
+    /**
+     * React-declared children only. The SDK ad view is attached as a physical
+     * `ViewGroup` child but deliberately kept out of this list so React's
+     * `manageChildren` reconciliation never touches it. Mirrors
+     * [CloudXNativeAdViewManagerImpl]'s shadowed child accessors.
+     */
+    private val reactChildren: MutableList<View> = mutableListOf()
+
+    fun reactChildCount(): Int = reactChildren.size
+
+    fun reactChildAt(index: Int): View? = reactChildren.getOrNull(index)
+
+    fun addReactChild(child: View, index: Int) {
+        val clampedIndex = index.coerceIn(0, reactChildren.size)
+        reactChildren.add(clampedIndex, child)
+        super.addView(child, clampedIndex)
+    }
+
+    fun removeReactChildAt(index: Int) {
+        if (index !in reactChildren.indices) return
+        val child = reactChildren.removeAt(index)
+        super.removeView(child)
+    }
+
+    fun removeAllReactChildren() {
+        for (child in reactChildren) {
+            super.removeView(child)
+        }
+        reactChildren.clear()
+    }
+
+    /**
+     * A dedicated loader per view. Sharing a loader across views for the same
+     * ad unit causes delegate reassignment and duplicate-load rejection (see
+     * the class doc). Reads the view's current field values so a loader
+     * created lazily by any setter (or by `onAttachedToWindow`) always starts
+     * fully configured, regardless of which prop landed first.
+     */
+    private fun currentLoader(): CloudXNativeAdLoader? {
+        attachedLoader?.let { return it }
+        val id = adUnitId ?: return null
+        val loader = CloudX.createNativeAdLoader(reactContext, id)
+        attachedLoader = loader
+        loader.nativeAdListener = this
+        loader.revenueListener = this
+        loader.setPlacement(placement)
+        loader.setCustomData(customData)
+        loader.isVideoFullScreenDisabled = disableVideoFullScreen
+        loader.isStartVideoUnmuted = startVideoUnmuted
+        loader.isVideoMediaControlsHidden = hideVideoMediaControls
+        appliedExtraParameterKeys = emptySet()
+        appliedLocalExtraParameterKeys = emptySet()
+        applyExtraParametersIfReady()
+        return loader
+    }
+
+    private fun applyExtraParametersIfReady() {
+        val loader = attachedLoader ?: return
+        appliedExtraParameterKeys = applyEntries(loader::setExtraParameter, extraParameters, appliedExtraParameterKeys)
+        appliedLocalExtraParameterKeys = applyEntries(loader::setLocalExtraParameter, localExtraParameters, appliedLocalExtraParameterKeys)
+    }
+
+    private fun applyEntries(setter: (String, Any?) -> Unit, entries: Map<String, Any?>, previousKeys: Set<String>): Set<String> {
+        for ((key, value) in entries) setter(key, value)
+        for (key in previousKeys - entries.keys) setter(key, null)
+        return entries.keys
+    }
+
+    private fun buildBinder(): CloudXNativeAdViewBinder {
+        // Every bundled layout uses the same resource IDs for each slot so we
+        // only need to swap the layout resource based on `templateName`.
+        // Unknown values fall back to the medium layout.
+        val layoutRes = when (templateName) {
+            "small_template" -> R.layout.cloudx_rn_native_small_template
+            "media_banner_template" -> R.layout.cloudx_rn_native_media_banner_template
+            "vertical_media_template" -> R.layout.cloudx_rn_native_vertical_media_template
+            else -> R.layout.cloudx_rn_native_medium_template
+        }
+        return CloudXNativeAdViewBinder.Builder(layoutRes)
+            .setTitleTextViewId(R.id.cloudx_rn_native_title)
+            .setBodyTextViewId(R.id.cloudx_rn_native_body)
+            .setCallToActionButtonId(R.id.cloudx_rn_native_cta)
+            .setIconImageViewId(R.id.cloudx_rn_native_icon)
+            .setMediaContentViewGroupId(R.id.cloudx_rn_native_media)
+            .setOptionsContentViewGroupId(R.id.cloudx_rn_native_options)
+            .setAdvertiserTextViewId(R.id.cloudx_rn_native_advertiser)
+            .setStarRatingContentViewGroupId(R.id.cloudx_rn_native_rating)
+            .build()
+    }
+
+    private fun loadIfPossible() {
+        if (loadRequested) return
+        val loader = currentLoader() ?: return
+        loadRequested = true
+        loadedCycleAd = null
+
+        if (manualRender) {
+            // Flow C (late binding): no pre-built binder view. The publisher
+            // children drive layout; `onNativeAdLoaded` will stash the ad and
+            // the subsequent `updateAssetView` + `renderNativeAd` commands
+            // wire up content and click tracking.
+            pendingManualAd = null
+            clickableViews.clear()
+            assetViewsByRole.clear()
+            loader.loadAd()
+        } else {
+            // Flow B (pre-built binder): the SDK populates the bundled
+            // template view. Attach before loading so the SDK's impression
+            // observer sees a window-backed view when it binds the creative;
+            // attaching only from `onNativeAdLoaded` can miss the first
+            // impression and its revenue callback.
+            val adView = SdkNativeAdView(context, buildBinder())
+            attachAdView(adView)
+            loader.loadAd(adView)
+        }
+    }
+
+    override fun onAttachedToWindow() {
+        super.onAttachedToWindow()
+        loadIfPossible()
+    }
+
+    fun teardown() {
+        releaseLoaderState()
+    }
+
+    /**
+     * Destroys the owned loader and resets all per-loader state. The loader
+     * is owned by this view: destroying it releases the SDK-side ad pipeline
+     * so nothing calls back into this view afterwards. Used both when React
+     * drops the view instance and when `adUnitId` is re-targeted live.
+     */
+    private fun releaseLoaderState() {
+        attachedLoader?.let {
+            it.nativeAdListener = null
+            it.revenueListener = null
+            it.destroy()
+        }
+        attachedLoader = null
+        removeInsertedSdkViews()
+        hostedAdView?.let { (it.parent as? ViewGroup)?.removeView(it) }
+        hostedAdView = null
+        pendingManualAd = null
+        loadedCycleAd = null
+        loadRequested = false
+        clickableViews.clear()
+        assetViewsByRole.clear()
+        appliedExtraParameterKeys = emptySet()
+        appliedLocalExtraParameterKeys = emptySet()
+    }
+
+    /**
+     * Pulls SDK-owned views back out of the publisher's containers. The
+     * containers themselves are React children and are left mounted.
+     */
+    private fun removeInsertedSdkViews() {
+        for (sdkView in insertedSdkViews) {
+            (sdkView.parent as? ViewGroup)?.removeView(sdkView)
+        }
+        insertedSdkViews.clear()
+    }
+
+    private fun attachAdView(adView: SdkNativeAdView) {
+        // If a previous SDK ad view was attached for this instance, detach it
+        // first. React-managed children (manual mode's asset views) are never
+        // touched here — they belong to the JS tree and must survive reloads.
+        hostedAdView?.takeIf { it !== adView }?.let { previous ->
+            (previous.parent as? ViewGroup)?.removeView(previous)
+        }
+        hostedAdView = adView
+        if (adView.parent !== this) {
+            (adView.parent as? ViewGroup)?.removeView(adView)
+            // `super.addView` routes around the React-child shadow list so the
+            // SDK ad view is invisible to React's `manageChildren`.
+            super.addView(adView, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT))
+        }
+        layoutAdViewToBounds()
+    }
+
+    /**
+     * Explicitly sizes the SDK ad view to fill this view. React Native drives
+     * layout through Yoga and does not measure/lay out children it did not
+     * declare, so the SDK ad view — added as a physical child but hidden from
+     * React's shadow tree — would otherwise stay at 0x0 regardless of its
+     * MATCH_PARENT layout params.
+     */
+    private fun layoutAdViewToBounds() {
+        val ad = hostedAdView ?: return
+        val w = width
+        val h = height
+        if (w <= 0 || h <= 0) return
+        ad.measure(
+            MeasureSpec.makeMeasureSpec(w, MeasureSpec.EXACTLY),
+            MeasureSpec.makeMeasureSpec(h, MeasureSpec.EXACTLY),
+        )
+        ad.layout(0, 0, w, h)
+    }
+
+    override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
+        super.onSizeChanged(w, h, oldw, oldh)
+        layoutAdViewToBounds()
+    }
+
+    /**
+     * Sizes one SDK-inserted asset view to its React-managed container.
+     *
+     * [layoutAdViewToBounds] covers the hosted ad view in template mode. Manual
+     * mode instead inserts the SDK's own options and media views underneath the
+     * publisher's React containers, and those containers never measure children
+     * they did not declare — their `requestLayout`/`onLayout` are no-ops. An
+     * inserted view therefore stays 0x0 and never draws.
+     */
+    private fun sizeInsertedViewToParent(child: View, parent: ViewGroup) {
+        val w = parent.width
+        val h = parent.height
+        if (w <= 0 || h <= 0) return
+        child.measure(
+            MeasureSpec.makeMeasureSpec(w, MeasureSpec.EXACTLY),
+            MeasureSpec.makeMeasureSpec(h, MeasureSpec.EXACTLY),
+        )
+        child.layout(0, 0, w, h)
+    }
+
+    /**
+     * Sizes [child] on the next frame, and again after [retryDelayMs] when that
+     * is non-zero. A single pass is not enough: the container's own bounds can
+     * still be settling when the asset mounts, and some networks attach their
+     * media surface asynchronously after the binder returns.
+     */
+    private fun scheduleInsertedViewSizing(child: View, parent: ViewGroup, retryDelayMs: Long) {
+        parent.post { sizeInsertedViewToParent(child, parent) }
+        if (retryDelayMs > 0L) {
+            parent.postDelayed({ sizeInsertedViewToParent(child, parent) }, retryDelayMs)
+        }
+    }
+
+    /**
+     * Fabric-compatible event dispatch, routed through the same
+     * `UIManagerHelper` / `EventDispatcher` pathway (and shared [CloudXAdViewEvent]
+     * carrier) as the in-tree banner/MREC component.
+     */
+    private fun dispatch(eventName: String, payload: WritableMap) {
+        val dispatcher = UIManagerHelper.getEventDispatcherForReactTag(reactContext, id) ?: return
+        val surfaceId = UIManagerHelper.getSurfaceId(reactContext)
+        dispatcher.dispatchEvent(CloudXAdViewEvent(surfaceId, id, eventName, payload))
+    }
+
+    // Commands
+
+    fun commandLoadAd() {
+        loadRequested = false
+        loadIfPossible()
+    }
+
+    fun commandUpdateAssetView(assetViewTag: Int, assetViewName: String) {
+        val ad = pendingManualAd ?: return
+        val nativeAd = ad.nativeAd ?: return
+        val view = findViewById<View>(assetViewTag) ?: return
+
+        // Dropping the prior view for this role ensures only the current one
+        // is registered for clicks; otherwise a re-mount (e.g. in a feed)
+        // would leave stale references in the list.
+        assetViewsByRole[assetViewName]?.let { clickableViews.remove(it) }
+        assetViewsByRole[assetViewName] = view
+
+        when (assetViewName) {
+            "TitleView" -> {
+                // No text write: JS already renders the title from the
+                // dispatched metadata. Assigning TextView.text here replaces
+                // React's styled spannable with a plain string and loses the
+                // publisher's color and weight.
+                view.isClickable = true
+                if (!nativeAd.title.isNullOrEmpty()) clickableViews.add(view)
+            }
+            "AdvertiserView" -> {
+                view.isClickable = true
+                if (!nativeAd.advertiser.isNullOrEmpty()) clickableViews.add(view)
+            }
+            "BodyView" -> {
+                view.isClickable = true
+                if (!nativeAd.body.isNullOrEmpty()) clickableViews.add(view)
+            }
+            "CallToActionView" -> {
+                view.isClickable = true
+                if (!nativeAd.callToAction.isNullOrEmpty()) clickableViews.add(view)
+            }
+            "IconView" -> {
+                val icon = nativeAd.icon
+                if (icon != null && view is ImageView) {
+                    // URL-based icons are loaded asynchronously in JS via the
+                    // dispatched metadata; drawable-based icons must be set
+                    // here because the raw bytes never cross the bridge.
+                    if (icon.uri == null && icon.drawable is BitmapDrawable) {
+                        view.setImageDrawable(icon.drawable)
+                    }
+                }
+                view.isClickable = true
+                clickableViews.add(view)
+            }
+            "OptionsView" -> {
+                val optionsView = nativeAd.optionsView
+                if (optionsView != null && view is ViewGroup) {
+                    (optionsView.parent as? ViewGroup)?.takeIf { it !== view }?.removeView(optionsView)
+                    if (optionsView.parent == null) {
+                        view.addView(optionsView)
+                        insertedSdkViews.add(optionsView)
+                        scheduleInsertedViewSizing(optionsView, view, 0L)
+                    }
+                }
+            }
+            "MediaView" -> {
+                val mediaView = nativeAd.mediaView
+                if (mediaView != null && view is ViewGroup) {
+                    (mediaView.parent as? ViewGroup)?.takeIf { it !== view }?.removeView(mediaView)
+                    if (mediaView.parent == null) {
+                        view.addView(mediaView)
+                        insertedSdkViews.add(mediaView)
+                        scheduleInsertedViewSizing(mediaView, view, MEDIA_VIEW_RESIZE_RETRY_MS)
+                    }
+                }
+                view.isClickable = true
+                clickableViews.add(view)
+            }
+            "StarRatingView" -> {
+                // Decorative; not clickable. JS handles rendering.
+            }
+        }
+    }
+
+    fun commandRenderNativeAd() {
+        // Each guard is a display failure, not a silent no-op: the publisher's
+        // onAdDisplayFailedEvent handler must hear about it so the QA harness
+        // and publisher UI don't hang waiting for a callback that never comes.
+        val ad = pendingManualAd
+        if (ad == null) {
+            val error = CloudXErrorCode.ADAPTER_INTERNAL_ERROR.toCloudXError("renderNativeAd called before ad loaded")
+            dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_DISPLAY_FAILED_EVENT, loadFailedPayload(adUnitId ?: "", error))
+            return
+        }
+        val nativeAd = ad.nativeAd
+        if (nativeAd == null) {
+            val error = CloudXErrorCode.ADAPTER_INTERNAL_ERROR.toCloudXError("renderNativeAd: native ad not available")
+            dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_DISPLAY_FAILED_EVENT, loadFailedPayload(ad.adUnitId, error))
+            return
+        }
+        if (nativeAd.isExpired) {
+            val error = CloudXErrorCode.ADAPTER_AD_EXPIRED.toCloudXError("renderNativeAd: ad expired")
+            dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_DISPLAY_FAILED_EVENT, loadFailedPayload(ad.adUnitId, error))
+            return
+        }
+        val registered = nativeAd.prepareForInteraction(clickableViews.toList(), this)
+        if (!registered) {
+            // A load that cannot register click/impression tracking is a
+            // display failure: the ad renders but never produces revenue.
+            val error = CloudXErrorCode.ADAPTER_INTERNAL_ERROR.toCloudXError("Native ad failed to register click/impression tracking")
+            dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_DISPLAY_FAILED_EVENT, loadFailedPayload(ad.adUnitId, error))
+        }
+    }
+
+    fun commandDestroyAd() {
+        // Destroy whichever ad this cycle holds: manual mode stashes it in
+        // pendingManualAd, template mode only in loadedCycleAd. Leaving the
+        // template-mode ad alive would leak SDK-side resources.
+        val ad = pendingManualAd ?: loadedCycleAd
+        if (ad != null) {
+            attachedLoader?.destroy(ad)
+        }
+        // Tear the loader down rather than only clearing per-ad state. When
+        // destroyAd arrives before onNativeAdLoaded there is no ad to destroy
+        // above, and leaving the loader attached kept its listener wired: the
+        // in-flight ad was then delivered into a view the JS layer had already
+        // destroyed. Next loadAd rebuilds the loader through currentLoader().
+        releaseLoaderState()
+    }
+
+    /**
+     * Drops the per-ad mutable state and detaches the SDK-owned ad view, so an
+     * invalidated ad can't leak its state into the next load cycle. Used by the
+     * SDK-initiated expiry/close callbacks, which leave the loader alive
+     * deliberately: the ad is gone but the publisher may still reload this
+     * view. [commandDestroyAd] wants the stronger [releaseLoaderState], which
+     * also cancels a load still in flight.
+     */
+    private fun clearAdState() {
+        pendingManualAd = null
+        loadedCycleAd = null
+        clickableViews.clear()
+        assetViewsByRole.clear()
+        removeInsertedSdkViews()
+        // Only detach the SDK-owned ad view. React-managed asset-view children
+        // stay mounted — they belong to the JS tree and will be removed by
+        // React itself when the publisher unmounts them.
+        hostedAdView?.let { (it.parent as? ViewGroup)?.removeView(it) }
+        hostedAdView = null
+        loadRequested = false
+    }
+
+    // CloudXNativeAdListener
+
+    override fun onNativeAdLoaded(adView: SdkNativeAdView?, ad: CloudXAd) {
+        loadedCycleAd = ad
+        if (manualRender) {
+            pendingManualAd = ad
+        } else {
+            adView?.let { attachAdView(it) }
+        }
+        dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_LOADED_EVENT, infoPayload(ad))
+    }
+
+    override fun onNativeAdLoadFailed(adUnitId: String, error: CloudXError) {
+        loadRequested = false
+        // The SDK funnels post-load adapter/render errors through the same
+        // listener callback as load failures. If this cycle already delivered
+        // an ad, the failure happened while displaying it — surface it as a
+        // display failure so JS sees the correct lifecycle event.
+        val displayedAd = loadedCycleAd
+        if (displayedAd != null) {
+            loadedCycleAd = null
+            dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_DISPLAY_FAILED_EVENT, loadFailedPayload(displayedAd.adUnitId, error))
+        } else {
+            // Template mode attaches the ad view before loadAd, so a genuine
+            // load failure would otherwise leave a blank attached view.
+            hostedAdView?.let { (it.parent as? ViewGroup)?.removeView(it) }
+            hostedAdView = null
+            dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_LOAD_FAILED_EVENT, loadFailedPayload(adUnitId, error))
+        }
+    }
+
+    override fun onNativeAdClicked(ad: CloudXAd) {
+        dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_CLICKED_EVENT, infoPayload(ad))
+    }
+
+    override fun onNativeAdExpired(ad: CloudXAd) {
+        dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_EXPIRED_EVENT, infoPayload(ad))
+        // The ad is invalidated: release SDK-side resources and drop our
+        // per-ad refs so the expired state can't leak into the next load
+        // cycle. The loader itself stays alive for reuse.
+        attachedLoader?.destroy(ad)
+        clearAdState()
+    }
+
+    override fun onNativeAdClosed(ad: CloudXAd) {
+        dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_CLOSED_EVENT, infoPayload(ad))
+        // Mirrors onNativeAdExpired: the ad is done, so detach its view and
+        // clear per-ad refs. Loader stays alive for the next load cycle.
+        attachedLoader?.destroy(ad)
+        clearAdState()
+    }
+
+    // CloudXAdRevenueListener
+
+    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
+        dispatch(CloudXAdEvents.ON_NATIVE_AD_VIEW_REVENUE_PAID_EVENT, infoPayload(cloudXAd))
+    }
+
+    /*
+     * Codegen cannot express a nested/heterogeneous native-ad payload as a
+     * typed prop, so both `adValues` and the loaded native ad's own metadata
+     * are serialized to JSON strings here and re-parsed by the JS wrapper
+     * (mirrors CloudXAdView's adValuesJson for the banner/MREC component).
+     */
+    private fun infoPayload(ad: CloudXAd): WritableMap {
+        val map = Arguments.createMap()
+        map.putString("adUnitId", ad.adUnitId)
+        map.putString("adFormat", ad.adFormat.name)
+        map.putString("networkName", ad.networkName)
+        map.putString("networkPlacement", ad.networkPlacement ?: "")
+        map.putString("placement", ad.placement ?: "")
+        map.putString("creativeId", ad.creativeId ?: "")
+        map.putDouble("revenue", ad.revenue)
+        val adValuesJson = try {
+            JSONObject(ad.adValues as Map<*, *>).toString()
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to serialize adValues; delivering empty object", e)
+            "{}"
+        }
+        map.putString("adValuesJson", adValuesJson)
+        ad.nativeAd?.let { map.putString("nativeAdJson", nativeAdMetadataJson(it)) }
+        return map
+    }
+
+    private fun loadFailedPayload(unitId: String, error: CloudXError): WritableMap {
+        val map = Arguments.createMap()
+        map.putString("adUnitId", unitId)
+        // Codegen declares `code` as Double; emit a double to match (and to
+        // stay consistent with `revenue` and the iOS side).
+        map.putDouble("code", error.code.code.toDouble())
+        map.putString("message", error.message)
+        return map
+    }
+
+    /**
+     * JSON-encoded native ad metadata for the codegen-typed `nativeAdJson`
+     * string field (codegen cannot express a nested map here). Mirrors the
+     * same field set as CloudXAdInfo.kt's imperative-event metadata map.
+     */
+    private fun nativeAdMetadataJson(nativeAd: CloudXNativeAd): String {
+        val iconImageSource = nativeAd.icon?.let { icon ->
+            if (icon.uri == null) {
+                (icon.drawable as? BitmapDrawable)?.bitmap?.let(::bitmapToBase64Png)
+            } else {
+                null
+            }
+        }
+        val json = JSONObject()
+        json.put("title", nativeAd.title ?: JSONObject.NULL)
+        json.put("advertiser", nativeAd.advertiser ?: JSONObject.NULL)
+        json.put("body", nativeAd.body ?: JSONObject.NULL)
+        json.put("callToAction", nativeAd.callToAction ?: JSONObject.NULL)
+        nativeAd.starRating?.let { json.put("starRating", it) }
+        if (nativeAd.mediaContentAspectRatio > 0f) {
+            json.put("mediaContentAspectRatio", nativeAd.mediaContentAspectRatio.toDouble())
+        }
+        val iconAvailable = nativeAd.icon != null
+        json.put("isIconImageAvailable", iconAvailable)
+        json.put("isOptionsViewAvailable", nativeAd.optionsView != null)
+        json.put("isMediaViewAvailable", nativeAd.mediaView != null)
+        nativeAd.icon?.let { icon ->
+            icon.uri?.let { json.put("url", it.toString()) }
+            if (icon.uri == null) {
+                iconImageSource?.let { json.put("imageSource", it) }
+            }
+        }
+        json.put("isVideoContent", nativeAd.isVideoContent)
+        json.put("videoDuration", nativeAd.videoDuration)
+        json.put("isExpired", nativeAd.isExpired)
+        return json.toString()
+    }
+}