cloudx-react-native 3.4.5 → 3.4.7

package/src/CloudXAdViewBase.tsx

@@ -0,0 +1,293 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { View } from 'react-native';
+import type { NativeSyntheticEvent, StyleProp, ViewProps, ViewStyle } from 'react-native';
+import NativeCloudXAdView from './specs/CloudXAdViewNativeComponent';
+import type {
+    CloudXAdInfoEvent,
+    CloudXAdLoadFailedEvent,
+    NativeExtraParameterEntry,
+} from './specs/CloudXAdViewNativeComponent';
+import NativeCloudX from './specs/NativeCloudX';
+import type { CloudXAdInfo, CloudXAdLoadFailedInfo } from './types/AdInfo';
+import type { CloudXAdProps } from './types/AdProps';
+import type { CloudXErrorCode } from './CloudXErrorCode';
+
+/**
+ * Ad format rendered by the in-tree view component.
+ */
+export type CloudXAdViewFormat = 'BANNER' | 'MREC';
+
+/**
+ * Props shared by CloudXBannerView and CloudXMRECView.
+ */
+export type CloudXAdViewProps = CloudXAdProps & ViewProps;
+
+/** Internal props: the shared base additionally needs the concrete ad format. */
+type CloudXAdViewBaseProps = CloudXAdViewProps & {
+    adFormat: CloudXAdViewFormat;
+};
+
+const AD_SIZE = {
+    banner: { width: 320, height: 50 },
+    leader: { width: 728, height: 90 },
+    mrec: { width: 300, height: 250 },
+};
+
+/*
+ * Tablet status is a device constant, but NativeCloudX.isTablet() is async.
+ * Cache it at module level so only the first banner in a session can flash
+ * phone->leader; every later mount reads the resolved value synchronously.
+ */
+let cachedIsTablet: boolean | null = null;
+
+/*
+ * Once the SDK reports initialized it stays initialized for the JS VM's life,
+ * so cache it module-wide: only the first ad view mounted before init has to
+ * poll + show a placeholder; every later mount renders the native view
+ * immediately. Mirrors cachedIsTablet above.
+ */
+let cachedIsInitialized = false;
+
+const parseAdValues = (json?: string | null): Record<string, string> => {
+    if (!json) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    } catch {
+        return {};
+    }
+};
+
+const toAdInfo = (event: CloudXAdInfoEvent): CloudXAdInfo => ({
+    adUnitId: event.adUnitId,
+    adFormat: event.adFormat,
+    networkName: event.networkName,
+    networkPlacement: event.networkPlacement || null,
+    placement: event.placement || null,
+    revenue: event.revenue ?? 0,
+    adValues: parseAdValues(event.adValuesJson),
+});
+
+const toLoadFailedInfo = (event: CloudXAdLoadFailedEvent): CloudXAdLoadFailedInfo => ({
+    adUnitId: event.adUnitId,
+    code: event.code as CloudXErrorCode,
+    message: event.message || null,
+});
+
+const warnIgnoredUndefinedExtraParameter = (keyPath: string): void => {
+    console.warn(
+        `CloudXAdView ignored extra parameter "${keyPath}" because ` +
+            'undefined values are not supported. Use null when a value is intentional.'
+    );
+};
+
+const normalizeExtraParameterValue = (
+    keyPath: string,
+    value: unknown
+): NativeExtraParameterEntry['value'] | undefined => {
+    if (value === undefined) {
+        warnIgnoredUndefinedExtraParameter(keyPath);
+        return undefined;
+    }
+
+    if (Array.isArray(value)) {
+        return value.reduce<unknown[]>((items, item, index) => {
+            const normalized = normalizeExtraParameterValue(`${keyPath}[${index}]`, item);
+            if (normalized !== undefined) {
+                items.push(normalized);
+            }
+            return items;
+        }, []);
+    }
+
+    if (value !== null && typeof value === 'object') {
+        return Object.entries(value as Record<string, unknown>).reduce<Record<string, unknown>>(
+            (object, [childKey, childValue]) => {
+                const normalized = normalizeExtraParameterValue(`${keyPath}.${childKey}`, childValue);
+                if (normalized !== undefined) {
+                    object[childKey] = normalized;
+                }
+                return object;
+            },
+            {}
+        );
+    }
+
+    return value;
+};
+
+const toNativeExtraParameterEntries = (
+    extraParameters?: CloudXAdProps['extraParameters']
+): ReadonlyArray<NativeExtraParameterEntry> => {
+    if (!extraParameters) {
+        return [];
+    }
+
+    return Object.entries(extraParameters as Record<string, unknown>).reduce<NativeExtraParameterEntry[]>(
+        (entries, [key, value]) => {
+            const normalizedValue = normalizeExtraParameterValue(key, value);
+            if (normalizedValue === undefined) {
+                return entries;
+            }
+
+            entries.push({ key, value: normalizedValue });
+            return entries;
+        },
+        []
+    );
+};
+
+/**
+ * Shared implementation for the in-tree banner/MREC view component. Resolves a
+ * default fixed size (overridable via `style`), wires the native per-view direct
+ * events to the public CloudXAdProps callbacks, and hosts the native ad view.
+ *
+ * Note: overriding `style` with a non-IAB size resizes the host frame, not the
+ * creative - iOS pins the ad view to the host bounds and Android measures the
+ * creative from the host, so the served creative keeps its own standard
+ * dimensions inside the resized frame.
+ */
+export const CloudXAdViewBase: React.FC<CloudXAdViewBaseProps> = ({
+    adFormat,
+    adUnitId,
+    placement,
+    customData,
+    extraParameters,
+    onAdLoaded,
+    onAdLoadFailed,
+    onAdClicked,
+    onAdRevenuePaid,
+    style,
+    ...viewProps
+}) => {
+    const [isTablet, setIsTablet] = useState(cachedIsTablet ?? false);
+    const nativeViewProps = viewProps;
+
+    /*
+     * Gate native ad-view creation on SDK initialization. A view mounted before
+     * CloudX.initialize() completes would create the ad against an uninitialized
+     * SDK - on iOS createBannerWithAdUnitId: returns nil and the view is
+     * permanently dead (no retry, no load-failed event). There is no init event
+     * to subscribe to, so poll isInitialized() until ready, then mount the
+     * native view (which is what delivers adUnitId/adFormat and triggers create).
+     * Mirrors CloudXNativeAdView. Cached module-wide so only the first pre-init
+     * mount pays the placeholder + poll.
+     */
+    const [isInitialized, setIsInitialized] = useState(cachedIsInitialized);
+
+    useEffect(() => {
+        if (cachedIsInitialized) {
+            return;
+        }
+        let cancelled = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let warnedOnce = false;
+        const check = () => {
+            NativeCloudX.isInitialized()
+                .then((ready) => {
+                    if (cancelled) {
+                        return;
+                    }
+                    if (ready) {
+                        cachedIsInitialized = true;
+                        setIsInitialized(true);
+                        return;
+                    }
+                    if (!warnedOnce) {
+                        warnedOnce = true;
+                        console.warn(
+                            'CloudXAdView mounted before CloudX SDK initialization; will render once initialize() completes.'
+                        );
+                    }
+                    timer = setTimeout(check, 1000);
+                })
+                .catch((error) => {
+                    if (cancelled) {
+                        return;
+                    }
+                    console.warn('CloudXAdView failed to read initialization state:', error);
+                    timer = setTimeout(check, 1000);
+                });
+        };
+        check();
+        return () => {
+            cancelled = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+        };
+    }, []);
+
+    useEffect(() => {
+        if (adFormat !== 'BANNER' || cachedIsTablet !== null) {
+            return;
+        }
+        let cancelled = false;
+        NativeCloudX.isTablet()
+            .then((tablet) => {
+                cachedIsTablet = tablet;
+                if (!cancelled) {
+                    setIsTablet(tablet);
+                }
+            })
+            .catch(() => {
+                /* keep phone default on failure */
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [adFormat]);
+
+    const defaultSize = useMemo<ViewStyle>(() => {
+        if (adFormat === 'MREC') {
+            return AD_SIZE.mrec;
+        }
+        return isTablet ? AD_SIZE.leader : AD_SIZE.banner;
+    }, [adFormat, isTablet]);
+
+    const resolvedStyle = useMemo<StyleProp<ViewStyle>>(
+        () => [defaultSize, style],
+        [defaultSize, style]
+    );
+    const nativeExtraParameters = useMemo(
+        () => toNativeExtraParameterEntries(extraParameters),
+        [extraParameters]
+    );
+
+    /*
+     * Until the SDK is initialized, render a sized placeholder that reserves
+     * the ad slot's layout but does NOT mount the native view (so no pre-init
+     * create). Swaps to the real ad view once isInitialized flips true.
+     */
+    if (!isInitialized) {
+        return <View style={resolvedStyle} {...nativeViewProps} />;
+    }
+
+    return (
+        <NativeCloudXAdView
+            {...nativeViewProps}
+            style={resolvedStyle}
+            adUnitId={adUnitId}
+            adFormat={adFormat}
+            placement={placement ?? null}
+            customData={customData ?? null}
+            extraParameters={nativeExtraParameters}
+            onAdLoadedEvent={(e: NativeSyntheticEvent<CloudXAdInfoEvent>) =>
+                onAdLoaded?.(toAdInfo(e.nativeEvent))
+            }
+            onAdLoadFailedEvent={(e: NativeSyntheticEvent<CloudXAdLoadFailedEvent>) =>
+                onAdLoadFailed?.(toLoadFailedInfo(e.nativeEvent))
+            }
+            onAdClickedEvent={(e: NativeSyntheticEvent<CloudXAdInfoEvent>) =>
+                onAdClicked?.(toAdInfo(e.nativeEvent))
+            }
+            onAdRevenuePaidEvent={(e: NativeSyntheticEvent<CloudXAdInfoEvent>) =>
+                onAdRevenuePaid?.(toAdInfo(e.nativeEvent))
+            }
+        />
+    );
+};

package/src/CloudXBannerView.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import { CloudXAdViewBase } from './CloudXAdViewBase';
+import type { CloudXAdViewProps } from './CloudXAdViewBase';
+
+/**
+ * In-tree banner ad component.
+ *
+ * Unlike the imperative `CloudXBannerAd` API (a native overlay above the whole
+ * RN view tree), this renders the banner as an ordinary React Native view, so
+ * app overlays such as toasts layer above it via normal RN z-ordering.
+ *
+ * Defaults to 320x50 on phones and 728x90 on tablets; override via `style`.
+ * Overriding `style` to a non-standard size resizes the host frame, not the
+ * creative - the served banner keeps its own IAB dimensions inside that frame.
+ */
+export const CloudXBannerView: React.FC<CloudXAdViewProps> = (props) => (
+    <CloudXAdViewBase adFormat="BANNER" {...props} />
+);
+
+export default CloudXBannerView;

package/src/CloudXMRECView.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import { CloudXAdViewBase } from './CloudXAdViewBase';
+import type { CloudXAdViewProps } from './CloudXAdViewBase';
+
+/**
+ * In-tree MREC ad component.
+ *
+ * Unlike the imperative `CloudXMRECAd` API (a native overlay above the whole RN
+ * view tree), this renders the MREC as an ordinary React Native view, so app
+ * overlays such as toasts layer above it via normal RN z-ordering.
+ *
+ * Fixed size of 300x250; override via `style`.
+ * Overriding `style` to a non-standard size resizes the host frame, not the
+ * creative - the served MREC keeps its own dimensions inside that frame.
+ */
+export const CloudXMRECView: React.FC<CloudXAdViewProps> = (props) => (
+    <CloudXAdViewBase adFormat="MREC" {...props} />
+);
+
+export default CloudXMRECView;

package/src/index.ts

@@ -10,6 +10,11 @@ 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';
 

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/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/version.ts

@@ -1,3 +1,6 @@
 // Keep PLUGIN_VERSION in sync with the `version` field in package.json.
-// Phase 1 of RELEASE.md bumps both together.
-export const PLUGIN_VERSION = '3.4.4';
+// RELEASE.md Phase 1 bumps both together (see the Version Files table).
+// 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.7';