cloudx-react-native 2.0.0-beta.1

package/src/AdView.tsx

@@ -0,0 +1,213 @@
+import React, { useRef, useState, useEffect, useCallback, useImperativeHandle, forwardRef } from 'react';
+import type { NativeSyntheticEvent, ViewProps } from 'react-native';
+import { View } from 'react-native';
+import NativeAdView, { Commands } from './specs/CloudXAdViewNativeComponent';
+import type { AdInfoEvent, AdErrorEvent } from './specs/CloudXAdViewNativeComponent';
+import NativeCloudXModule from './specs/NativeCloudXModule';
+import type { AdInfo, AdLoadFailedInfo } from './types/AdInfo';
+
+/**
+ * Ad format for the AdView component.
+ */
+export enum AdFormat {
+    BANNER = 'BANNER',
+    MREC = 'MREC',
+}
+
+/**
+ * Position constants for programmatic ad placement.
+ */
+export enum AdViewPosition {
+    TOP_LEFT = 'top_left',
+    TOP_CENTER = 'top_center',
+    TOP_RIGHT = 'top_right',
+    CENTER_LEFT = 'center_left',
+    CENTERED = 'centered',
+    CENTER_RIGHT = 'center_right',
+    BOTTOM_LEFT = 'bottom_left',
+    BOTTOM_CENTER = 'bottom_center',
+    BOTTOM_RIGHT = 'bottom_right',
+}
+
+type SizeRecord = { width: number; height: number };
+
+const ADVIEW_SIZE = {
+    banner: { width: 320, height: 50 },
+    leader: { width: 728, height: 90 },
+    mrec: { width: 300, height: 250 },
+};
+
+/**
+ * Props for the AdView component.
+ */
+export type AdViewProps = {
+    /** The ad unit ID. */
+    adUnitId: string;
+
+    /** The ad format: BANNER or MREC. */
+    adFormat: AdFormat;
+
+    /** Placement name for reporting. */
+    placement?: string | null;
+
+    /** Custom data string. */
+    customData?: string | null;
+
+    /** Whether to automatically refresh. Defaults to true. */
+    autoRefresh?: boolean;
+
+    /** Whether to load the ad on mount. Defaults to true. */
+    loadOnMount?: boolean;
+
+    /** Position for programmatic window-level placement. When set, the banner
+     *  is removed from React layout and added to the app window at the given position. */
+    adPosition?: AdViewPosition | null;
+
+    /** Callbacks */
+    onAdLoaded?: (adInfo: AdInfo) => void;
+    onAdLoadFailed?: (errorInfo: AdLoadFailedInfo) => void;
+    onAdClicked?: (adInfo: AdInfo) => void;
+    onAdExpanded?: (adInfo: AdInfo) => void;
+    onAdCollapsed?: (adInfo: AdInfo) => void;
+    onAdRevenuePaid?: (adInfo: AdInfo) => void;
+};
+
+/**
+ * Imperative handle exposed via ref for AdView control.
+ */
+export type AdViewHandler = {
+    loadAd: () => void;
+    destroy: () => void;
+};
+
+const handleAdViewEvent = <T extends AdInfoEvent | AdErrorEvent>(
+    event: NativeSyntheticEvent<T>,
+    callback?: (data: T) => void,
+) => {
+    if (callback) callback(event.nativeEvent);
+};
+
+/**
+ * React component for displaying CloudX banner or MREC ads.
+ *
+ * - **Banners**: 320×50 on phones, 728×90 on tablets.
+ * - **MRECs**: Fixed 300×250 on all devices.
+ *
+ * Supports both programmatic control via ref and declarative props.
+ */
+export const AdView = forwardRef<AdViewHandler, AdViewProps & ViewProps>(function AdView(
+    {
+        adUnitId,
+        adFormat,
+        placement,
+        customData,
+        autoRefresh = true,
+        loadOnMount = true,
+        adPosition,
+        onAdLoaded,
+        onAdLoadFailed,
+        onAdClicked,
+        onAdExpanded,
+        onAdCollapsed,
+        onAdRevenuePaid,
+        style,
+        ...otherProps
+    },
+    ref,
+) {
+    const nativeRef = useRef<React.ElementRef<typeof NativeAdView>>(null);
+    const [adFormatSize, setAdFormatSize] = useState<SizeRecord>(
+        adFormat === AdFormat.MREC ? ADVIEW_SIZE.mrec : ADVIEW_SIZE.banner,
+    );
+    const [isReady, setIsReady] = useState(false);
+
+    const loadAd = useCallback(() => {
+        nativeRef.current && Commands.loadAd(nativeRef.current);
+    }, []);
+
+    const destroy = useCallback(() => {
+        nativeRef.current && Commands.destroy(nativeRef.current);
+    }, []);
+
+    useImperativeHandle(ref, () => ({ loadAd, destroy }), [loadAd, destroy]);
+
+    useEffect(() => {
+        (async () => {
+            try {
+                const isTablet = adFormat === AdFormat.BANNER ? await NativeCloudXModule.isTablet() : false;
+                setAdFormatSize(
+                    adFormat === AdFormat.MREC
+                        ? ADVIEW_SIZE.mrec
+                        : isTablet
+                          ? ADVIEW_SIZE.leader
+                          : ADVIEW_SIZE.banner,
+                );
+            } catch {
+                console.warn('AdView: isTablet() check failed, defaulting to phone size.');
+            }
+
+            try {
+                const initialized = await NativeCloudXModule.isInitialized();
+                if (!initialized) {
+                    console.warn('AdView was mounted before the CloudX SDK was initialized.');
+                }
+            } catch {
+                console.warn('AdView: isInitialized() check failed.');
+            }
+
+            setIsReady(true);
+        })();
+    }, [adFormat]);
+
+    const onAdLoadedHandler = useCallback(
+        (event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdLoaded),
+        [onAdLoaded],
+    );
+    const onAdLoadFailedHandler = useCallback(
+        (event: NativeSyntheticEvent<AdErrorEvent>) => handleAdViewEvent(event, onAdLoadFailed),
+        [onAdLoadFailed],
+    );
+    const onAdClickedHandler = useCallback(
+        (event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdClicked),
+        [onAdClicked],
+    );
+    const onAdExpandedHandler = useCallback(
+        (event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdExpanded),
+        [onAdExpanded],
+    );
+    const onAdCollapsedHandler = useCallback(
+        (event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdCollapsed),
+        [onAdCollapsed],
+    );
+    const onAdRevenuePaidHandler = useCallback(
+        (event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdRevenuePaid),
+        [onAdRevenuePaid],
+    );
+
+    if (!isReady) {
+        return <View style={style} {...otherProps} />;
+    }
+
+    return (
+        <NativeAdView
+            ref={nativeRef}
+            adUnitId={adUnitId}
+            adFormat={adFormat}
+            placement={placement}
+            customData={customData}
+            autoRefresh={autoRefresh}
+            loadOnMount={loadOnMount}
+            adPosition={adPosition}
+            style={[adFormatSize, style]}
+            onAdLoaded={onAdLoadedHandler}
+            onAdLoadFailed={onAdLoadFailedHandler}
+            onAdClicked={onAdClickedHandler}
+            onAdExpanded={onAdExpandedHandler}
+            onAdCollapsed={onAdCollapsedHandler}
+            onAdRevenuePaid={onAdRevenuePaidHandler}
+            {...otherProps}
+        />
+    );
+});
+
+export default AdView;

