cloudx-react-native 3.11.0 → 3.11.1

package/src/hooks.ts

@@ -9,6 +9,10 @@ import { useEffect, useState, useCallback, useRef } from 'react';
 import type { EventSubscription } from 'react-native';
 import NativeCloudX from './specs/NativeCloudX';
 import { emitter } from './EventEmitter';
+import { CloudXNativeAd } from './CloudXNativeAd';
+import { useCloudXSdkInitializationGate } from './useCloudXSdkInitialization';
+import type { CloudXAdLoadFailedInfo } from './types/AdInfo';
+import type { CloudXNativeAdLoadOptions } from './types/NativeAd';
 
 const {
     ON_INTERSTITIAL_LOADED_EVENT,
@@ -429,3 +433,235 @@ export function useCloudXBanner(adUnitId: string): CloudXBannerHookResult {
 
     return { isLoaded, error };
 }
+
+// ---------------------------------------------------------------------------
+// useCloudXNativeAd
+// ---------------------------------------------------------------------------
+
+export type CloudXNativeAdHookStatus = 'idle' | 'loading' | 'loaded' | 'expired' | 'error';
+
+export type CloudXNativeAdHookResult = {
+    status: CloudXNativeAdHookStatus;
+    nativeAd: CloudXNativeAd | null;
+    error: CloudXAdLoadFailedInfo | null;
+    load: () => void;
+    destroy: () => void;
+};
+
+const stableSerialize = (value: unknown): unknown => {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(stableSerialize);
+    }
+    const record = value as Record<string, unknown>;
+    const sortedKeys = Object.keys(record).sort();
+    const result: Record<string, unknown> = {};
+    for (const key of sortedKeys) {
+        const val = record[key];
+        if (val !== undefined) {
+            result[key] = stableSerialize(val);
+        }
+    }
+    return result;
+};
+
+const getOptionsSignature = (options?: CloudXNativeAdLoadOptions): string => {
+    if (!options) return '{}';
+    return JSON.stringify(stableSerialize(options));
+};
+
+/**
+ * Hook for managing a preloaded native ad lifecycle.
+ *
+ * Preloads a native ad ahead of render and holds it until unmount, manual
+ * destruction, or identity change. Unlike view-managed ads, a preloaded ad's
+ * lifecycle belongs to its handle and this hook: unmounting a view bound to it
+ * does not destroy it.
+ *
+ * With autoLoad (the default) the first load waits until the SDK has
+ * initialized, as `CloudXNativeAdView` does. A `load()` call made before
+ * initialization fails with `NOT_INITIALIZED`.
+ *
+ * @param adUnitId - The ad unit identifier, or null to keep idle.
+ * @param options - Load options configuring the auction and loader.
+ * @param config - Optional configuration (autoLoad defaults to true).
+ */
+export function useCloudXNativeAd(
+    adUnitId: string | null,
+    options?: CloudXNativeAdLoadOptions,
+    config?: { autoLoad?: boolean }
+): CloudXNativeAdHookResult {
+    const autoLoad = config?.autoLoad ?? true;
+    const optionsSignature = getOptionsSignature(options);
+    const isSdkInitialized = useCloudXSdkInitializationGate('useCloudXNativeAd');
+
+    const [status, setStatus] = useState<CloudXNativeAdHookStatus>(() =>
+        autoLoad && adUnitId ? 'loading' : 'idle'
+    );
+    const [nativeAd, setNativeAd] = useState<CloudXNativeAd | null>(null);
+    const [error, setError] = useState<CloudXAdLoadFailedInfo | null>(null);
+
+    const mountedRef = useRef(true);
+    const generationRef = useRef(0);
+    const heldAdRef = useRef<CloudXNativeAd | null>(null);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+
+    const inflightRef = useRef<{
+        signature: string;
+        generation: number;
+        promise: Promise<CloudXNativeAd>;
+    } | null>(null);
+
+    const lastSignatureRef = useRef<string | null>(null);
+
+    const executeLoad = useCallback(() => {
+        if (!adUnitId) {
+            setStatus('idle');
+            setNativeAd(null);
+            setError(null);
+            return;
+        }
+
+        const currentSignature = `${adUnitId}::${optionsSignature}`;
+
+        // Coalesce concurrent loads with the same signature (React StrictMode
+        // double effects must not start two loads).
+        if (inflightRef.current && inflightRef.current.signature === currentSignature) {
+            return;
+        }
+
+        const generation = ++generationRef.current;
+        setStatus('loading');
+        setError(null);
+
+        if (heldAdRef.current) {
+            heldAdRef.current.destroy();
+            heldAdRef.current = null;
+            setNativeAd(null);
+        }
+
+        const currentOptions = optionsRef.current;
+        const promise = CloudXNativeAd.load(adUnitId, currentOptions);
+        inflightRef.current = { signature: currentSignature, generation, promise };
+
+        promise
+            .then((ad) => {
+                if (inflightRef.current?.promise === promise) {
+                    inflightRef.current = null;
+                }
+
+                // A load that resolves after unmount, after destroy(), or after the signature
+                // changed is destroyed immediately and never published (generation counter).
+                if (!mountedRef.current || generationRef.current !== generation) {
+                    ad.destroy();
+                    return;
+                }
+
+                if (heldAdRef.current && heldAdRef.current !== ad) {
+                    heldAdRef.current.destroy();
+                }
+                heldAdRef.current = ad;
+
+                // On the handle's 'expired' event: status 'expired', nativeAd null,
+                // and the expired handle destroyed.
+                ad.addListener('expired', () => {
+                    if (generationRef.current === generation && heldAdRef.current === ad) {
+                        heldAdRef.current = null;
+                        setStatus('expired');
+                        setNativeAd(null);
+                        ad.destroy();
+                    }
+                });
+
+                setStatus('loaded');
+                setNativeAd(ad);
+                setError(null);
+            })
+            .catch((err: CloudXAdLoadFailedInfo) => {
+                if (inflightRef.current?.promise === promise) {
+                    inflightRef.current = null;
+                }
+
+                // Ignores stale rejection after identity change, destroy, or unmount.
+                if (!mountedRef.current || generationRef.current !== generation) {
+                    return;
+                }
+
+                setStatus('error');
+                setNativeAd(null);
+                setError(err);
+            });
+    }, [adUnitId, optionsSignature]);
+
+    // Unmount owns the release. Kept apart from the load effect so a re-run
+    // of that effect (autoLoad flipping, say) never destroys an ad this hook
+    // has already published. Under StrictMode the simulated unmount only
+    // clears mountedRef; the remount sets it again, so a load in flight from
+    // the first mount is still published rather than duplicated.
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            if (heldAdRef.current) {
+                heldAdRef.current.destroy();
+                heldAdRef.current = null;
+            }
+        };
+    }, []);
+
+    useEffect(() => {
+        const currentSignature = adUnitId ? `${adUnitId}::${optionsSignature}` : '';
+        const isFirstRun = lastSignatureRef.current === null;
+        const signatureChanged = !isFirstRun && lastSignatureRef.current !== currentSignature;
+        lastSignatureRef.current = currentSignature;
+
+        if (signatureChanged) {
+            if (heldAdRef.current) {
+                heldAdRef.current.destroy();
+                heldAdRef.current = null;
+            }
+            // Never leave the previous identity's (now destroyed) handle
+            // published while the replacement loads, nor its status or error:
+            // with autoLoad off nothing replaces them, and a `loaded` status
+            // with no ad, or a `loading` one that never settles, would stick.
+            setNativeAd(null);
+            setStatus('idle');
+            setError(null);
+            generationRef.current++;
+            inflightRef.current = null;
+
+            if (!adUnitId) {
+                return;
+            }
+        }
+
+        // A held ad survives autoLoad flipping back on; only an identity
+        // change (handled above) replaces it.
+        if (autoLoad && adUnitId && isSdkInitialized && !heldAdRef.current) {
+            executeLoad();
+        }
+    }, [adUnitId, optionsSignature, autoLoad, isSdkInitialized, executeLoad]);
+
+    const load = useCallback(() => {
+        executeLoad();
+    }, [executeLoad]);
+
+    const destroy = useCallback(() => {
+        generationRef.current++;
+        inflightRef.current = null;
+
+        if (heldAdRef.current) {
+            heldAdRef.current.destroy();
+            heldAdRef.current = null;
+        }
+
+        setStatus('idle');
+        setNativeAd(null);
+        setError(null);
+    }, []);
+
+    return { status, nativeAd, error, load, destroy };
+}

