cloudx-react-native 3.4.6 → 3.6.0

package/src/hooks.ts

@@ -15,6 +15,10 @@ const {
     ON_INTERSTITIAL_LOAD_FAILED_EVENT,
     ON_INTERSTITIAL_DISPLAY_FAILED_EVENT,
     ON_INTERSTITIAL_HIDDEN_EVENT,
+    ON_APPOPEN_LOADED_EVENT,
+    ON_APPOPEN_LOAD_FAILED_EVENT,
+    ON_APPOPEN_DISPLAY_FAILED_EVENT,
+    ON_APPOPEN_HIDDEN_EVENT,
     ON_REWARDED_AD_LOADED_EVENT,
     ON_REWARDED_AD_LOAD_FAILED_EVENT,
     ON_REWARDED_AD_DISPLAY_FAILED_EVENT,
@@ -123,6 +127,105 @@ export function useCloudXInterstitial(adUnitId: string): CloudXInterstitialHookR
     return { isLoaded, isLoading, error, load, show, destroy };
 }
 
+// ---------------------------------------------------------------------------
+// useCloudXAppOpen
+// ---------------------------------------------------------------------------
+
+export type CloudXAppOpenHookResult = {
+    isLoaded: boolean;
+    isLoading: boolean;
+    error: string | null;
+    load: () => void;
+    show: (placement?: string | null, customData?: string | null) => void;
+    destroy: () => void;
+};
+
+/**
+ * Hook for managing an app open ad lifecycle.
+ *
+ * @param adUnitId - The ad unit identifier.
+ */
+export function useCloudXAppOpen(adUnitId: string): CloudXAppOpenHookResult {
+    const [isLoaded, setIsLoaded] = useState(false);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    const mountedRef = useRef(true);
+
+    useEffect(() => {
+        mountedRef.current = true;
+        const subs: EventSubscription[] = [];
+
+        subs.push(
+            emitter.addListener(ON_APPOPEN_LOADED_EVENT, (event: { adUnitId: string }) => {
+                if (event.adUnitId === adUnitId && mountedRef.current) {
+                    setIsLoaded(true);
+                    setIsLoading(false);
+                    setError(null);
+                }
+            }),
+        );
+
+        subs.push(
+            emitter.addListener(ON_APPOPEN_LOAD_FAILED_EVENT, (event: { adUnitId: string; message?: string }) => {
+                if (event.adUnitId === adUnitId && mountedRef.current) {
+                    setIsLoaded(false);
+                    setIsLoading(false);
+                    setError(event.message ?? 'Failed to load');
+                }
+            }),
+        );
+
+        subs.push(
+            emitter.addListener(ON_APPOPEN_DISPLAY_FAILED_EVENT, (event: { adUnitId: string; message?: string }) => {
+                if (event.adUnitId === adUnitId && mountedRef.current) {
+                    setIsLoaded(false);
+                    setError(event.message ?? 'Display failed');
+                }
+            }),
+        );
+
+        subs.push(
+            emitter.addListener(ON_APPOPEN_HIDDEN_EVENT, (event: { adUnitId: string }) => {
+                if (event.adUnitId === adUnitId && mountedRef.current) {
+                    setIsLoaded(false);
+                }
+            }),
+        );
+
+        return () => {
+            mountedRef.current = false;
+            subs.forEach((s) => s.remove());
+            NativeCloudX.destroyAppOpen(adUnitId);
+        };
+    }, [adUnitId]);
+
+    const load = useCallback(() => {
+        setIsLoading(true);
+        setError(null);
+        NativeCloudX.loadAppOpen(adUnitId);
+    }, [adUnitId]);
+
+    const show = useCallback(
+        (placement?: string | null, customData?: string | null) => {
+            if (!isLoaded) {
+                setError('Ad not loaded');
+                return;
+            }
+            NativeCloudX.showAppOpen(adUnitId, placement ?? undefined, customData ?? undefined);
+        },
+        [adUnitId, isLoaded],
+    );
+
+    const destroy = useCallback(() => {
+        NativeCloudX.destroyAppOpen(adUnitId);
+        setIsLoaded(false);
+        setIsLoading(false);
+        setError(null);
+    }, [adUnitId]);
+
+    return { isLoaded, isLoading, error, load, show, destroy };
+}
+
 // ---------------------------------------------------------------------------
 // useCloudXRewarded
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -1,15 +1,26 @@
 // Core SDK
 export { default, CloudX } from './CloudX';
 export { default as NativeCloudX } from './specs/NativeCloudX';