package/src/AppTrackingTransparency.ts

@@ -0,0 +1,56 @@
+/**
+ * App Tracking Transparency (ATT) module for iOS 14+.
+ *
+ * Provides methods to request and check tracking authorization status.
+ * On Android or iOS < 14, these methods return safe defaults.
+ */
+
+import { NativeModules, Platform } from 'react-native';
+
+const ATTModule = NativeModules.AppTrackingTransparency;
+
+/**
+ * ATT authorization status values.
+ */
+export enum ATTStatus {
+    AUTHORIZED = 'authorized',
+    DENIED = 'denied',
+    RESTRICTED = 'restricted',
+    NOT_DETERMINED = 'not_determined',
+    NOT_REQUIRED = 'not_required',
+}
+
+/**
+ * Requests App Tracking Transparency permission (iOS 14+).
+ *
+ * On iOS 14+, this shows the system ATT permission dialog.
+ * On iOS < 14 or Android, returns ATTStatus.NOT_REQUIRED.
+ */
+export async function requestTrackingAuthorization(): Promise<ATTStatus> {
+    if (Platform.OS !== 'ios' || !ATTModule) {
+        return ATTStatus.NOT_REQUIRED;
+    }
+
+    try {
+        const status: string = await ATTModule.requestTrackingAuthorization();
+        return status as ATTStatus;
+    } catch (_error) {
+        return ATTStatus.NOT_DETERMINED;
+    }
+}
+
+/**
+ * Gets the current tracking authorization status without showing a dialog.
+ */
+export async function getTrackingAuthorizationStatus(): Promise<ATTStatus> {
+    if (Platform.OS !== 'ios' || !ATTModule) {
+        return ATTStatus.NOT_REQUIRED;
+    }
+
+    try {
+        const status: string = await ATTModule.getTrackingAuthorizationStatus();
+        return status as ATTStatus;
+    } catch (_error) {
+        return ATTStatus.NOT_DETERMINED;
+    }
+}