package/src/index.ts

@@ -15,6 +15,7 @@ export { CloudXRewardedAd } from './CloudXRewardedAd';
 export { CloudXBannerAd } from './CloudXBannerAd';
 export { CloudXMRECAd } from './CloudXMRECAd';
 export { CloudXAdPosition } from './CloudXAdPosition';
+export { CloudXNativeAd } from './CloudXNativeAd';
 
 // Ad View Components (in-tree; layer correctly under app overlays)
 export { CloudXBannerView } from './CloudXBannerView';
@@ -47,12 +48,20 @@ export { CloudXErrorCode } from './CloudXErrorCode';
 export { requestTrackingAuthorization, getTrackingAuthorizationStatus, CloudXATTStatus } from './AppTrackingTransparency';
 
 // Hooks
-export { useCloudXInterstitial, useCloudXAppOpen, useCloudXRewarded, useCloudXBanner } from './hooks';
+export {
+    useCloudXInterstitial,
+    useCloudXAppOpen,
+    useCloudXRewarded,
+    useCloudXBanner,
+    useCloudXNativeAd,
+} from './hooks';
 export type {
     CloudXInterstitialHookResult,
     CloudXAppOpenHookResult,
     CloudXRewardedHookResult,
     CloudXBannerHookResult,
+    CloudXNativeAdHookResult,
+    CloudXNativeAdHookStatus,
 } from './hooks';
 
 // Types
