react-native-applovin-max 9.0.0 → 9.1.0

package/src/nativeAd/NativeAdViewProvider.tsx

@@ -1,3 +1,8 @@
+/**
+ * Provides context and state management for NativeAdView and its child asset views.
+ * Shares asset view refs and native ad data between internal components and the native SDK.
+ */
+
 import * as React from 'react';
 import { useState, createContext, useRef } from 'react';
 import type { ReactNode } from 'react';
@@ -5,12 +10,20 @@ import type { Image, NativeMethods, Text, View } from 'react-native';
 import type { NativeAd } from '../types/NativeAd';
 import type { NativeProps } from '../specs/AppLovinMAXNativeAdViewNativeComponent';
 
+/**
+ * Native component type for the rendered NativeAdView.
+ */
 export type NativeAdViewType = React.Component<NativeProps> & NativeMethods;
 
+// Ref types for native views
 type TextRef = React.ElementRef<typeof Text>;
 type ImageRef = React.ElementRef<typeof Image>;
 type ViewRef = React.ElementRef<typeof View>;
 
+/**
+ * Context type used internally by NativeAdView.
+ * Stores references to asset views and the current native ad data.
+ */
 export type NativeAdViewContextType = {
     titleRef: React.RefObject<TextRef>;
     advertiserRef: React.RefObject<TextRef>;
@@ -23,11 +36,15 @@ export type NativeAdViewContextType = {
     setNativeAd: React.Dispatch<React.SetStateAction<NativeAd>>;
 };
 
+// Default for an uninitialized native ad
 const defaultNativeAd: NativeAd = {
     isOptionsViewAvailable: false,
     isMediaViewAvailable: false,
 };
 
+/**
+ * Internal context used by NativeAdView to provide access to asset view refs and native ad data.
+ */
 export const NativeAdViewContext = createContext<NativeAdViewContextType>({
     titleRef: { current: null },
     advertiserRef: { current: null },
@@ -40,6 +57,9 @@ export const NativeAdViewContext = createContext<NativeAdViewContextType>({
     setNativeAd: () => {},
 });
 
+/**
+ * React provider that wraps components requiring access to NativeAdViewContext.
+ */
 export const NativeAdViewProvider: React.FC<{ children: ReactNode }> = ({ children }) => {
     const titleRef = useRef<TextRef | null>(null);
     const advertiserRef = useRef<TextRef | null>(null);
@@ -50,6 +70,9 @@ export const NativeAdViewProvider: React.FC<{ children: ReactNode }> = ({ childr
     const mediaViewRef = useRef<ViewRef | null>(null);
     const [nativeAd, setNativeAd] = useState<NativeAd>(defaultNativeAd);
 
+    /**
+     * Memoized context value to avoid unnecessary renders.
+     */
     const providerValue = React.useMemo(
         () => ({
             titleRef,

package/src/specs/AppLovinMAXAdViewNativeComponent.ts

@@ -3,6 +3,9 @@ import type { Double, DirectEventHandler, WithDefault } from 'react-native/Libra
 import codegenNativeCommands from 'react-native/Libraries/Utilities/codegenNativeCommands';
 import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
 
+/**
+ * Payload for ad lifecycle events (e.g. load, display, click).
+ */
 export type AdInfoEvent = Readonly<{
     adUnitId: string;
     adFormat: string;
@@ -21,6 +24,9 @@ export type AdInfoEvent = Readonly<{
     }>;
 }>;
 
+/**
+ * Payload for ad load failure events.
+ */
 export type AdLoadFailedEvent = Readonly<{
     adUnitId: string;
     adViewId?: Double;
@@ -31,6 +37,9 @@ export type AdLoadFailedEvent = Readonly<{
     adLoadFailureInfo?: string | null;
 }>;
 
+/**
+ * Payload for ad display failure events.
+ */
 export type AdDisplayFailedEvent = Readonly<{
     adUnitId: string;
     adFormat: string;
@@ -53,44 +62,96 @@ export type AdDisplayFailedEvent = Readonly<{
     mediatedNetworkErrorMessage: string;
 }>;
 
+/**
+ * Props passed to the {@link AppLovinMAXAdView} native component.
+ */
 export interface NativeProps extends ViewProps {
+    /** Ad unit ID used to load the ad. */
     adUnitId: string;
+
+    /** Ad format (e.g., "BANNER", "MREC"). */
     adFormat?: string;
+
+    /** Unique identifier for this ad view. Defaults to 0. */
     adViewId?: WithDefault<Double, 0>;
+
+    /** Optional placement name for ad tracking. */
     placement?: string | null;
+
+    /** Optional custom data associated with the ad. */
     customData?: string | null;
+
+    /** Enables adaptive banner sizing. Defaults to `true`. */
     adaptiveBannerEnabled?: WithDefault<boolean, true>;
+
+    /** Enables automatic refresh of the ad. Defaults to `true`. */
     autoRefresh?: WithDefault<boolean, true>;
+
+    /** Whether to automatically load the ad on mount. Defaults to `true`. */
     loadOnMount?: WithDefault<boolean, true>;
+
+    /** Extra key-value string parameters passed to the SDK. */
     extraParameters?: ReadonlyArray<{
         key: string;
         value: string | null;
     }>;
+
+    /** Local string parameters passed to the mediation adapter. */
     strLocalExtraParameters?: ReadonlyArray<{
         key: string;
         value: string | null;
     }>;
+
+    /** Local boolean parameters passed to the mediation adapter. */
     boolLocalExtraParameters?: ReadonlyArray<{
         key: string;
         value: boolean | null;
     }>;
+
+    /** Called when an ad is successfully loaded. */
     onAdLoadedEvent: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when an ad fails to load. */
     onAdLoadFailedEvent: DirectEventHandler<AdLoadFailedEvent>;
+
+    /** Called when an ad fails to display. */
     onAdDisplayFailedEvent: DirectEventHandler<AdDisplayFailedEvent>;
+
+    /** Called when the ad is clicked. */
     onAdClickedEvent: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when the ad expands. */
     onAdExpandedEvent: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when the ad collapses. */
     onAdCollapsedEvent: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when ad revenue is reported. */
     onAdRevenuePaidEvent: DirectEventHandler<AdInfoEvent>;
 }
 
 type AppLovinMAXAdViewNativeComponentType = HostComponent<NativeProps>;
 
+/**
+ * Native commands callable from JS for managing {@link AppLovinMAXAdView}.
+ */
 interface NativeCommands {
-    loadAd: (viewRef: React.ElementRef<AppLovinMAXAdViewNativeComponentType>) => void;
+    /**
+     * Manually starts loading a new ad when `loadOnMount` is `false`.
+     *
+     * @param viewRef - Reference to the native ad view component.
+     */
+    loadAd(viewRef: React.ElementRef<AppLovinMAXAdViewNativeComponentType>): void;
 }
 
+/**
+ * JS interface to ad view commands for {@link AppLovinMAXAdView}.
+ */
 export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
     supportedCommands: ['loadAd'],
 });
 
+/**
+ * Native view component for displaying a banner or MREC ad.
+ */
 export default codegenNativeComponent<NativeProps>('AppLovinMAXAdView') as HostComponent<NativeProps>;

package/src/specs/AppLovinMAXNativeAdViewNativeComponent.ts

@@ -3,6 +3,9 @@ import type { Double, DirectEventHandler } from 'react-native/Libraries/Types/Co
 import codegenNativeCommands from 'react-native/Libraries/Utilities/codegenNativeCommands';
 import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
 
+/**
+ * Payload for native ad lifecycle events (e.g., load, click, revenue).
+ */
 export type AdInfoEvent = Readonly<{
     adUnitId: string;
     adFormat: string;
@@ -18,6 +21,10 @@ export type AdInfoEvent = Readonly<{
         width: Double;
         height: Double;
     }>;
+
+    /**
+     * Optional native ad content for display in asset views.
+     */
     nativeAd?: Readonly<{
         title?: string;
         advertiser?: string;
@@ -29,6 +36,10 @@ export type AdInfoEvent = Readonly<{
         isOptionsViewAvailable: boolean;
         isMediaViewAvailable: boolean;
     }>;
+
+    /**
+     * Full internal native ad payload used for runtime rendering and view mapping.
+     */
     nativeAdImpl: Readonly<{
         title?: string | null;
         advertiser?: string | null;
@@ -43,6 +54,9 @@ export type AdInfoEvent = Readonly<{
     }>;
 }>;
 
+/**
+ * Payload for native ad load failure events.
+ */
 export type AdLoadFailedEvent = Readonly<{
     adUnitId: string;
     code: Double;
@@ -52,38 +66,88 @@ export type AdLoadFailedEvent = Readonly<{
     adLoadFailureInfo?: string | null;
 }>;
 
+/**
+ * Props passed to the {@link AppLovinMAXNativeAdView} native component.
+ */
 export interface NativeProps extends ViewProps {
+    /** Ad unit ID used to load the ad. */
     adUnitId: string;
+
+    /** Optional placement name for ad tracking. */
     placement?: string | null;
+
+    /** Optional custom data associated with the ad. */
     customData?: string | null;
+
+    /** Extra key-value string parameters passed to the SDK. */
     extraParameters?: ReadonlyArray<{
         key: string;
         value: string | null;
-    }> | null;
+    }>;
+
+    /** Local string parameters passed to the mediation adapter. */
     strLocalExtraParameters?: ReadonlyArray<{
         key: string;
         value: string | null;
-    }> | null;
+    }>;
+
+    /** Local boolean parameters passed to the mediation adapter. */
     boolLocalExtraParameters?: ReadonlyArray<{
         key: string;
         value: boolean | null;
-    }> | null;
+    }>;
+
+    /** Called when a native ad is successfully loaded. */
     onAdLoadedEvent: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when ad loading fails. */
     onAdLoadFailedEvent: DirectEventHandler<AdLoadFailedEvent>;
+
+    /** Called when the ad is clicked. */
     onAdClickedEvent: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when ad revenue is reported. */
     onAdRevenuePaidEvent: DirectEventHandler<AdInfoEvent>;
 }
 
 type AppLovinMAXNativeAdViewNativeComponentType = HostComponent<NativeProps>;
 
+/**
+ * Native commands callable from JS for managing {@link NativeAdView}.
+ */
 interface NativeCommands {
-    loadAd: (viewRef: React.ElementRef<AppLovinMAXNativeAdViewNativeComponentType>) => void;
-    updateAssetView: (viewRef: React.ElementRef<AppLovinMAXNativeAdViewNativeComponentType>, assetViewTag: Double, assetViewName: string) => void;
-    renderNativeAd: (viewRef: React.ElementRef<AppLovinMAXNativeAdViewNativeComponentType>) => void;
+    /**
+     * Manually loads a new native ad.
+     *
+     * @param viewRef - Reference to the native ad view.
+     */
+    loadAd(viewRef: React.ElementRef<AppLovinMAXNativeAdViewNativeComponentType>): void;
+
+    /**
+     * Binds a React Native child view to a native asset (e.g. TitleView, IconView).
+     *
+     * @param viewRef - Reference to the native ad view.
+     * @param assetViewTag - React tag for the asset view (via `findNodeHandle()`).
+     * @param assetViewName - Name of the asset (e.g., "MediaView", "CallToActionView").
+     */
+    updateAssetView(viewRef: React.ElementRef<AppLovinMAXNativeAdViewNativeComponentType>, assetViewTag: Double, assetViewName: string): void;
+
+    /**
+     * Instructs the native view to render the bound native ad after all asset views are set.
+     *
+     * @param viewRef - Reference to the native ad view.
+     */
+    renderNativeAd(viewRef: React.ElementRef<AppLovinMAXNativeAdViewNativeComponentType>): void;
 }
 
+/**
+ * JS interface to native ad view commands for {@link AppLovinMAXNativeAdView}.
+ */
 export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
     supportedCommands: ['loadAd', 'updateAssetView', 'renderNativeAd'],
 });
 
+/**
+ * Native component for rendering a custom native ad layout using bound asset views.
+ */
 export default codegenNativeComponent<NativeProps>('AppLovinMAXNativeAdView') as HostComponent<NativeProps>;

package/src/specs/NativeAppLovinMAXModule.ts

@@ -5,8 +5,16 @@ import type { Configuration } from '../types';
 import type { CMPError } from '../types';
 import type { AdViewId } from '../types';
 
+/**
+ * Native TurboModule interface for AppLovin MAX.
+ * Defines all methods and constants exposed to JavaScript.
+ */
 export interface Spec extends TurboModule {
+    /**
+     * Returns all supported event constants and SDK error codes.
+     */
     readonly getConstants: () => {
+        // Interstitial ad events
         ON_INTERSTITIAL_LOADED_EVENT: string;
         ON_INTERSTITIAL_LOAD_FAILED_EVENT: string;
         ON_INTERSTITIAL_CLICKED_EVENT: string;
@@ -14,6 +22,8 @@ export interface Spec extends TurboModule {
         ON_INTERSTITIAL_AD_FAILED_TO_DISPLAY_EVENT: string;
         ON_INTERSTITIAL_HIDDEN_EVENT: string;
         ON_INTERSTITIAL_AD_REVENUE_PAID: string;
+
+        // Rewarded ad events
         ON_REWARDED_AD_LOADED_EVENT: string;
         ON_REWARDED_AD_LOAD_FAILED_EVENT: string;
         ON_REWARDED_AD_CLICKED_EVENT: string;
@@ -22,18 +32,24 @@ export interface Spec extends TurboModule {
         ON_REWARDED_AD_HIDDEN_EVENT: string;
         ON_REWARDED_AD_RECEIVED_REWARD_EVENT: string;
         ON_REWARDED_AD_REVENUE_PAID: string;
+
+        // Banner ad events
         ON_BANNER_AD_LOADED_EVENT: string;
         ON_BANNER_AD_LOAD_FAILED_EVENT: string;
         ON_BANNER_AD_CLICKED_EVENT: string;
         ON_BANNER_AD_COLLAPSED_EVENT: string;
         ON_BANNER_AD_EXPANDED_EVENT: string;
         ON_BANNER_AD_REVENUE_PAID: string;
+
+        // MREC ad events
         ON_MREC_AD_LOADED_EVENT: string;
         ON_MREC_AD_LOAD_FAILED_EVENT: string;
         ON_MREC_AD_CLICKED_EVENT: string;
         ON_MREC_AD_COLLAPSED_EVENT: string;
         ON_MREC_AD_EXPANDED_EVENT: string;
         ON_MREC_AD_REVENUE_PAID: string;
+
+        // App Open ad events
         ON_APPOPEN_AD_LOADED_EVENT: string;
         ON_APPOPEN_AD_LOAD_FAILED_EVENT: string;
         ON_APPOPEN_AD_CLICKED_EVENT: string;
@@ -41,8 +57,12 @@ export interface Spec extends TurboModule {
         ON_APPOPEN_AD_FAILED_TO_DISPLAY_EVENT: string;
         ON_APPOPEN_AD_HIDDEN_EVENT: string;
         ON_APPOPEN_AD_REVENUE_PAID: string;
+
+        // Native UI component ad events
         ON_NATIVE_UI_COMPONENT_ADVIEW_AD_LOADED_EVENT: string;
         ON_NATIVE_UI_COMPONENT_ADVIEW_AD_LOAD_FAILED_EVENT: string;
+
+        // Error codes
         MAX_ERROR_CODE_UNSPECIFIED: number;
         MAX_ERROR_CODE_NO_FILL: number;
         MAX_ERROR_CODE_AD_LOAD_FAILED: number;
@@ -57,138 +77,132 @@ export interface Spec extends TurboModule {
         MAX_ERROR_CODE_INVALID_AD_UNIT_ID: number;
     };
 
-    isInitialized(): Promise<boolean>;
+    // ─────────────────────────────────────────────────────────
+    // SDK Initialization & Configuration
+    // ─────────────────────────────────────────────────────────
 
+    isInitialized(): Promise<boolean>;
     initialize(pluginVersion: string, sdkKey: string): Promise<Configuration>;
-
     isTablet(): Promise<boolean>;
-
     showMediationDebugger(): void;
 
-    setHasUserConsent(hasUserConsent: boolean): void;
+    // ─────────────────────────────────────────────────────────
+    // Privacy & Consent APIs
+    // ─────────────────────────────────────────────────────────
 
+    setHasUserConsent(hasUserConsent: boolean): void;
     hasUserConsent(): Promise<boolean>;
 
     setDoNotSell(doNotSell: boolean): void;
-
     isDoNotSell(): Promise<boolean>;
 
-    setUserId(userId: string): void;
+    // ─────────────────────────────────────────────────────────
+    // User & Debug Settings
+    // ─────────────────────────────────────────────────────────
 
+    setUserId(userId: string): void;
     setMuted(muted: boolean): void;
-
     isMuted(): Promise<boolean>;
-
     setVerboseLogging(enabled: boolean): void;
-
     setCreativeDebuggerEnabled(enabled: boolean): void;
-
     setTestDeviceAdvertisingIds(ids: string[]): void;
 
-    setExtraParameter(key: string, value: string | null): void;
+    // ─────────────────────────────────────────────────────────
+    // Extra Parameters
+    // ─────────────────────────────────────────────────────────
 
+    setExtraParameter(key: string, value: string | null): void;
     setInitializationAdUnitIds(adUnitIds: string[]): void;
 
-    setTermsAndPrivacyPolicyFlowEnabled(enabled: boolean): void;
+    // ─────────────────────────────────────────────────────────
+    // CMP (Consent Flow)
+    // ─────────────────────────────────────────────────────────
 
+    setTermsAndPrivacyPolicyFlowEnabled(enabled: boolean): void;
     setPrivacyPolicyUrl(url: string): void;
-
     setTermsOfServiceUrl(url: string): void;
-
     setConsentFlowDebugUserGeography(userGeography: string): void;
-
     showCmpForExistingUser(): Promise<CMPError | null>;
-
     hasSupportedCmp(): Promise<boolean>;
 
-    addSegment(key: number, values: number[]): Promise<void>;
+    // ─────────────────────────────────────────────────────────
+    // Segments
+    // ─────────────────────────────────────────────────────────
 
+    addSegment(key: number, values: number[]): Promise<void>;
     getSegments(): Promise<{ [key: string]: number[] } | null>;
 
-    createBanner(adUnitId: string, position: string): void;
+    // ─────────────────────────────────────────────────────────
+    // Banner Ads
+    // ─────────────────────────────────────────────────────────
 
+    createBanner(adUnitId: string, position: string): void;
     createBannerWithOffsets(adUnitId: string, position: string, xOffset: number, yOffset: number): void;
-
     setBannerBackgroundColor(adUnitId: string, hexColorCode: string): void;
-
     setBannerPlacement(adUnitId: string, placement: string | null): void;
-
     setBannerCustomData(adUnitId: string, customData: string | null): void;
-
     setBannerWidth(adUnitId: string, width: number): void;
-
     updateBannerPosition(adUnitId: string, position: string): void;
-
     updateBannerOffsets(adUnitId: string, xOffset: number, yOffset: number): void;
-
     setBannerExtraParameter(adUnitId: string, key: string, value: string | null): void;
-
     setBannerLocalExtraParameter(adUnitId: string, parameters: UnsafeObject): void;
-
     startBannerAutoRefresh(adUnitId: string): void;
-
     stopBannerAutoRefresh(adUnitId: string): void;
-
     showBanner(adUnitId: string): void;
-
     hideBanner(adUnitId: string): void;
-
     destroyBanner(adUnitId: string): void;
-
     getAdaptiveBannerHeightForWidth(width: number): Promise<number>;
 
-    createMRec(adUnitId: string, position: string): void;
+    // ─────────────────────────────────────────────────────────
+    // MREC Ads
+    // ─────────────────────────────────────────────────────────
 
+    createMRec(adUnitId: string, position: string): void;
     setMRecPlacement(adUnitId: string, placement: string | null): void;
-
     setMRecCustomData(adUnitId: string, customData: string | null): void;
-
     updateMRecPosition(adUnitId: string, position: string): void;
-
     setMRecExtraParameter(adUnitId: string, key: string, value: string | null): void;
-
     setMRecLocalExtraParameter(adUnitId: string, parameters: UnsafeObject): void;
-
     startMRecAutoRefresh(adUnitId: string): void;
-
     stopMRecAutoRefresh(adUnitId: string): void;
-
     showMRec(adUnitId: string): void;
-
     hideMRec(adUnitId: string): void;
-
     destroyMRec(adUnitId: string): void;
 
-    loadInterstitial(adUnitId: string): void;
+    // ─────────────────────────────────────────────────────────
+    // Interstitial Ads
+    // ─────────────────────────────────────────────────────────
 
+    loadInterstitial(adUnitId: string): void;
     isInterstitialReady(adUnitId: string): Promise<boolean>;
-
     showInterstitial(adUnitId: string, placement?: string | null, customData?: string | null): void;
-
     setInterstitialExtraParameter(adUnitId: string, key: string, value: string | null): void;
-
     setInterstitialLocalExtraParameter(adUnitId: string, parameters: UnsafeObject): void;
 
-    loadRewardedAd(adUnitId: string): void;
+    // ─────────────────────────────────────────────────────────
+    // Rewarded Ads
+    // ─────────────────────────────────────────────────────────
 
+    loadRewardedAd(adUnitId: string): void;
     isRewardedAdReady(adUnitId: string): Promise<boolean>;
-
     showRewardedAd(adUnitId: string, placement?: string | null, customData?: string | null): void;
-
     setRewardedAdExtraParameter(adUnitId: string, key: string, value: string | null): void;
-
     setRewardedAdLocalExtraParameter(adUnitId: string, parameters: UnsafeObject): void;
 
-    loadAppOpenAd(adUnitId: string): void;
+    // ─────────────────────────────────────────────────────────
+    // App Open Ads
+    // ─────────────────────────────────────────────────────────
 
+    loadAppOpenAd(adUnitId: string): void;
     isAppOpenAdReady(adUnitId: string): Promise<boolean>;
-
     showAppOpenAd(adUnitId: string, placement?: string | null, customData?: string | null): void;
-
     setAppOpenAdExtraParameter(adUnitId: string, key: string, value: string | null): void;
-
     setAppOpenAdLocalExtraParameter(adUnitId: string, parameters: UnsafeObject): void;
 
+    // ─────────────────────────────────────────────────────────
+    // Native UI Component AdView (Preload/Destroy)
+    // ─────────────────────────────────────────────────────────
+
     preloadNativeUIComponentAdView(
         adUnitId: string,
         adFormat: string,
@@ -200,9 +214,15 @@ export interface Spec extends TurboModule {
 
     destroyNativeUIComponentAdView(adViewId: number): Promise<void>;
 
-    addListener(eventType: string): void;
+    // ─────────────────────────────────────────────────────────
+    // TurboModule Listener Management
+    // ─────────────────────────────────────────────────────────
 
+    addListener(eventType: string): void;
     removeListeners(count: number): void;
 }
 
+/**
+ * Enforces use of the native AppLovinMAX TurboModule.
+ */
 export default TurboModuleRegistry.getEnforcing<Spec>('AppLovinMAX');

package/src/types/AdEvent.ts

@@ -1,15 +1,21 @@
 import type { AdInfo, AdLoadFailedInfo, AdDisplayFailedInfo, AdRewardInfo } from './AdInfo';
 
+/**
+ * Represents any ad event object that can be emitted by the native AppLovin MAX module.
+ */
 export type AdEventObject = AdInfo | AdLoadFailedInfo | AdDisplayFailedInfo | AdRewardInfo;
 
 /**
- * Defines a generic event listener for the pragrammatic methods to receive an event from the native
- * module.
+ * A generic event listener for handling ad events in programmatic APIs.
+ *
+ * @template T - A specific ad event type.
  */
 export type AdEventListener<T extends AdEventObject> = (event: T) => void;
 
 /**
- * Defines a generic event object for the UI components i.e. AdView and NativeAdView to receive an
- * event from the native module.
+ * Wraps an ad event in a `nativeEvent` field, following the React Native synthetic event pattern.
+ * Used for UI component props such as {@link AdView} and {@link NativeAdView}.
+ *
+ * @template T - A specific ad event type.
  */
 export type AdNativeEvent<T extends AdEventObject> = { nativeEvent: T };