package/src/BannerAd.ts

@@ -0,0 +1,133 @@
+import { addEventListener, removeEventListener } from './EventEmitter';
+import type { AdInfo, AdLoadFailedInfo } from './types/AdInfo';
+import type { BannerAdType, AdViewPositionType } from './types/BannerAd';
+import NativeCloudXModule from './specs/NativeCloudXModule';
+
+const {
+    ON_BANNER_AD_LOADED_EVENT,
+    ON_BANNER_AD_LOAD_FAILED_EVENT,
+    ON_BANNER_AD_CLICKED_EVENT,
+    ON_BANNER_AD_EXPANDED_EVENT,
+    ON_BANNER_AD_COLLAPSED_EVENT,
+    ON_BANNER_AD_REVENUE_PAID,
+} = NativeCloudXModule.getConstants();
+
+const createAd = (adUnitId: string, position: AdViewPositionType): void => {
+    NativeCloudXModule.createBanner(adUnitId, position);
+};
+
+const createAdWithOffsets = (adUnitId: string, position: AdViewPositionType, xOffset: number, yOffset: number): void => {
+    NativeCloudXModule.createBannerWithOffsets(adUnitId, position, xOffset, yOffset);
+};
+
+const destroyAd = (adUnitId: string): void => {
+    NativeCloudXModule.destroyBanner(adUnitId);
+};
+
+const showAd = (adUnitId: string): void => {
+    NativeCloudXModule.showBanner(adUnitId);
+};
+
+const hideAd = (adUnitId: string): void => {
+    NativeCloudXModule.hideBanner(adUnitId);
+};
+
+const setPlacement = (adUnitId: string, placement: string | null): void => {
+    NativeCloudXModule.setBannerPlacement(adUnitId, placement);
+};
+
+const setCustomData = (adUnitId: string, customData: string | null): void => {
+    NativeCloudXModule.setBannerCustomData(adUnitId, customData);
+};
+
+const startAutoRefresh = (adUnitId: string): void => {
+    NativeCloudXModule.startBannerAutoRefresh(adUnitId);
+};
+
+const stopAutoRefresh = (adUnitId: string): void => {
+    NativeCloudXModule.stopBannerAutoRefresh(adUnitId);
+};
+
+const updatePosition = (adUnitId: string, position: AdViewPositionType): void => {
+    NativeCloudXModule.updateBannerPosition(adUnitId, position);
+};
+
+const updateOffsets = (adUnitId: string, xOffset: number, yOffset: number): void => {
+    NativeCloudXModule.updateBannerOffsets(adUnitId, xOffset, yOffset);
+};
+
+const setBackgroundColor = (adUnitId: string, hexColorString: string): void => {
+    NativeCloudXModule.setBannerBackgroundColor(adUnitId, hexColorString);
+};
+
+const addAdLoadedEventListener = (listener: (adInfo: AdInfo) => void): void => {
+    addEventListener(ON_BANNER_AD_LOADED_EVENT, listener);
+};
+const removeAdLoadedEventListener = (): void => {
+    removeEventListener(ON_BANNER_AD_LOADED_EVENT);
+};
+
+const addAdLoadFailedEventListener = (listener: (errorInfo: AdLoadFailedInfo) => void): void => {
+    addEventListener(ON_BANNER_AD_LOAD_FAILED_EVENT, listener);
+};
+const removeAdLoadFailedEventListener = (): void => {
+    removeEventListener(ON_BANNER_AD_LOAD_FAILED_EVENT);
+};
+
+const addAdClickedEventListener = (listener: (adInfo: AdInfo) => void): void => {
+    addEventListener(ON_BANNER_AD_CLICKED_EVENT, listener);
+};
+const removeAdClickedEventListener = (): void => {
+    removeEventListener(ON_BANNER_AD_CLICKED_EVENT);
+};
+
+const addAdExpandedEventListener = (listener: (adInfo: AdInfo) => void): void => {
+    addEventListener(ON_BANNER_AD_EXPANDED_EVENT, listener);
+};
+const removeAdExpandedEventListener = (): void => {
+    removeEventListener(ON_BANNER_AD_EXPANDED_EVENT);
+};
+
+const addAdCollapsedEventListener = (listener: (adInfo: AdInfo) => void): void => {
+    addEventListener(ON_BANNER_AD_COLLAPSED_EVENT, listener);
+};
+const removeAdCollapsedEventListener = (): void => {
+    removeEventListener(ON_BANNER_AD_COLLAPSED_EVENT);
+};
+
+const addAdRevenuePaidListener = (listener: (adInfo: AdInfo) => void): void => {
+    addEventListener(ON_BANNER_AD_REVENUE_PAID, listener);
+};
+const removeAdRevenuePaidListener = (): void => {
+    removeEventListener(ON_BANNER_AD_REVENUE_PAID);
+};
+
+export const BannerAd: BannerAdType = {
+    createAd,
+    createAdWithOffsets,
+    destroyAd,
+    showAd,
+    hideAd,
+    updatePosition,
+    updateOffsets,
+    setBackgroundColor,
+    setPlacement,
+    setCustomData,
+    startAutoRefresh,
+    stopAutoRefresh,
+
+    addAdLoadedEventListener,
+    removeAdLoadedEventListener,
+    addAdLoadFailedEventListener,
+    removeAdLoadFailedEventListener,
+    addAdClickedEventListener,
+    removeAdClickedEventListener,
+    addAdExpandedEventListener,
+    removeAdExpandedEventListener,
+    addAdCollapsedEventListener,
+    removeAdCollapsedEventListener,
+    addAdRevenuePaidListener,
+    removeAdRevenuePaidListener,
+};
+
+export default BannerAd;