+// The shared NativeEventEmitter every hook subscribes through. Consumers
+// that need raw event access (e.g. logging) should use this instance rather
+// than constructing their own NativeEventEmitter(NativeCloudX).
+export { emitter as cloudXEventEmitter } from './EventEmitter';
 export { CloudXArbiterBid } from './types/Arbiter';
+export { CloudXRevenuePlatform, CloudXRevenuePrecision } from './types/RevenueData';
 
 // Ad Modules
 export { CloudXInterstitialAd } from './CloudXInterstitialAd';
+export { CloudXAppOpenAd } from './CloudXAppOpenAd';
 export { CloudXRewardedAd } from './CloudXRewardedAd';
 export { CloudXBannerAd } from './CloudXBannerAd';
 export { CloudXMRECAd } from './CloudXMRECAd';
 export { CloudXAdPosition } from './CloudXAdPosition';
 
+// Ad View Components (in-tree; layer correctly under app overlays)
+export { CloudXBannerView } from './CloudXBannerView';
+export { CloudXMRECView } from './CloudXMRECView';
+export type { CloudXAdViewProps, CloudXAdViewFormat } from './CloudXAdViewBase';
+
 // Error Codes
 export { CloudXErrorCode } from './CloudXErrorCode';
 
@@ -17,8 +28,13 @@ export { CloudXErrorCode } from './CloudXErrorCode';
 export { requestTrackingAuthorization, getTrackingAuthorizationStatus, CloudXATTStatus } from './AppTrackingTransparency';
 
 // Hooks
