react-native-applovin-max 8.2.0 → 9.1.0

package/src/ErrorCode.ts

@@ -1,6 +1,4 @@
-import { NativeModules } from 'react-native';
-
-const { AppLovinMAX } = NativeModules;
+import AppLovinMAX from './specs/NativeAppLovinMAXModule';
 
 const {
     MAX_ERROR_CODE_UNSPECIFIED,
@@ -18,85 +16,78 @@ const {
 } = AppLovinMAX.getConstants();
 
 /**
- * This enum contains various error codes that the SDK can return when a MAX ad fails to load or
- * display.
+ * Error codes returned by the AppLovin MAX SDK when an ad fails to load or display.
  */
 export enum ErrorCode {
     /**
-     * This error code represents an error that could not be categorized into one of the other defined
-     * errors. See the message field in the error object for more details.
+     * An unspecified error occurred.
+     * See the `message` field for more details.
      */
     UNSPECIFIED = MAX_ERROR_CODE_UNSPECIFIED,
 
     /**
-     * This error code indicates that MAX returned no eligible ads from any mediated networks for this
-     * app/device.
+     * No eligible ads were returned from any mediated networks.
      */
     NO_FILL = MAX_ERROR_CODE_NO_FILL,
 
     /**
-     * This error code indicates that MAX returned eligible ads from mediated networks, but all ads
-     * failed to load. See the adLoadFailureInfo field in the error object for more details.
+     * Eligible ads were returned but all failed to load.
+     * See `adLoadFailureInfo` for more details.
      */
     AD_LOAD_FAILED = MAX_ERROR_CODE_AD_LOAD_FAILED,
 
     /**
-     * This error code represents an error that was encountered when showing an ad.
+     * An error occurred while attempting to display the ad.
      */
     AD_DISPLAY_FAILED = MAX_ERROR_CODE_AD_DISPLAY_FAILED,
 
     /**
-     * This error code indicates that the ad request failed due to a generic network error. See the
-     * message field in the error object for more details.
+     * The ad request failed due to a general network issue.
+     * See the `message` field for details.
      */
     NETWORK_ERROR = MAX_ERROR_CODE_NETWORK_ERROR,
 
     /**
-     * This error code indicates that the ad request timed out due to a slow internet connection.
+     * The ad request timed out, likely due to a slow internet connection.
      */
     NETWORK_TIMEOUT = MAX_ERROR_CODE_NETWORK_TIMEOUT,
 
     /**
-     * This error code indicates that the ad request failed because the device is not connected to the
-     * internet.
+     * The ad request failed because the device was offline.
      */
     NO_NETWORK = MAX_ERROR_CODE_NO_NETWORK,
 
     /**
-     * This error code indicates that you attempted to show a fullscreen ad while another fullscreen ad
-     * is still showing.
+     * A fullscreen ad was requested while another one was already showing.
      */
     FULLSCREEN_AD_ALREADY_SHOWING = MAX_ERROR_CODE_FULLSCREEN_AD_ALREADY_SHOWING,
 
     /**
-     * This error code indicates you are attempting to show a fullscreen ad before the one has been
-     * loaded.
+     * A fullscreen ad was requested before it had finished loading.
      */
     FULLSCREEN_AD_NOT_READY = MAX_ERROR_CODE_FULLSCREEN_AD_NOT_READY,
 
     /**
-     * This error code indicates you attempted to present a fullscreen ad from an invalid view
-     * controller.
-     * **iOS ONLY**.
+     * The ad was presented from an invalid view controller.
+     * **iOS only**.
      */
     FULLSCREEN_AD_INVALID_VIEW_CONTROLLER = MAX_ERROR_CODE_FULLSCREEN_AD_INVALID_VIEW_CONTROLLER,
 
     /**
-     * This error code indicates that the SDK failed to display an ad because the user has the
-     * "Don't Keep Activities" developer setting enabled.
-     * **Android ONLY**.
+     * The SDK was unable to display the ad because the
+     * "Don't Keep Activities" developer setting is enabled.
+     * **Android only**.
      */
     DONT_KEEP_ACTIVITIES_ENABLED = MAX_ERROR_CODE_DONT_KEEP_ACTIVITIES_ENABLED,
 
     /**
-     * This error code indicates that the SDK failed to load an ad because the publisher provided an
-     * invalid ad unit identifier.
+     * The ad failed to load due to an invalid ad unit identifier.
      *
-     * Possible reasons for an invalid ad unit identifier:
-     * 1. Ad unit identifier is malformed or does not exist.
-     * 2. Ad unit is disabled.
-     * 3. Ad unit is not associated with the current app's package name.
-     * 4. Ad unit was created within the last 30-60 minutes.
+     * Possible causes:
+     * 1. The ad unit ID is malformed or does not exist.
+     * 2. The ad unit is disabled.
+     * 3. The ad unit is not linked to the current app’s package name.
+     * 4. The ad unit was recently created (less than ~30–60 minutes ago).
      */
     INVALID_AD_UNIT_ID = MAX_ERROR_CODE_INVALID_AD_UNIT_ID,
 }

package/src/EventEmitter.ts

@@ -1,16 +1,28 @@
-import { NativeModules, NativeEventEmitter } from 'react-native';
+/**
+ * Manages AppLovin MAX ad event listeners using a shared NativeEventEmitter.
+ * Ensures only one active subscription per event type at any given time.
+ */
+
+import { NativeEventEmitter } from 'react-native';
 import type { EventSubscription } from 'react-native';
 import type { AdEventObject, AdEventListener } from './types/AdEvent';
+import AppLovinMAX from './specs/NativeAppLovinMAXModule';
 
-const { AppLovinMAX } = NativeModules;
-
-// Note that this is a singleton in ES6 module
+// Singleton event emitter for AppLovin MAX native events.
 const emitter = new NativeEventEmitter(AppLovinMAX);
 
+// Tracks active subscriptions by event type.
 const subscriptions: Record<string, EventSubscription> = {};
 
+/**
+ * Subscribes to a specific ad event.
+ * If a listener already exists for the event, it will be replaced.
+ *
+ * @param event - The event name to listen for.
+ * @param handler - The callback to handle the event.
+ */
 export const addEventListener = <T extends AdEventObject>(event: string, handler: AdEventListener<T>): void => {
-    const subscription: EventSubscription = emitter.addListener(event, handler);
+    const subscription = emitter.addListener(event, handler);
     const currentSubscription = subscriptions[event];
     if (currentSubscription) {
         currentSubscription.remove();
@@ -18,6 +30,11 @@ export const addEventListener = <T extends AdEventObject>(event: string, handler
     subscriptions[event] = subscription;
 };
 
+/**
+ * Unsubscribes from a specific ad event, if a listener exists.
+ *
+ * @param event - The event name to unsubscribe from.
+ */
 export const removeEventListener = (event: string): void => {
     const currentSubscription = subscriptions[event];
     if (currentSubscription) {

package/src/InterstitialAd.ts

@@ -1,10 +1,8 @@
-import { NativeModules } from 'react-native';
 import { addEventListener, removeEventListener } from './EventEmitter';
 import type { AdDisplayFailedInfo, AdInfo, AdLoadFailedInfo } from './types/AdInfo';
 import type { LocalExtraParameterValue } from './types/AdProps';
 import type { InterstitialAdType } from './types/InterstitialAd';
-
-const { AppLovinMAX } = NativeModules;
+import AppLovinMAX from './specs/NativeAppLovinMAXModule';
 
 const {
     ON_INTERSTITIAL_LOADED_EVENT,
@@ -25,7 +23,7 @@ const loadAd = (adUnitId: string): void => {
 };
 
 const showAd = (adUnitId: string, placement?: string | null, customData?: string | null): void => {
-    AppLovinMAX.showInterstitial(adUnitId, placement ?? null, customData ?? null);
+    AppLovinMAX.showInterstitial(adUnitId, placement ?? undefined, customData ?? undefined);
 };
 
 const setExtraParameter = (adUnitId: string, key: string, value: string | null): void => {

package/src/MRecAd.ts

@@ -1,11 +1,9 @@
-import { NativeModules } from 'react-native';
 import { addEventListener, removeEventListener } from './EventEmitter';
 import type { AdInfo, AdLoadFailedInfo } from './types/AdInfo';
 import type { LocalExtraParameterValue } from './types/AdProps';
 import type { MRecAdType } from './types/MRecAd';
 import type { AdViewPosition } from './AdView';
-
-const { AppLovinMAX } = NativeModules;
+import AppLovinMAX from './specs/NativeAppLovinMAXModule';
 
 const { ON_MREC_AD_LOADED_EVENT, ON_MREC_AD_LOAD_FAILED_EVENT, ON_MREC_AD_CLICKED_EVENT, ON_MREC_AD_COLLAPSED_EVENT, ON_MREC_AD_EXPANDED_EVENT, ON_MREC_AD_REVENUE_PAID } =
     AppLovinMAX.getConstants();

package/src/Privacy.ts

@@ -1,6 +1,4 @@
-import { NativeModules } from 'react-native';
 import type { PrivacyType } from './types/Privacy';
-
-const { AppLovinMAX } = NativeModules;
+import AppLovinMAX from './specs/NativeAppLovinMAXModule';
 
 export const Privacy: PrivacyType = AppLovinMAX;

package/src/RewardedAd.ts

@@ -1,10 +1,8 @@
-import { NativeModules } from 'react-native';
 import { addEventListener, removeEventListener } from './EventEmitter';
 import type { AdDisplayFailedInfo, AdInfo, AdLoadFailedInfo, AdRewardInfo } from './types/AdInfo';
 import type { LocalExtraParameterValue } from './types/AdProps';
 import type { RewardedAdType } from './types/RewardedAd';
-
-const { AppLovinMAX } = NativeModules;
+import AppLovinMAX from './specs/NativeAppLovinMAXModule';
 
 const {
     ON_REWARDED_AD_LOADED_EVENT,
@@ -26,7 +24,7 @@ const loadAd = (adUnitId: string): void => {
 };
 
 const showAd = (adUnitId: string, placement?: string | null, customData?: string | null): void => {
-    AppLovinMAX.showRewardedAd(adUnitId, placement ?? null, customData ?? null);
+    AppLovinMAX.showRewardedAd(adUnitId, placement ?? undefined, customData ?? undefined);
 };
 
 const setExtraParameter = (adUnitId: string, key: string, value: string | null): void => {

package/src/Utils.ts

@@ -0,0 +1,45 @@
+import type { LocalExtraParameterValue } from './types/AdProps';
+
+/**
+ * Converts a record of string-based extra parameters into an array of `{ key, value }` objects.
+ * Used for sending extra parameters to the native SDK.
+ *
+ * @param input - An optional map of key-value string pairs (or null values).
+ * @returns An array of `{ key, value }` objects. Returns an empty array if input is undefined.
+ */
+export const makeExtraParametersArray = (input?: Record<string, string | null>): { key: string; value: string | null }[] => {
+    if (!input) return [];
+
+    return Object.entries(input).map(([key, value]) => ({ key, value }));
+};
+
+type LocalExtraParameterType = 'str' | 'bool';
+
+type LocalExtraParameterValueMap = {
+    str: string | null;
+    bool: boolean | null;
+};
+
+/**
+ * Converts a map of local extra parameters into a filtered array of `{ key, value }` pairs.
+ * Only values matching the specified type (`'str'` or `'bool'`) are included.
+ *
+ * @param input - A record of local extra parameters (string, boolean, or null).
+ * @param type - The expected type of each value: `'str'` for strings, `'bool'` for booleans.
+ * @returns A filtered array of `{ key, value }` objects, cast to the specified type.
+ */
+export const makeLocalExtraParametersArray = <T extends LocalExtraParameterType>(
+    input: Record<string, LocalExtraParameterValue> | undefined,
+    type: T
+): { key: string; value: LocalExtraParameterValueMap[T] }[] => {
+    if (!input) return [];
+
+    return Object.entries(input)
+        .filter(([_, value]) => {
+            if (value === null) return true;
+            if (type === 'str') return typeof value === 'string';
+            if (type === 'bool') return typeof value === 'boolean';
+            return false;
+        })
+        .map(([key, value]) => ({ key, value: value as LocalExtraParameterValueMap[T] }));
+};

package/src/nativeAd/NativeAdView.tsx

@@ -1,28 +1,22 @@
+/**
+ * Provides the NativeAdView component, which manages loading and rendering of native ads using the
+ * AppLovin MAX SDK in React Native.
+ */
+
 import * as React from 'react';
 import { forwardRef, useContext, useImperativeHandle, useRef, useState, useEffect, useCallback } from 'react';
-import { NativeModules, requireNativeComponent, UIManager, findNodeHandle, View } from 'react-native';
-import type { ViewProps } from 'react-native';
+import { findNodeHandle, View } from 'react-native';
+import type { NativeSyntheticEvent, ViewProps } from 'react-native';
+import AppLovinMAX from '../specs/NativeAppLovinMAXModule';
+import NativeAdViewComponent, { Commands } from '../specs/AppLovinMAXNativeAdViewNativeComponent';
+import type { AdInfoEvent, AdLoadFailedEvent } from '../specs/AppLovinMAXNativeAdViewNativeComponent';
 import { NativeAdViewContext, NativeAdViewProvider } from './NativeAdViewProvider';
-import type { AdInfo, AdLoadFailedInfo } from '../types/AdInfo';
-import type { AdNativeEvent } from '../types/AdEvent';
-import type { NativeAd } from '../types/NativeAd';
+import type { NativeAdViewContextType } from './NativeAdViewProvider';
 import type { NativeAdViewHandler, NativeAdViewProps } from '../types/NativeAdViewProps';
-import type { NativeAdViewType, NativeAdViewContextType } from './NativeAdViewProvider';
-
-const { AppLovinMAX } = NativeModules;
-
-type NativeAdViewNativeEvents = {
-    onAdLoadedEvent(event: { nativeEvent: { nativeAd: NativeAd; adInfo: AdInfo } }): void;
-    onAdLoadFailedEvent(event: AdNativeEvent<AdLoadFailedInfo>): void;
-    onAdClickedEvent(event: AdNativeEvent<AdInfo>): void;
-    onAdRevenuePaidEvent(event: AdNativeEvent<AdInfo>): void;
-};
-
-const NativeAdViewComponent = requireNativeComponent<NativeAdViewProps & ViewProps & NativeAdViewNativeEvents>('AppLovinMAXNativeAdView');
+import { makeExtraParametersArray, makeLocalExtraParametersArray } from '../Utils';
 
 /**
- * The {@link NativeAdView} component that you use building a native ad. This loads a native ad and
- * renders it with the asset views:
+ * The {@link NativeAdView} component renders a native ad and binds it to asset views:
  *
  * - {@link IconView}
  * - {@link TitleView}
@@ -32,19 +26,21 @@ const NativeAdViewComponent = requireNativeComponent<NativeAdViewProps & ViewPro
  * - {@link MediaView}
  * - {@link CallToActionView}
  *
- * {@link NativeAdView} fills each asset view with the data of a native ad as soon as it loads the native
- * ad, but you need to provide the layout and style of the asset views.
- * {@link NativeAdView} can reload a new native ad by using the ref handler.
+ * Each asset view must be manually laid out and styled.
+ * The component automatically populates content once an ad is loaded.
+ * You can reload the ad using the component’s ref via `loadAd()`.
+ *
+ * **Note:** The AppLovin SDK must be initialized before using this component.
  *
  * ### Example:
- * ```js
+ * ```tsx
  * <NativeAdView
  *   ref={nativeAdViewHandler}
  *   adUnitId={adUnitId}
  *   style={styles.nativead}
  *   onAdLoaded={(adInfo: AdInfo) => { ... }}
  * >
- *   <View style={ ... }>
+ *   <View style={...}>
  *     <IconView style={styles.icon} />
  *     <TitleView style={styles.title} />
  *     <AdvertiserView style={styles.advertiser} />
@@ -56,20 +52,21 @@ const NativeAdViewComponent = requireNativeComponent<NativeAdViewProps & ViewPro
  *   </View>
  * </NativeAdView>
  * ```
+ *
+ * For a complete implementation example, see:
+ * https://github.com/AppLovin/AppLovin-MAX-React-Native/blob/master/example/src/NativeAdViewExample.tsx
  */
 export const NativeAdView = forwardRef<NativeAdViewHandler, NativeAdViewProps & ViewProps>(function NativeAdView(props, ref) {
     const [isInitialized, setIsInitialized] = useState<boolean>(false);
 
     useEffect(() => {
-        const checkInitialization = async () => {
+        (async () => {
             const result = await AppLovinMAX.isInitialized();
             setIsInitialized(result);
             if (!result) {
                 console.warn('NativeAdView is mounted before the initialization of the AppLovin MAX React Native module.');
             }
-        };
-
-        checkInitialization();
+        })();
     }, []);
 
     // Avoid rendering the NativeAdView if the SDK is not initialized
@@ -84,76 +81,89 @@ export const NativeAdView = forwardRef<NativeAdViewHandler, NativeAdViewProps &
     );
 });
 
+/**
+ * Extracts native ad info from a synthetic event and invokes the provided callback, if any.
+ * Ensures optional native ad fields have fallback defaults.
+ */
+const handleNativeAdViewEvent = <T extends AdInfoEvent | AdLoadFailedEvent>(event: NativeSyntheticEvent<T>, callback?: (adInfo: T) => void) => {
+    if (!callback) return;
+    callback(event.nativeEvent);
+};
+
 const NativeAdViewImpl = forwardRef<NativeAdViewHandler, NativeAdViewProps & ViewProps>(function NativeAdViewImpl(
     { adUnitId, placement, customData, extraParameters, localExtraParameters, onAdLoaded, onAdLoadFailed, onAdClicked, onAdRevenuePaid, children, style, ...otherProps },
     ref
 ) {
     // Context provides functions to manage native ad and native ad view state
-    const { setNativeAd, setNativeAdView } = useContext(NativeAdViewContext) as NativeAdViewContextType;
+    const { titleRef, advertiserRef, bodyRef, callToActionRef, imageRef, optionViewRef, mediaViewRef, setNativeAd } = useContext(NativeAdViewContext) as NativeAdViewContextType;
 
-    const nativeAdViewRef = useRef<NativeAdViewType | null>(null);
+    const nativeAdViewRef = useRef<React.ElementRef<typeof NativeAdViewComponent> | undefined>();
 
-    // Load a new ad
+    // Triggers a native ad load via the native command
     const loadAd = useCallback(() => {
-        const nativeAdView = nativeAdViewRef.current;
-        if (nativeAdView) {
-            const viewManagerConfig = UIManager.getViewManagerConfig('AppLovinMAXNativeAdView');
-            if (viewManagerConfig?.Commands && typeof viewManagerConfig.Commands.loadAd === 'number') {
-                UIManager.dispatchViewManagerCommand(findNodeHandle(nativeAdView), viewManagerConfig.Commands.loadAd, []);
-            }
-        }
+        nativeAdViewRef.current && Commands.loadAd(nativeAdViewRef.current);
     }, []);
 
     useImperativeHandle(ref, () => ({ loadAd }), [loadAd]);
 
-    // Save the DOM element reference
-    const saveElement = useCallback(
-        (element: NativeAdViewType | null) => {
-            if (element) {
-                nativeAdViewRef.current = element;
-                setNativeAdView(element);
-            }
-        },
-        [setNativeAdView]
-    );
+    /**
+     * Updates the native asset view binding for a given view type (e.g., TitleView, MediaView).
+     */
+    const updateAssetView = useCallback((assetViewRef: React.RefObject<View>, type: string) => {
+        if (!nativeAdViewRef.current || !assetViewRef.current) return;
+
+        const node = findNodeHandle(assetViewRef.current);
+        if (node) {
+            Commands.updateAssetView(nativeAdViewRef.current, node, type);
+        }
+    }, []);
 
+    /**
+     * Handles native ad load event:
+     * - Updates context with the new native ad data
+     * - Notifies native module of updated asset view mappings
+     * - Triggers native rendering after all asset views are registered
+     */
     const onAdLoadedEvent = useCallback(
-        (event: { nativeEvent: { nativeAd: NativeAd; adInfo: AdInfo } }) => {
-            setNativeAd(event.nativeEvent.nativeAd);
-            onAdLoaded?.(event.nativeEvent.adInfo);
-        },
-        [onAdLoaded, setNativeAd]
-    );
+        (event: NativeSyntheticEvent<AdInfoEvent>) => {
+            const nativeAdImpl = event.nativeEvent.nativeAdImpl;
+
+            if (nativeAdImpl) {
+                setNativeAd({ ...nativeAdImpl });
+
+                if (nativeAdImpl.title) updateAssetView(titleRef, 'TitleView');
+                if (nativeAdImpl.advertiser) updateAssetView(advertiserRef, 'AdvertiserView');
+                if (nativeAdImpl.body) updateAssetView(bodyRef, 'BodyView');
+                if (nativeAdImpl.callToAction) updateAssetView(callToActionRef, 'CallToActionView');
+                if (nativeAdImpl.url || nativeAdImpl.image || nativeAdImpl.imageSource) updateAssetView(imageRef, 'IconView');
+                if (nativeAdImpl.isOptionsViewAvailable) updateAssetView(optionViewRef, 'OptionsView');
+                if (nativeAdImpl.isMediaViewAvailable) updateAssetView(mediaViewRef, 'MediaView');
+            }
 
-    const onAdLoadFailedEvent = useCallback(
-        (event: AdNativeEvent<AdLoadFailedInfo>) => {
-            onAdLoadFailed?.(event.nativeEvent);
-        },
-        [onAdLoadFailed]
-    );
+            if (nativeAdViewRef.current) {
+                Commands.renderNativeAd(nativeAdViewRef.current);
+            }
 
-    const onAdClickedEvent = useCallback(
-        (event: AdNativeEvent<AdInfo>) => {
-            onAdClicked?.(event.nativeEvent);
+            handleNativeAdViewEvent(event, onAdLoaded);
         },
-        [onAdClicked]
+        [setNativeAd, onAdLoaded, updateAssetView, titleRef, advertiserRef, bodyRef, callToActionRef, imageRef, optionViewRef, mediaViewRef]
     );
 
-    const onAdRevenuePaidEvent = useCallback(
-        (event: AdNativeEvent<AdInfo>) => {
-            onAdRevenuePaid?.(event.nativeEvent);
-        },
-        [onAdRevenuePaid]
-    );
+    const onAdLoadFailedEvent = useCallback((event: NativeSyntheticEvent<AdLoadFailedEvent>) => handleNativeAdViewEvent(event, onAdLoadFailed), [onAdLoadFailed]);
+
+    const onAdClickedEvent = useCallback((event: NativeSyntheticEvent<AdInfoEvent>) => handleNativeAdViewEvent(event, onAdClicked), [onAdClicked]);
+
+    const onAdRevenuePaidEvent = useCallback((event: NativeSyntheticEvent<AdInfoEvent>) => handleNativeAdViewEvent(event, onAdRevenuePaid), [onAdRevenuePaid]);
 
     return (
         <NativeAdViewComponent
-            ref={saveElement}
+            ref={(element) => (nativeAdViewRef.current = element ?? undefined)}
             adUnitId={adUnitId}
             placement={placement}
             customData={customData}
-            extraParameters={extraParameters}
-            localExtraParameters={localExtraParameters}
+            extraParameters={makeExtraParametersArray(extraParameters)}
+            strLocalExtraParameters={makeLocalExtraParametersArray(localExtraParameters, 'str')}
+            boolLocalExtraParameters={makeLocalExtraParametersArray(localExtraParameters, 'bool')}
             onAdLoadedEvent={onAdLoadedEvent}
             onAdLoadFailedEvent={onAdLoadFailedEvent}
             onAdClickedEvent={onAdClickedEvent}