package/src/CloudX.ts

@@ -0,0 +1,55 @@
+import type { CloudXType } from './types/CloudX';
+import type { Configuration } from './types/Configuration';
+import NativeCloudXModule from './specs/NativeCloudXModule';
+
+const VERSION = '2.0.0';
+
+const initialize = (appKey: string): Promise<Configuration> => {
+    return NativeCloudXModule.initialize(VERSION, appKey) as Promise<Configuration>;
+};
+
+const isInitialized = (): Promise<boolean> => {
+    return NativeCloudXModule.isInitialized();
+};
+
+const getVersion = (): Promise<string> => {
+    return NativeCloudXModule.getVersion();
+};
+
+const setMinLogLevel = (level: string): void => {
+    NativeCloudXModule.setMinLogLevel(level);
+};
+
+const setHashedUserID = (hashedUserID: string): void => {
+    NativeCloudXModule.setHashedUserID(hashedUserID);
+};
+
+const setUserKeyValue = (key: string, value: string): void => {
+    NativeCloudXModule.setUserKeyValue(key, value);
+};
+
+const setAppKeyValue = (key: string, value: string): void => {
+    NativeCloudXModule.setAppKeyValue(key, value);
+};
+
+const clearAllKeyValues = (): void => {
+    NativeCloudXModule.clearAllKeyValues();
+};
+
+const setVisualDebuggingEnabled = (enabled: boolean): void => {
+    NativeCloudXModule.setVisualDebuggingEnabled(enabled);
+};
+
+export const CloudX: CloudXType = {
+    initialize,
+    isInitialized,
+    getVersion,
+    setMinLogLevel,
+    setHashedUserID,
+    setUserKeyValue,
+    setAppKeyValue,
+    clearAllKeyValues,
+    setVisualDebuggingEnabled,
+};
+
+export default CloudX;