@@ -92,6 +101,10 @@ export type {
     CloudXNativeAdMetadata,
     CloudXNativeAdViewHandle,
     CloudXNativeAdViewProps,
+    CloudXNativeAdViewComponentProps,
+    CloudXNativeAdViewPreloadedProps,
+    CloudXNativeAdLoadOptions,
+    CloudXNativeAdEventType,
     CloudXLocalExtraParameters,
 } from './types';
 export { CloudXNativeTemplate } from './types';

package/src/specs/CloudXNativeAdViewNativeComponent.ts

@@ -40,6 +40,11 @@ export type CloudXNativeAdLoadFailedEvent = Readonly<{
     message?: string | null;
 }>;
 
+/** Internal: names the preloaded ad that just left the view. */
+export type CloudXNativeAdBindingClearedEvent = Readonly<{
+    nativeAdId: string;
+}>;
+
 export type NativeExtraParameterEntry = Readonly<{
     key: string;
     value: UnsafeMixed;
@@ -53,8 +58,15 @@ export type NativeExtraParameterEntry = Readonly<{
  * normal RN z-ordering.
  */
 export interface NativeProps extends ViewProps {
-    /** Ad unit ID used to load the ad. */
-    adUnitId: string;
+    /** Ad unit ID used to load the ad. Ignored when `nativeAdId` is set. */
+    adUnitId?: string | null;
+
+    /**
+     * Id of an ad already loaded by `loadNativeAd`. When set, the view never
+     * loads: it renders the held ad on attach and leaves its lifetime to the
+     * holder, so unmounting does not destroy it.
+     */
+    nativeAdId?: string | null;
 
     /**
      * Publisher-selected template name (e.g. "small_template",
@@ -103,6 +115,12 @@ export interface NativeProps extends ViewProps {
     /** Called when the ad fails to render/display (e.g. manual render before load). */
     onAdDisplayFailedEvent: DirectEventHandler<CloudXNativeAdLoadFailedEvent>;
 
+    /**
+     * Called each time an ad is rendered into this view and registered for
+     * click and impression tracking. Fires again after a re-bind.
+     */
+    onAdDisplayedEvent: DirectEventHandler<CloudXNativeAdInfoEvent>;
+
     /** Called when the ad is clicked. */
     onAdClickedEvent: DirectEventHandler<CloudXNativeAdInfoEvent>;
 
@@ -114,6 +132,13 @@ export interface NativeProps extends ViewProps {
 
     /** Called when ad revenue is paid. */
     onAdRevenuePaidEvent: DirectEventHandler<CloudXNativeAdInfoEvent>;
+
+    /**
+     * Internal, not a publisher callback: native released the preloaded ad
+     * this view showed (destroy, expiry, or a newer view took it), so the JS
+     * view clears its asset components.
+     */
+    onAdBindingClearedEvent?: DirectEventHandler<CloudXNativeAdBindingClearedEvent>;
 }
 
 export interface NativeCommands {

package/src/specs/NativeCloudX.ts

@@ -61,6 +61,12 @@ export interface Spec extends TurboModule {
         ON_APPOPEN_DISPLAY_FAILED_EVENT: string;
         ON_APPOPEN_HIDDEN_EVENT: string;
         ON_APPOPEN_AD_REVENUE_PAID: string;
+
+        // Preloaded native ad events. Every payload carries `nativeAdId`.
+        ON_NATIVE_AD_CLICKED_EVENT: string;
+        ON_NATIVE_AD_EXPIRED_EVENT: string;
+        ON_NATIVE_AD_CLOSED_EVENT: string;
+        ON_NATIVE_AD_REVENUE_PAID: string;
     };
 
     // =========================================================================
@@ -171,6 +177,20 @@ export interface Spec extends TurboModule {
     showAppOpen(adUnitId: string, placement?: string | null, customData?: string | null): void;
     destroyAppOpen(adUnitId: string): void;
 
+    // =========================================================================
+    // Native (load first, render later)
+    // =========================================================================
+
+    /**
+     * Loads a native ad with no view attached. Resolves with
+     * `{ nativeAdId, adInfo }` once an ad is held natively; rejects with the
+     * CloudX error code as the promise code. The ad stays held until
+     * `destroyNativeAd`, expiry, or module invalidation.
+     */
+    loadNativeAd(adUnitId: string, options: UnsafeObject): Promise<UnsafeObject>;
+    /** Releases a held native ad. Idempotent; unknown ids are ignored. */
+    destroyNativeAd(nativeAdId: string): void;
+
     // =========================================================================
     // Event Emitter (required by NativeEventEmitter)
     // =========================================================================

package/src/types/NativeAd.ts

@@ -1,7 +1,8 @@
 import type { ViewProps } from 'react-native';
 import type { CloudXAdDisplayFailedInfo, CloudXAdInfo } from './AdInfo';
 import type { CloudXAdProps } from './AdProps';
-import type { CloudXExtraParameterValue } from './ExtraParameters';
+import type { CloudXExtraParameters, CloudXExtraParameterValue } from './ExtraParameters';
+import type { CloudXNativeAd } from '../CloudXNativeAd';
 
 /**
  * Built-in native ad template variants rendered by the SDK's view component.
@@ -85,41 +86,107 @@ export type CloudXLocalExtraParameters = {
 };
 
 /**
- * Props for the native-ad view component.
+ * Load-time options for {@link CloudXNativeAd.load}. These configure the
+ * auction and the loader, so they are fixed once the ad is loaded; the view
+ * that later renders the ad only chooses the layout.
+ */
+export type CloudXNativeAdLoadOptions = {
+    placement?: string | null;
+    customData?: string | null;
+    extraParameters?: CloudXExtraParameters | null;
+    localExtraParameters?: CloudXLocalExtraParameters | null;
+    disableVideoFullScreen?: boolean;
+    startVideoUnmuted?: boolean;
+    hideVideoMediaControls?: boolean;
+};
+
+/** Events a preloaded {@link CloudXNativeAd} reports on its own handle. */
+export type CloudXNativeAdEventType = 'clicked' | 'revenuePaid' | 'expired' | 'closed';
+
+/** Props every native-ad view accepts, whichever way the ad was loaded. */
+type CloudXNativeAdViewRenderProps = ViewProps & {
+    template?: CloudXNativeTemplate;
+    /** Selects between the SDK's bundled template layouts and manual asset binding. */
+    renderMode?: 'template' | 'manual';
+    /**
+     * Called each time the ad is rendered into this view and registered for
+     * click and impression tracking. Fires again after a re-bind.
+     */
+    onAdDisplayed?: (adInfo: CloudXAdInfo) => void;
+    /**
+     * Called when an ad fails to display or track in this view.
+     *
+     * Emitted on both platforms. Android fires it for post-load
+     * adapter/render errors and when click/impression registration fails in
+     * manual mode. iOS fires it on the manual-mode failure paths: render
+     * requested before load, expired ad, and registration refused. With
+     * `nativeAd`, it also fires when the handle is destroyed or expired.
+     */
+    onAdDisplayFailed?: (errorInfo: CloudXAdDisplayFailedInfo) => void;
+};
+
+/**
+ * Props for a native-ad view that loads its own ad when it attaches and
+ * destroys it on unmount. This is the shape `CloudXNativeAdView` has always
+ * taken, so wrappers that extend, `Omit` or `Pick` it keep compiling.
  *
  * Callbacks inherited from {@link CloudXAdProps} (`onAdLoaded`, `onAdLoadFailed`,
  * `onAdClicked`, `onAdRevenuePaid`) receive unwrapped payloads, not synthetic events.
  */
-export type CloudXNativeAdViewProps = CloudXAdProps &
-    ViewProps & {
-        template?: CloudXNativeTemplate;
+export type CloudXNativeAdViewProps = CloudXNativeAdViewRenderProps &
+    CloudXAdProps & {
         localExtraParameters?: CloudXLocalExtraParameters;
         disableVideoFullScreen?: boolean;
         startVideoUnmuted?: boolean;
         hideVideoMediaControls?: boolean;
-        /** Selects between the SDK's bundled template layouts and manual asset binding. */
-        renderMode?: 'template' | 'manual';
-        /**
-         * Called when a loaded ad subsequently fails to display or track.
-         *
-         * Emitted on both platforms. Android fires it for post-load
-         * adapter/render errors and when click/impression registration fails in
-         * manual mode. iOS fires it on the three manual-mode failure paths:
-         * render requested before load, expired ad, and registration refused.
-         */
-        onAdDisplayFailed?: (errorInfo: CloudXAdDisplayFailedInfo) => void;
         onAdExpired?: (adInfo: CloudXAdInfo) => void;
         onAdClosed?: (adInfo: CloudXAdInfo) => void;
+        nativeAd?: never;
     };
 
+/**
+ * The view renders an ad loaded earlier with {@link CloudXNativeAd.load}. It
+ * never loads and never destroys the ad. Clicks, revenue, expiry and close
+ * are reported once, on the handle (`nativeAd.addListener`), never on the
+ * view, so revenue cannot be counted twice.
+ */
+export type CloudXNativeAdViewPreloadedProps = CloudXNativeAdViewRenderProps & {
+    nativeAd: CloudXNativeAd;
+    adUnitId?: never;
+    placement?: never;
+    customData?: never;
+    extraParameters?: never;
+    localExtraParameters?: never;
+    disableVideoFullScreen?: never;
+    startVideoUnmuted?: never;
+    hideVideoMediaControls?: never;
+    onAdLoaded?: never;
+    onAdLoadFailed?: never;
+    onAdClicked?: never;
+    onAdRevenuePaid?: never;
+    onAdExpired?: never;
+    onAdClosed?: never;
+};
+
+/**
+ * Everything `CloudXNativeAdView` accepts: either it loads its own ad
+ * ({@link CloudXNativeAdViewProps}) or it renders one loaded earlier
+ * ({@link CloudXNativeAdViewPreloadedProps}). Mixing the two is a type error.
+ */
+export type CloudXNativeAdViewComponentProps = CloudXNativeAdViewProps | CloudXNativeAdViewPreloadedProps;
+
 export type CloudXNativeAdViewHandle = {
     /**
-     * Requests a load. This does NOT force a new auction: both native SDKs
+     * Requests a load. No-op when the view renders a preloaded `nativeAd`.
+     * This does NOT force a new auction: both native SDKs
      * re-serve the ad they already hold while it is neither expired nor
      * destroyed, including after its impression. Changed targeting is
      * therefore not picked up. Call `destroyAd()` first for a fresh ad.
      */
     loadAd: () => void;
-    /** Releases the native ad and its resources. */
+    /**
+     * Releases the native ad and its resources. No-op when the view renders a
+     * preloaded `nativeAd`: the handle owns that ad, so call `nativeAd.destroy()`.
+     */
     destroyAd: () => void;
 };

package/src/types/index.ts

@@ -29,6 +29,10 @@ export type {
     CloudXNativeAdMetadata,
     CloudXNativeAdViewHandle,
     CloudXNativeAdViewProps,
+    CloudXNativeAdViewComponentProps,
+    CloudXNativeAdViewPreloadedProps,
+    CloudXNativeAdLoadOptions,
+    CloudXNativeAdEventType,
     CloudXLocalExtraParameters,
 } from './NativeAd';
 export { CloudXNativeTemplate, CloudXNativeAssetType } from './NativeAd';

package/src/version.ts

@@ -3,4 +3,4 @@
 // This value is reported to the native SDK in CloudX.initialize() and is used
 // for wrapper-version telemetry/attribution, so a stale value mis-attributes
 // installs to the wrong release.
-export const PLUGIN_VERSION = '3.11.0';
+export const PLUGIN_VERSION = '3.11.1';