-export { useCloudXInterstitial, useCloudXRewarded, useCloudXBanner } from './hooks';
-export type { CloudXInterstitialHookResult, CloudXRewardedHookResult, CloudXBannerHookResult } from './hooks';
+export { useCloudXInterstitial, useCloudXAppOpen, useCloudXRewarded, useCloudXBanner } from './hooks';
+export type {
+    CloudXInterstitialHookResult,
+    CloudXAppOpenHookResult,
+    CloudXRewardedHookResult,
+    CloudXBannerHookResult,
+} from './hooks';
 
 // Types
 export type {
@@ -36,8 +52,12 @@ export type {
     CloudXSDKArbiterBid,
     CloudXLevelPlayArbiterBid,
     CloudXPubMaticArbiterBid,
+    CloudXRevenueData,
+    CloudXRevenuePlatformValue,
+    CloudXRevenuePrecisionValue,
     CloudXFullscreenAdType,
     CloudXInterstitialAdType,
+    CloudXAppOpenAdType,
     CloudXRewardedAdType,
     CloudXViewAdType,
     CloudXBannerAdType,

package/src/specs/CloudXAdViewNativeComponent.ts

@@ -0,0 +1,84 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import type {
+    Double,
+    DirectEventHandler,
+    UnsafeMixed,
+} from 'react-native/Libraries/Types/CodegenTypes';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+
+/**
+ * Payload for ad lifecycle events (load, click, revenue).
+ *
+ * Codegen cannot express `Record<string, string>`, so the SDK-owned ad values
+ * are delivered as a JSON-encoded string in `adValuesJson` and re-parsed into a
+ * map by the JS wrapper before surfacing a CloudXAdInfo to the publisher.
+ */
+export type CloudXAdInfoEvent = Readonly<{
+    adUnitId: string;
+    adFormat: string;
+    networkName: string;
+    networkPlacement?: string | null;
+    placement?: string | null;
+    revenue: Double;
+    adValuesJson?: string | null;
+}>;
+
+/**
+ * Payload for ad load-failure events.
+ */
+export type CloudXAdLoadFailedEvent = Readonly<{
+    adUnitId: string;
+    code: Double;
+    message?: string | null;
+}>;
+
+export type NativeExtraParameterEntry = Readonly<{
+    key: string;
+    value: UnsafeMixed;
+}>;
+
+/**
+ * Props for the native CloudXAdView component (banner + MREC).
+ *
+ * This is the in-tree view component: the ad renders as an ordinary React
+ * Native view, so publisher overlays (toasts, modals) layer above it via
+ * normal RN z-ordering — unlike the imperative overlay banner API.
+ */
+export interface NativeProps extends ViewProps {
+    /** Ad unit ID used to load the ad. */
+    adUnitId: string;
+
+    /*
+     * Ad format: "BANNER" or "MREC". Typed as a plain string because codegen
+     * cannot express union literals ('BANNER' | 'MREC') on native props; the
+     * literal type is enforced upstream at the wrapper layer (CloudXAdViewBase /
+     * CloudXBannerView / CloudXMRECView).
+     */
+    adFormat: string;
+
+    /** Optional placement name for reporting. */
+    placement?: string | null;
+
+    /** Optional custom data string. */
+    customData?: string | null;
+
+    /** Extra parameters applied to the underlying ad view. */
+    extraParameters: ReadonlyArray<NativeExtraParameterEntry>;
+
+    /** Called when an ad is successfully loaded. */
+    onAdLoadedEvent: DirectEventHandler<CloudXAdInfoEvent>;
+
+    /** Called when the SDK fails to load an ad. */
+    onAdLoadFailedEvent: DirectEventHandler<CloudXAdLoadFailedEvent>;
+
+    /** Called when the ad is clicked. */
+    onAdClickedEvent: DirectEventHandler<CloudXAdInfoEvent>;
+
+    /** Called when ad revenue is paid. */
+    onAdRevenuePaidEvent: DirectEventHandler<CloudXAdInfoEvent>;
+}
+
+/**
+ * Native in-tree view component backing CloudXBannerView / CloudXMRECView.
+ */
+export default codegenNativeComponent<NativeProps>('CloudXAdView') as HostComponent<NativeProps>;

package/src/specs/NativeCloudX.ts

@@ -52,6 +52,15 @@ export interface Spec extends TurboModule {
         ON_REWARDED_AD_HIDDEN_EVENT: string;
         ON_REWARDED_AD_RECEIVED_REWARD_EVENT: string;
         ON_REWARDED_AD_REVENUE_PAID: string;
+
+        // App Open events
+        ON_APPOPEN_LOADED_EVENT: string;
+        ON_APPOPEN_LOAD_FAILED_EVENT: string;
+        ON_APPOPEN_CLICKED_EVENT: string;
+        ON_APPOPEN_DISPLAYED_EVENT: string;
+        ON_APPOPEN_DISPLAY_FAILED_EVENT: string;
+        ON_APPOPEN_HIDDEN_EVENT: string;
+        ON_APPOPEN_AD_REVENUE_PAID: string;
     };
 
     // =========================================================================
@@ -92,6 +101,9 @@ export interface Spec extends TurboModule {
 
     arbiter(configuration: UnsafeObject): Promise<UnsafeObject>;
 
+    // Revenue Data
+    reportRevenueData(data: UnsafeObject): Promise<boolean>;
+
     // =========================================================================
     // Banner (Programmatic)
     // =========================================================================
@@ -148,6 +160,16 @@ export interface Spec extends TurboModule {
     showRewarded(adUnitId: string, placement?: string | null, customData?: string | null): void;
     destroyRewarded(adUnitId: string): void;
 
+    // =========================================================================
+    // App Open
+    // =========================================================================
+
+    loadAppOpen(adUnitId: string): void;
+    setAppOpenExtraParameters(adUnitId: string, extraParameters: UnsafeObject): void;
+    isAppOpenReady(adUnitId: string): Promise<boolean>;
+    showAppOpen(adUnitId: string, placement?: string | null, customData?: string | null): void;
+    destroyAppOpen(adUnitId: string): void;
+
     // =========================================================================
     // Event Emitter (required by NativeEventEmitter)
     // =========================================================================

package/src/types/AdProps.ts

@@ -1,4 +1,5 @@
 import type { CloudXAdInfo, CloudXAdLoadFailedInfo } from './AdInfo';
+import type { CloudXExtraParameters } from './ExtraParameters';
 
 /**
  * Base props shared by ad UI components.
@@ -13,6 +14,9 @@ export type CloudXAdProps = {
     /** Custom data string. */
     customData?: string | null;
 
+    /** Extra parameters applied to the underlying ad view. */
+    extraParameters?: CloudXExtraParameters | null;
+
     /** Called when a new ad is successfully loaded. */
     onAdLoaded?: (adInfo: CloudXAdInfo) => void;
 

package/src/types/AppOpenAd.ts

@@ -0,0 +1,8 @@
+import type { CloudXFullscreenAdType } from './FullscreenAd';
+
+/**
+ * App Open ad type — identical to the fullscreen ad interface.
+ * Provides a named type for consumers and a place to add app-open-specific
+ * methods in the future without refactoring.
+ */
+export type CloudXAppOpenAdType = CloudXFullscreenAdType;

package/src/types/CloudX.ts

@@ -1,5 +1,6 @@
 import type { CloudXInitializationResult } from './Configuration';
 import type { CloudXArbiterConfiguration, CloudXArbiterResult } from './Arbiter';
+import type { CloudXRevenueData } from './RevenueData';
 
 export type CloudXLogLevelValue = 'verbose' | 'debug' | 'info' | 'warn' | 'error' | 'none';
 
@@ -57,4 +58,10 @@ export type CloudXType = {
 
     /** Runs CloudX Arbiter using bid data passed through to the native SDK. */
     arbiter(configuration: CloudXArbiterConfiguration): Promise<CloudXArbiterResult>;
+
+    /**
+     * Reports publisher-observed revenue data.
+     * Resolves false when unsupported, invalid, or rejected.
+     */
+    reportRevenueData(data: CloudXRevenueData): Promise<boolean>;
 };

package/src/types/RevenueData.ts

@@ -0,0 +1,39 @@
+export type CloudXRevenuePlatformValue = string;
+
+export const CloudXRevenuePlatform = {
+    ADMOB: 'AdMob',
+    /*
+     * InMobi does not provide a React Native SDK.
+     * INMOBI: 'InMobi',
+     */
+    custom: (name: string): CloudXRevenuePlatformValue => name.trim(),
+} as const;
+
+export const CloudXRevenuePrecision = {
+    EXACT: 'exact',
+    ESTIMATED: 'estimated',
+    PUBLISHER_DEFINED: 'publisher_defined',
+    UNDEFINED: 'undefined',
+} as const;
+
+export type CloudXRevenuePrecisionValue = (typeof CloudXRevenuePrecision)[keyof typeof CloudXRevenuePrecision];
+
+export type CloudXRevenueData = {
+    platform: CloudXRevenuePlatformValue;
+    /**
+     * Revenue for this impression in `currencyCode` units, not micros.
+     *
+     * Example: pass `1.234` for USD 1.234, not `1234000`.
+     */
+    revenue: number;
+    adFormat: string;
+    currencyCode?: string | null;
+    precision?: CloudXRevenuePrecisionValue | null;
+    networkName?: string | null;
+    adUnitId?: string | null;
+    thirdPartyAdPlacementId?: string | null;
+    creativeId?: string | null;
+    networkPlacement?: string | null;
+    countryCode?: string | null;
+    userSegment?: string | null;
+};

package/src/types/index.ts

@@ -10,8 +10,11 @@ export type {
     CloudXLevelPlayArbiterBid,
     CloudXPubMaticArbiterBid,
 } from './Arbiter';
+export { CloudXRevenuePlatform, CloudXRevenuePrecision } from './RevenueData';
+export type { CloudXRevenueData, CloudXRevenuePlatformValue, CloudXRevenuePrecisionValue } from './RevenueData';
 export type { CloudXFullscreenAdType } from './FullscreenAd';
 export type { CloudXInterstitialAdType } from './InterstitialAd';
+export type { CloudXAppOpenAdType } from './AppOpenAd';
 export type { CloudXRewardedAdType } from './RewardedAd';
 export type { CloudXViewAdType } from './ViewAd';
 export type { CloudXBannerAdType } from './BannerAd';

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.4.6';
+export const PLUGIN_VERSION = '3.6.0';