package/src/ErrorCode.ts

@@ -0,0 +1,157 @@
+/**
+ * Error codes for CloudX SDK — values match the native CLXErrorCode (iOS)
+ * and CloudXErrorCode (Android) enumerations exactly.
+ *
+ * Code ranges:
+ *   0-99   General errors
+ * 100-199  Network and connectivity errors
+ * 200-299  SDK initialization errors
+ * 300-399  Ad request / loading errors
+ * 400-499  Ad display / presentation errors
+ * 500-599  Configuration / setup errors
+ * 600-699  Adapter-level errors
+ */
+export enum ErrorCode {
+    // GENERAL (0-99)
+
+    /** An internal error occurred. */
+    INTERNAL_ERROR = 0,
+
+    // NETWORK (100-199)
+
+    /** General network error. */
+    NETWORK_ERROR = 100,
+
+    /** Network request timed out. */
+    NETWORK_TIMEOUT = 101,
+
+    /** Server error (5xx). */
+    SERVER_ERROR = 102,
+
+    /** Client error (4xx). */
+    CLIENT_ERROR = 103,
+
+    /** Rate limited (429). */
+    TOO_MANY_REQUESTS = 104,
+
+    /** Invalid or unparseable server response. */
+    INVALID_RESPONSE = 105,
+
+    /** No network connectivity. */
+    NO_CONNECTION = 106,
+
+    // INITIALIZATION (200-299)
+
+    /** SDK is not initialized. Call CloudX.initialize() first. */
+    NOT_INITIALIZED = 200,
+
+    /** No ad adapters/networks found. */
+    NO_ADAPTERS_FOUND = 201,
+
+    /** No ad networks configured for this app. */
+    NO_NETWORKS_CONFIGURED = 202,
+
+    /** Invalid app key provided. */
+    INVALID_APP_KEY = 203,
+
+    /** SDK disabled by server configuration. */
+    SDK_DISABLED = 204,
+
+    // AD REQUEST / LOADING (300-399)
+
+    /** Invalid ad unit ID. */
+    INVALID_AD_UNIT = 300,
+
+    /** Ads disabled for this ad unit. */
+    ADS_DISABLED = 301,
+
+    /** No ad available (no fill). */
+    NO_FILL = 302,
+
+    /** Ad failed to load. */
+    LOAD_FAILED = 304,
+
+    // AD DISPLAY / SHOW (400-499)
+
+    /** Ad is not ready to be shown. */
+    AD_NOT_READY = 400,
+
+    /** Another fullscreen ad is already showing. */
+    AD_ALREADY_SHOWING = 401,
+
+    /** Android "Don't keep activities" setting is enabled (Android only). */
+    DONT_KEEP_ACTIVITIES_ENABLED = 402,
+
+    // CONFIGURATION (500-599)
+
+    /** Native view is nil or invalid. */
+    INVALID_NATIVE_VIEW = 500,
+
+    // ADAPTER (600-699)
+
+    /** Internal error in an ad network adapter. */
+    ADAPTER_INTERNAL_ERROR = 600,
+
+    /** Adapter returned no fill. */
+    ADAPTER_NO_FILL = 601,
+
+    /** Adapter reported an invalid load state. */
+    ADAPTER_INVALID_LOAD_STATE = 602,
+
+    /** Adapter has an invalid configuration. */
+    ADAPTER_INVALID_CONFIGURATION = 603,
+
+    /** Adapter received invalid server extras. */
+    ADAPTER_INVALID_SERVER_EXTRAS = 604,
+
+    /** Adapter rejected the ad request. */
+    ADAPTER_BAD_REQUEST = 605,
+
+    /** Adapter is not initialized. */
+    ADAPTER_NOT_INITIALIZED = 606,
+
+    /** Adapter failed to initialize. */
+    ADAPTER_INITIALIZATION_ERROR = 607,
+
+    /** Adapter ad is not ready. */
+    ADAPTER_AD_NOT_READY = 608,
+
+    /** Adapter load timed out. */
+    ADAPTER_LOAD_TIMEOUT = 609,
+
+    /** Adapter operation timed out. */
+    ADAPTER_TIMEOUT = 610,
+
+    /** Adapter has no network connection. */
+    ADAPTER_NO_CONNECTION = 611,
+
+    /** Adapter server error. */
+    ADAPTER_SERVER_ERROR = 612,
+
+    /** Adapter bid token request timed out. */
+    ADAPTER_BID_TOKEN_TIMEOUT = 613,
+
+    /** Adapter does not support bid tokens. */
+    ADAPTER_BID_TOKEN_NOT_SUPPORTED = 614,
+
+    /** Adapter encountered a WebView error. */
+    ADAPTER_WEBVIEW_ERROR = 615,
+
+    /** Adapter ad has expired. */
+    ADAPTER_AD_EXPIRED = 616,
+
+    /** Adapter ad is frequency capped. */
+    ADAPTER_AD_FREQUENCY_CAPPED = 617,
+
+    /** Adapter reward error. */
+    ADAPTER_REWARD_ERROR = 618,
+
+    /** Adapter is missing native ad assets. */
+    ADAPTER_MISSING_NATIVE_AD_ASSETS = 619,
+
+    /** Adapter is missing the required activity (Android) or view controller (iOS). */
+    ADAPTER_MISSING_VIEW_CONTROLLER = 620,
+
+    /** Adapter failed to display the ad. */
+    ADAPTER_DISPLAY_FAILED = 621,
+}

