react-native-applovin-max 9.0.0 → 9.2.0

package/src/AdView.tsx

@@ -13,7 +13,7 @@ import { makeExtraParametersArray, makeLocalExtraParametersArray } from './Utils
 const { ON_NATIVE_UI_COMPONENT_ADVIEW_AD_LOADED_EVENT, ON_NATIVE_UI_COMPONENT_ADVIEW_AD_LOAD_FAILED_EVENT } = AppLovinMAX.getConstants();
 
 /**
- * Defines a format of an ad.
+ * Defines the format of an ad.
  */
 export enum AdFormat {
     /**
@@ -28,7 +28,7 @@ export enum AdFormat {
 }
 
 /**
- * Defines a position of a banner or MREC ad.
+ * Defines the position for rendering a banner or MREC ad within its container.
  */
 export enum AdViewPosition {
     TOP_CENTER = 'top_center',
@@ -51,76 +51,53 @@ const ADVIEW_SIZE = {
     mrec: { width: 300, height: 250 },
 };
 
-// Returns 'auto' for unspecified width / height
+// Extracts width and height from the style prop, defaulting to 'auto' when unspecified.
 const getOutlineViewSize = (style: StyleProp<ViewStyle>): [DimensionValue, DimensionValue] => {
     const viewStyle = StyleSheet.flatten(style) || {};
     return [viewStyle.width ?? 'auto', viewStyle.height ?? 'auto'];
 };
 
-const sizeBannerDimensions = async (sizeProps: SizeRecord, adaptiveBannerEnabled: boolean, screenWidth: number, bannerFormatSize: SizeRecord): Promise<SizeRecord> => {
-    const width = sizeProps.width === 'auto' ? screenWidth : sizeProps.width;
-
-    let height;
-    if (sizeProps.height === 'auto') {
-        if (adaptiveBannerEnabled) {
-            try {
-                height = await AppLovinMAX.getAdaptiveBannerHeightForWidth(screenWidth);
-            } catch (error) {
-                console.error('Error getting adaptive banner height:', error);
-                height = bannerFormatSize.height;
-            }
-        } else {
-            height = bannerFormatSize.height;
-        }
-    } else {
-        height = sizeProps.height;
-    }
-
-    return { width, height };
-};
-
 const handleAdViewEvent = <T extends AdInfoEvent | AdLoadFailedEvent | AdDisplayFailedEvent>(event: NativeSyntheticEvent<T>, callback?: (adInfo: T) => void) => {
     if (!callback) return;
-
-    let adInfo: any = { ...event.nativeEvent };
-
-    if ('size' in event.nativeEvent) {
-        adInfo.size = {
-            width: event.nativeEvent.size?.width ?? 0,
-            height: event.nativeEvent.size?.height ?? 0,
-        };
-    }
-
-    callback(adInfo);
+    callback(event.nativeEvent);
 };
 
 /**
- * The {@link AdView} component renders banner or MREC ads with responsive sizing.
- * - **Banners**: 320x50 on phones, 728x90 on tablets.
- * - **MRECs**: 300x250 on all devices.
+ * Renders a banner or MREC ad using a native view, with adaptive or responsive sizing.
  *
- * Use {@link AppLovinMAX.isTablet()} to determine device type for layout adjustments.
- * For adaptive banners, use {@link BannerAd.getAdaptiveHeightForWidth()} for precise sizing.
+ * - **Banners**: 320×50 on phones, 728×90 on tablets.
+ * - **MRECs**: Fixed size of 300×250 on all devices.
+ *
+ * Internally uses {@link AppLovinMAX.isTablet()} to determine banner size on tablets.
+ * You can also use this method externally to assist with layout decisions.
+ *
+ * For adaptive banners, use {@link BannerAd.getAdaptiveHeightForWidth()} to determine the appropriate height.
  *
  * **Preloading**:
- * When preloading an {@link AdView} using {@link preloadNativeUIComponentAdView},
- * the returned {@link AdViewId} must be passed to identify the preloaded instance.
+ * If you preload an ad for AdView using {@link preloadNativeUIComponentAdView},
+ * pass the returned {@link AdViewId} to this component to display the preloaded instance.
+ *
+ * **Note:** The AppLovin SDK must be initialized before using this component.
  *
  * ### Example:
- * ```js
+ * ```tsx
  * <AdView
  *   adUnitId={adUnitId}
  *   adFormat={AdFormat.BANNER}
  *   placement="my_placement"
  *   customData="my_customData"
- *   extraParameters={{"key1":"value1", "key2":"value2"}}
- *   localExtraParameters={{"key1":123", "key2":object}}
+ *   extraParameters={{ key1: "value1", key2: "value2" }}
+ *   localExtraParameters={{ key1: "value1", key2: true }}
  *   adaptiveBannerEnabled={false}
  *   autoRefresh={false}
  *   style={styles.banner}
  *   onAdLoaded={(adInfo: AdInfo) => { ... }}
  * />
  * ```
+ *
+ * For complete implementation examples, see:
+ * - https://github.com/AppLovin/AppLovin-MAX-React-Native/blob/master/example/src/NativeBannerExample.tsx
+ * - https://github.com/AppLovin/AppLovin-MAX-React-Native/blob/master/example/src/NativeMRecExample.tsx
  */
 export const AdView = forwardRef<AdViewHandler, AdViewProps & ViewProps>(function AdView(
     {
@@ -151,10 +128,13 @@ export const AdView = forwardRef<AdViewHandler, AdViewProps & ViewProps>(functio
     const [, forceUpdate] = useReducer((x) => x + 1, 0);
     const adViewRef = useRef<React.ElementRef<typeof AdViewComponent> | undefined>();
     const [isInitialized, setIsInitialized] = useState<boolean>(false);
-    const sizeProps = useRef<SizeRecord>({});
     const dimensions = useRef<SizeRecord>({});
 
-    useImperativeHandle(ref, () => ({ loadAd: () => Commands.loadAd(adViewRef.current!) }), []);
+    const loadAd = useCallback(() => {
+        adViewRef.current && Commands.loadAd(adViewRef.current);
+    }, []);
+
+    useImperativeHandle(ref, () => ({ loadAd }), [loadAd]);
 
     useEffect(() => {
         (async () => {
@@ -164,7 +144,7 @@ export const AdView = forwardRef<AdViewHandler, AdViewProps & ViewProps>(functio
             const initialized = await AppLovinMAX.isInitialized();
             setIsInitialized(initialized);
             if (!initialized) {
-                console.warn('AdView is mounted before the initialization of the AppLovin MAX React Native module');
+                console.warn('AdView was mounted before the AppLovin MAX React Native module was initialized.');
             }
         })();
     }, [adFormat]);
@@ -172,45 +152,50 @@ export const AdView = forwardRef<AdViewHandler, AdViewProps & ViewProps>(functio
     useEffect(() => {
         const [width, height] = getOutlineViewSize(style);
 
-        if (sizeProps.current.width === width && sizeProps.current.height === height) return;
-
-        sizeProps.current = { width, height };
+        if (dimensions.current.width === width && dimensions.current.height === height) return;
 
         (async () => {
-            if (adFormat === AdFormat.BANNER) {
-                const adaptedSize = await sizeBannerDimensions(sizeProps.current, adaptiveBannerEnabled, screenWidth, adFormatSize.current);
-
-                if (dimensions.current.width !== adaptedSize.width || dimensions.current.height !== adaptedSize.height) {
-                    dimensions.current = adaptedSize;
-                    forceUpdate();
+            const isBanner = adFormat === AdFormat.BANNER;
+            const isWidthAuto = width === 'auto';
+            const isHeightAuto = height === 'auto';
+
+            const resolvedWidth = isWidthAuto ? (isBanner ? screenWidth : adFormatSize.current.width) : width;
+
+            let resolvedHeight: DimensionValue | undefined = height;
+
+            if (isHeightAuto) {
+                if (isBanner && adaptiveBannerEnabled) {
+                    try {
+                        resolvedHeight = await AppLovinMAX.getAdaptiveBannerHeightForWidth(screenWidth);
+                    } catch (error) {
+                        console.error('Error getting adaptive banner height:', error);
+                        resolvedHeight = adFormatSize.current.height;
+                    }
+                } else {
+                    resolvedHeight = adFormatSize.current.height;
                 }
-            } else {
-                dimensions.current = {
-                    width: width === 'auto' ? adFormatSize.current.width : width,
-                    height: height === 'auto' ? adFormatSize.current.height : height,
-                };
+            }
+
+            const newSize = { width: resolvedWidth, height: resolvedHeight };
+
+            if (dimensions.current.width !== newSize.width || dimensions.current.height !== newSize.height) {
+                dimensions.current = newSize;
                 forceUpdate();
             }
         })();
     }, [adFormat, adaptiveBannerEnabled, isInitialized, screenWidth, style]);
 
     const onAdLoadedEvent = useCallback((event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdLoaded), [onAdLoaded]);
-
     const onAdLoadFailedEvent = useCallback((event: NativeSyntheticEvent<AdLoadFailedEvent>) => handleAdViewEvent(event, onAdLoadFailed), [onAdLoadFailed]);
-
     const onAdDisplayFailedEvent = useCallback((event: NativeSyntheticEvent<AdDisplayFailedEvent>) => handleAdViewEvent(event, onAdDisplayFailed), [onAdDisplayFailed]);
-
     const onAdClickedEvent = useCallback((event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdClicked), [onAdClicked]);
-
     const onAdExpandedEvent = useCallback((event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdExpanded), [onAdExpanded]);
-
     const onAdCollapsedEvent = useCallback((event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdCollapsed), [onAdCollapsed]);
-
     const onAdRevenuePaidEvent = useCallback((event: NativeSyntheticEvent<AdInfoEvent>) => handleAdViewEvent(event, onAdRevenuePaid), [onAdRevenuePaid]);
 
     if (!isInitialized || Object.keys(dimensions.current).length === 0) {
         // Early return if not initialized or dimensions are not set
-        return <View style={Object.assign({}, style, dimensions.current)} {...otherProps} />;
+        return <View style={style} {...otherProps} />;
     }
 
     return (
@@ -234,7 +219,7 @@ export const AdView = forwardRef<AdViewHandler, AdViewProps & ViewProps>(functio
             onAdExpandedEvent={onAdExpandedEvent}
             onAdCollapsedEvent={onAdCollapsedEvent}
             onAdRevenuePaidEvent={onAdRevenuePaidEvent}
-            style={Object.assign({}, style, dimensions.current)}
+            style={[style, dimensions.current]}
             {...otherProps}
         />
     );
@@ -247,15 +232,15 @@ export const AdView = forwardRef<AdViewHandler, AdViewProps & ViewProps>(functio
  * - Unmounting {@link AdView} does not destroy the preloaded component—it will be reused on the next mount.
  * - You must manually destroy the preloaded component when it is no longer needed using {@link destroyNativeUIComponentAdView}.
  *
- * @param adUnitId - The Ad Unit ID for which the ads should be preloaded.
+ * @param adUnitId - The Ad Unit ID for which ads should be preloaded.
  * @param adFormat - The ad format to preload. Must be either {@link AdFormat.BANNER} or {@link AdFormat.MREC}.
  * @param options - Optional properties to configure the native UI component (e.g., placement, custom data).
- * @returns A promise resolving to an {@link AdViewId}, which uniquely identifies the preloaded component.
+ * @returns A promise that resolves to an {@link AdViewId}, uniquely identifying the preloaded component instance.
  * @throws An error if the preload request fails.
  */
 export const preloadNativeUIComponentAdView = async (adUnitId: string, adFormat: AdFormat, options: NativeUIComponentAdViewOptions = {}): Promise<AdViewId> => {
-    const { placement = null, customData = null, extraParameters = {}, localExtraParameters = {} } = options;
-    return AppLovinMAX.preloadNativeUIComponentAdView(adUnitId, adFormat, placement, customData, extraParameters, localExtraParameters);
+    const { isAdaptive = true, placement = null, customData = null, extraParameters = {}, localExtraParameters = {} } = options;
+    return AppLovinMAX.preloadNativeUIComponentAdView(adUnitId, adFormat, isAdaptive, placement, customData, extraParameters, localExtraParameters);
 };
 
 /**
@@ -275,8 +260,7 @@ export const destroyNativeUIComponentAdView = async (adViewId: AdViewId): Promis
 };
 
 /**
- * Adds the specified event listener to receive {@link AdInfo} when a native UI component loads a
- * new ad.
+ * Adds the specified event listener to receive {@link AdInfo} when a native UI component loads a new ad.
  *
  * @param listener Listener to be notified.
  */
@@ -285,15 +269,14 @@ export const addNativeUIComponentAdViewAdLoadedEventListener = (listener: (adInf
 };
 
 /**
- * Removes the event listener to receive {@link AdInfo} when a native UI component loads a new ad.
+ * Removes the event listener registered to receive {@link AdInfo} when a native UI component loads a new ad.
  */
 export const removeNativeUIComponentAdViewAdLoadedEventListener = (): void => {
     removeEventListener(ON_NATIVE_UI_COMPONENT_ADVIEW_AD_LOADED_EVENT);
 };
 
 /**
- * Adds the specified event listener to receive {@link AdLoadFailedInfo} when a native UI component
- * could not load a new ad.
+ * Adds the specified event listener to receive {@link AdLoadFailedInfo} when a native UI component could not load a new ad.
  *
  * @param listener Listener to be notified.
  */
@@ -302,8 +285,7 @@ export const addNativeUIComponentAdViewAdLoadFailedEventListener = (listener: (e
 };
 
 /**
- * Removes the event listener to receive {@link AdLoadFailedInfo} when a native UI component could
- * not load a new ad.
+ * Removes the event listener registered to receive {@link AdLoadFailedInfo} when a native UI component could not load a new ad.
  */
 export const removeNativeUIComponentAdViewAdLoadFailedEventListener = (): void => {
     removeEventListener(ON_NATIVE_UI_COMPONENT_ADVIEW_AD_LOAD_FAILED_EVENT);

package/src/AppLovinMAX.ts

@@ -2,93 +2,100 @@ import type { AppLovinMAXType } from './types/AppLovinMAX';
 import type { Configuration } from './types/Configuration';
 import NativeAppLovinMAX from './specs/NativeAppLovinMAXModule';
 
-const VERSION = '9.0.0';
+const VERSION = '9.2.0';
 
 /**
- * This enum represents the user's geography used to determine the type of consent flow shown to the
- * user.
+ * Represents the user's geography, used to determine which type of consent flow to display.
  */
 export enum ConsentFlowUserGeography {
     /**
-     * User's geography is unknown.
+     * The user's geography could not be determined.
      */
     UNKNOWN = 'U',
 
     /**
-     * The user is in GDPR region.
+     * The user is located in a GDPR region.
      */
     GDPR = 'G',
 
     /**
-     * The user is in a non-GDPR region.
+     * The user is not in a GDPR region.
      */
     OTHER = 'O',
 }
 
 /**
- * AppLovin SDK-defined app tracking transparency status values (extended to include "unavailable"
- * state on iOS before iOS14).
+ * App tracking transparency status values as defined by the AppLovin SDK.
+ *
+ * These values are based on Apple's AppTrackingTransparency framework (iOS 14+).
  */
 export enum AppTrackingStatus {
     /**
-     * Device is on iOS before iOS14, AppTrackingTransparency.framework is not available.
+     * Device is running an iOS version prior to iOS 14.
+     * AppTrackingTransparency is not available.
      */
     UNAVAILABLE = 'U',
 
     /**
-     * The user has not yet received an authorization request to authorize access to app-related
-     * data that can be used for tracking the user or the device.
+     * The user has not yet responded to the tracking authorization prompt.
      */
     NOT_DETERMINED = 'N',
 
     /**
-     * Authorization to access app-related data that can be used for tracking the user or the device
-     * is restricted.
+     * Tracking is restricted (e.g. due to parental controls).
      */
     RESTRICTED = 'R',
 
     /**
-     * The user denies authorization to access app-related data that can be used for tracking the
-     * user or the device.
+     * The user denied authorization for tracking.
      */
     DENIED = 'D',
 
     /**
-     * The user authorizes access to app-related data that can be used for tracking the user or the
-     * device.
+     * The user authorized tracking access.
      */
     AUTHORIZED = 'A',
 }
 
 /**
- * Represents errors for CMP flow.
+ * Error codes returned from the Consent Management Platform (CMP) flow.
  */
 export enum CMPErrorCode {
     /**
-     * Indicates that an unspecified error has occurred.
+     * An unspecified error occurred.
      */
     UNSPECIFIED = -1,
 
     /**
-     * Indicates that the CMP has not been integrated correctly.
+     * The CMP was not integrated correctly.
      */
     INTEGRATION_ERROR = 1,
 
     /**
-     * Indicates that the CMP form is unavailable.
+     * The CMP form is unavailable.
      */
     FORM_UNAVAILABLE = 2,
 
     /**
-     * Indicates that the CMP form is not required.
+     * The CMP form is not required for this user.
      */
     FORM_NOT_REQUIRED = 3,
 }
 
-const initialize = (sdkKey: string): Promise<Configuration> => {
-    return NativeAppLovinMAX.initialize(VERSION, sdkKey);
-};
+/**
+ * Initializes the AppLovin MAX SDK with the provided SDK key.
+ *
+ * @param sdkKey - Your AppLovin SDK key.
+ * @returns A promise that resolves with the SDK configuration.
+ */
+const initialize = (sdkKey: string): Promise<Configuration> => NativeAppLovinMAX.initialize(VERSION, sdkKey);
 
+/**
+ * Retrieves the user segments.
+ *
+ * @returns A promise resolving to a Map of segment IDs to arrays of group IDs,
+ *          or `null` if no segments are available.
+ */
 const getSegments = async (): Promise<Map<number, number[]> | null> => {
     const segments = await NativeAppLovinMAX.getSegments();
 
@@ -98,10 +105,8 @@ const getSegments = async (): Promise<Map<number, number[]> | null> => {
 
     const map = new Map<number, number[]>();
 
-    for (const key in segments) {
-        // Convert the key from a string to a number. In JavaScript, an object cannot have an
-        // integer as a key, but the Map object can have keys of any data type.
-        const value = segments[key];
+    for (const [key, value] of Object.entries(segments)) {
+        // In JavaScript, object keys are always strings, so we convert them to numbers for the Map.
         if (value) {
             map.set(Number(key), value);
         }
@@ -110,10 +115,15 @@ const getSegments = async (): Promise<Map<number, number[]> | null> => {
     return map;
 };
 
+// All native methods except those overridden here
 type NativeAppLovinMAXType = Omit<AppLovinMAXType, 'initialize' | 'getSegments'>;
 
 const nativeMethods: NativeAppLovinMAXType = NativeAppLovinMAX;
 
+/**
+ * Main AppLovin MAX module interface exposed to JavaScript.
+ * Wraps the native module and overrides `initialize()` and `getSegments()` for custom handling.
+ */
 export const AppLovinMAX: AppLovinMAXType = Object.create(nativeMethods, {
     initialize: {
         value: initialize,

package/src/BannerAd.ts

@@ -14,9 +14,8 @@ const {
     ON_BANNER_AD_REVENUE_PAID,
 } = AppLovinMAX.getConstants();
 
-const createAd = (adUnitId: string, position: AdViewPosition, xOffset: number = 0, yOffset: number = 0): void => {
-    AppLovinMAX.createBannerWithOffsets(adUnitId, position, xOffset, yOffset);
-    AppLovinMAX.setBannerExtraParameter(adUnitId, 'adaptive_banner', 'true');
+const createAd = (adUnitId: string, position: AdViewPosition, xOffset: number = 0, yOffset: number = 0, isAdaptive: boolean = true): void => {
+    AppLovinMAX.createBannerWithOffsets(adUnitId, position, xOffset, yOffset, isAdaptive);
 };
 
 const destroyAd = (adUnitId: string): void => {

package/src/ErrorCode.ts

@@ -16,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,15 +1,28 @@
+/**
+ * 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';
 
-// 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();
@@ -17,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/Utils.ts

@@ -1,6 +1,17 @@
 import type { LocalExtraParameterValue } from './types/AdProps';
 
-export const makeExtraParametersArray = (input?: Record<string, string | null>) => (input ? Object.entries(input).map(([key, value]) => ({ key, value })) : []);
+/**
+ * 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';
 
@@ -9,6 +20,14 @@ type LocalExtraParameterValueMap = {
     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