package/src/EventEmitter.ts

@@ -0,0 +1,38 @@
+/**
+ * Manages CloudX ad event listeners using a shared NativeEventEmitter.
+ * Ensures only one active subscription per event type at any given time,
+ * following the singleton listener pattern.
+ */
+
+import { NativeEventEmitter } from 'react-native';
+import type { EventSubscription } from 'react-native';
+import type { AdEventObject, AdEventListener } from './types/AdEvent';
+import NativeCloudXModule from './specs/NativeCloudXModule';
+
+const emitter = new NativeEventEmitter(NativeCloudXModule);
+
+const subscriptions: Record<string, EventSubscription> = {};
+
+/**
+ * Subscribes to a specific ad event.
+ * If a listener already exists for the event, it will be replaced.
+ */
+export const addEventListener = <T extends AdEventObject>(event: string, handler: AdEventListener<T>): void => {
+    const subscription = emitter.addListener(event, handler);
+    const currentSubscription = subscriptions[event];
+    if (currentSubscription) {
+        currentSubscription.remove();
+    }
+    subscriptions[event] = subscription;
+};
+
+/**
+ * Unsubscribes from a specific ad event, if a listener exists.
+ */
+export const removeEventListener = (event: string): void => {
+    const currentSubscription = subscriptions[event];
+    if (currentSubscription) {
+        currentSubscription.remove();
+        delete subscriptions[event];
+    }
+};