react-native-applovin-max 9.0.0 → 9.2.0

package/src/types/AppLovinMAX.ts

@@ -3,154 +3,151 @@ import type { CMPError } from './CMPError';
 import type { ConsentFlowUserGeography } from '../AppLovinMAX';
 
 /**
- * Represents the AppLovinMAX module.
+ * Defines the AppLovin MAX module interface exposed to JavaScript.
  */
 export type AppLovinMAXType = {
     /**
-     * Indicates whether or not the AppLovinMAX SDK has fully initialized without errors and
-     * {@link AppLovinMAX.initialize()} has called the completion callback.
+     * Checks whether the AppLovin MAX SDK has finished initializing.
+     *
+     * @returns A promise that resolves to `true` if the SDK is initialized, or `false` otherwise.
      */
     isInitialized(): Promise<boolean>;
 
     /**
-     * Initializes the AppLovinMAX SDK, and returns {@link Configuration} when it finishes initializing.
+     * Initializes the AppLovin MAX SDK.
      *
-     * @param sdkKey SDK key to use for the instance of the AppLovinMAX SDK.
+     * @param sdkKey - Your AppLovin SDK key.
+     * @returns A promise that resolves with the initialization configuration.
      */
     initialize(sdkKey: string): Promise<Configuration>;
 
     /**
-     * Sets a list of the ad units for the SDK to initialize only those networks.
+     * Restricts initialization to the specified ad unit IDs only.
      *
-     * @param adUnitIds Ad units to be initialized with the SDK.
+     * @param adUnitIds - An array of ad unit IDs to initialize.
      */
     setInitializationAdUnitIds(adUnitIds: string[]): void;
 
     /**
-     * Presents the mediation debugger UI.
+     * Displays the AppLovin Mediation Debugger UI.
      */
     showMediationDebugger(): void;
 
     /**
-     * Whether this device is a tablet.
+     * Checks whether the current device is a tablet.
+     *
+     * @returns A promise that resolves to `true` if the device is a tablet.
      */
     isTablet(): Promise<boolean>;
 
     /**
-     * Sets an ID for the current user. AppLovin ties this identifier to SDK events and AppLovin’s
-     * optional S2S postbacks.
+     * Sets a user ID for use in SDK events and S2S postbacks.
      *
-     * @param userId User id.
+     * @param userId - The custom user ID to associate with this device.
      */
     setUserId(userId: string): void;
 
     /**
-     * Sets a muted state (or not) as the initial state for video ads.
+     * Sets whether video ads should start in a muted state.
      *
-     * @param muted If ads should begin in a muted state.
+     * @param muted - `true` to mute ads by default.
      */
     setMuted(muted: boolean): void;
 
     /**
-     * Whether to begin video ads in a muted state or not.
+     * Gets whether video ads will start muted.
+     *
+     * @returns A promise that resolves to `true` if ads will begin muted.
      */
     isMuted(): Promise<boolean>;
 
     /**
-     * A toggle for verbose logging for the AppLovinMAX SDK.
+     * Enables or disables verbose logging in the AppLovin MAX SDK.
      *
-     * @param verboseLoggingEnabled true if the AppLovinMAX SDK should output log messages.
+     * @param verboseLoggingEnabled - `true` to enable verbose logs.
      */
     setVerboseLogging(verboseLoggingEnabled: boolean): void;
 
     /**
-     * Enables devices to receive test ads by passing in the advertising identifier (IDFA or IDFV) of
-     * each test device. Refer to AppLovin logs for the IDFA or IDFV of your current device.
+     * Registers test devices using their advertising IDs (IDFA/IDFV).
      *
-     * @param advertisingIds A list of the advertising ids.
+     * @param advertisingIds - An array of advertising IDs to register.
      */
     setTestDeviceAdvertisingIds(advertisingIds: string[]): void;
 
     /**
-     * Whether the Creative Debugger displays after you flip the device screen down twice.
+     * Enables or disables the Creative Debugger gesture (flip screen down twice).
      *
-     * @param enabled Default to true.
+     * @param enabled - `true` to enable the Creative Debugger (default: true).
      */
     setCreativeDebuggerEnabled(enabled: boolean): void;
 
     /**
-     * Sets an extra parameter to pass to the AppLovin server.
+     * Sets an extra parameter to send with SDK requests.
      *
-     * @param key Parameter key.
-     * @param value Parameter value.
+     * @param key - The name of the parameter.
+     * @param value - The value of the parameter, or `null` to clear it.
      */
     setExtraParameter(key: string, value: string | null): void;
 
     /**
-     * Enables the MAX Terms and Privacy Policy Flow.
+     * Enables the AppLovin MAX Terms and Privacy Policy flow.
      *
-     * @param enabled true to enable the MAX Terms and Privacy Policy Flow.
+     * @param enabled - `true` to enable the flow.
      */
     setTermsAndPrivacyPolicyFlowEnabled(enabled: boolean): void;
 
     /**
-     * The URL of your company’s privacy policy, as a string. This is required in order to enable
-     * the Terms Flow.
+     * Sets the URL for your company’s privacy policy (required to enable the terms flow).
      *
-     * @param urlString The URL string to point your company’s privacy policy.
+     * @param urlString - A valid URL string to your privacy policy.
      */
     setPrivacyPolicyUrl(urlString: string): void;
 
     /**
-     * The URL of your company’s terms of service, as a string. This is optional; you can enable
-     * the Terms Flow with or without it.
+     * Sets the URL for your company’s terms of service (optional).
      *
-     * @param urlString The URL string to point your company’s terms of service.
+     * @param urlString - A valid URL string to your terms of service.
      */
     setTermsOfServiceUrl(urlString: string): void;
 
     /**
-     * Set debug user geography. You may use this to test CMP flow by setting this to {@link ConsentFlowUserGeography.GDPR}.
+     * Sets a mock geography for testing the CMP flow (e.g., GDPR).
      *
-     * @note The debug geography is used only when the app is in debug mode.
+     * @note This only applies when running the app in debug mode.
+     *
+     * @param userGeography - The mock user geography to simulate.
      */
     setConsentFlowDebugUserGeography(userGeography: ConsentFlowUserGeography): void;
 
     /**
-     * Shows the CMP flow to an existing user.
-     * Note that this resets the user’s existing consent information.
-     *
-     * The function returns when the flow finishes showing. On success, returns null. On failure,
-     * returns one of the {@link CMPError} codes.
+     * Displays the CMP flow for an existing user and resets their consent status.
      *
-     * @return {Promise<CMPError|null>}
+     * @returns A promise that resolves to `null` on success, or a {@link CMPError} on failure.
      */
     showCmpForExistingUser(): Promise<CMPError | null>;
 
     /**
-     * Returns true if a supported CMP SDK is detected.
+     * Checks if a supported CMP SDK is available.
      *
-     * @return {boolean}
+     * @returns A promise that resolves to `true` if a CMP is detected.
      */
     hasSupportedCmp(): Promise<boolean>;
 
     /**
-     * Adds a segment. Both the key and the values must be integers.
+     * Adds a new user segment.
      *
-     * @param key An integer key.
-     * @param values An array of integers.
-     * @returns A promise that resolves upon the successful addition. The resolved object contains
-     * void.
-     * @throws Throws an error if the segments can not be added.
+     * @param key - An integer key identifying the segment.
+     * @param values - An array of integer values for the segment.
+     * @returns A promise that resolves on success, or rejects if the operation fails.
      */
     addSegment(key: number, values: number[]): Promise<void>;
 
     /**
-     * Returns a list of segments.
+     * Retrieves the list of user segments.
      *
-     * @returns A promise that resolves upon a successful inquiry. The resolved object contains a
-     * Map object that holds a list of segments, each represented by a key and an array of integers.
-     * @throws Throws an error if the segments can not be gotten.
+     * @returns A promise that resolves to a map of segment keys to arrays of values,
+     * or `null` if no segments are available.
      */
     getSegments(): Promise<Map<number, number[]> | null>;
 };

package/src/types/BannerAd.ts

@@ -1,46 +1,52 @@
 import type { ViewAdType } from './ViewAd';
 import type { AdViewPosition } from '../AdView';
 
+/**
+ * Defines the interface for managing banner ads.
+ * Extends {@link ViewAdType} with banner-specific layout and customization methods.
+ */
 export type BannerAdType = ViewAdType & {
     /**
-     * Creates a banner at the specified position and offsets.
+     * Creates a banner ad at the specified position and optional pixel offsets.
      *
-     * @param adUnitId The Ad Unit ID to load ads for.
-     * @param position {@ AdViewPosition} position.
-     * @param xOffset Horizontal offset from the left position.
-     * @param yOffset Vertical offset from the top position.
+     * @param adUnitId - The ad unit ID to load ads for.
+     * @param position - The position of the banner on screen.
+     * @param xOffset - Optional horizontal offset from the left (default: 0).
+     * @param yOffset - Optional vertical offset from the top (default: 0).
+     * @param isAdaptive - Optional flag to enable adaptive banners (default: true).
      */
-    createAd(adUnitId: string, position: AdViewPosition, xOffset?: number, yOffset?: number): void;
+    createAd(adUnitId: string, position: AdViewPosition, xOffset?: number, yOffset?: number, isAdaptive?: boolean): void;
 
     /**
-     * Sets a background color for the banner.
+     * Sets the background color of the banner.
      *
-     * @param adUnitId The Ad Unit ID to load ads for.
-     * @param hexColorCode Hexadecimal color (#rrggbb).
+     * @param adUnitId - The ad unit ID of the banner.
+     * @param hexColorCode - A hex color string (e.g. "#FFFFFF").
      */
     setBackgroundColor(adUnitId: string, hexColorCode: string): void;
 
     /**
-     * Sets the banner width.
+     * Sets the width of the banner.
      *
-     * @param adUnitId The Ad Unit ID to load ads for.
-     * @param width The desired banner width.
+     * @param adUnitId - The ad unit ID of the banner.
+     * @param width - Desired width in pixels.
      */
     setWidth(adUnitId: string, width: number): void;
 
     /**
-     * Updates the banner position offsets.
+     * Updates the position offsets of the banner after creation.
      *
-     * @param adUnitId The Ad Unit ID to load ads for.
-     * @param xOffset Horizontal offset from the left position.
-     * @param yOffset Vertical offset from the top position.
+     * @param adUnitId - The ad unit ID of the banner.
+     * @param xOffset - Horizontal offset from the left.
+     * @param yOffset - Vertical offset from the top.
      */
     updateOffsets(adUnitId: string, xOffset: number, yOffset: number): void;
 
     /**
-     * Gets the adaptive banner size for the provided width at the current orientation.
+     * Calculates the adaptive banner height for the given width and current screen orientation.
      *
-     * @param width The banner width.
+     * @param width - The banner width in pixels.
+     * @returns A promise that resolves with the appropriate height.
      */
     getAdaptiveHeightForWidth(width: number): Promise<number>;
 };

package/src/types/CMPError.ts

@@ -1,23 +1,26 @@
 import type { CMPErrorCode } from '../AppLovinMAX';
 
+/**
+ * Represents an error returned from the Consent Management Platform (CMP) flow.
+ */
 export type CMPError = {
     /**
-     * The error code for this error.
+     * The AppLovin-defined CMP error code.
      */
     code: CMPErrorCode;
 
     /**
-     * The error message for this error.
+     * A descriptive error message from the AppLovin SDK.
      */
     message: string;
 
     /**
-     * The error code returned by the CMP.
+     * The raw error code returned by the CMP.
      */
     cmpCode: number;
 
     /**
-     * The error message returned by the CMP.
+     * The raw error message returned by the CMP.
      */
     cmpMessage: string;
 };

package/src/types/Configuration.ts

@@ -1,36 +1,34 @@
 import type { ConsentFlowUserGeography, AppTrackingStatus } from '../AppLovinMAX';
 
 /**
- * Encapsulates data for the AppLovinMAX SDK configuration.
+ * Represents the AppLovin MAX SDK configuration returned after initialization.
  */
 export type Configuration = {
     /**
-     * The country code of this user.
+     * The user's country code.
      */
     countryCode: string;
 
     /**
-     * The user's geography used to determine the type of consent flow shown to the user.  If no
-     * such determination could be made, {@link ConsentFlowUserGeography.UNKNOWN} will be returned.
+     * The user's geographic region used to determine which consent flow to display.
+     * Returns {@link ConsentFlowUserGeography.UNKNOWN} if the geography cannot be determined.
      */
     consentFlowUserGeography: ConsentFlowUserGeography;
 
     /**
-     * Indicates whether or not the user authorizes access to app-related data that can be used for
-     * tracking the user or the device.
-     *
-     * Note: available only on iOS
+     * The user's app tracking transparency status on iOS.
+     * Only available on iOS 14+; undefined on Android.
      */
     appTrackingStatus?: AppTrackingStatus;
 
     /**
-     * Whether or not test mode is enabled for this session.
+     * Indicates whether test mode is enabled for this session.
      *
-     * @return {boolean} true in one of the following cases:
-     * 1. {@link AppLovinMAX.setTestDeviceAdvertisingIds()} was called with current device's GAID prior to SDK initialization.
-     * 2. Current device was registered as a test device through MAX dashboard -> MAX Test Devices prior to SDK initialization.
-     * 3. Test mode was manually enabled for this session through the Mediation Debugger during the last session.
-     * 4. Current device is an emulator.
+     * Returns `true` if any of the following conditions are met:
+     * - {@link AppLovinMAX.setTestDeviceAdvertisingIds()} was called with the current device's GAID before SDK initialization.
+     * - The current device was registered via the MAX dashboard under "Test Devices".
+     * - Test mode was manually enabled in the Mediation Debugger in a previous session.
+     * - The app is running on an emulator.
      */
     isTestModeEnabled: boolean;
 };

package/src/types/FullscreenAd.ts

@@ -3,139 +3,132 @@ import type { AdInfo, AdLoadFailedInfo, AdDisplayFailedInfo } from './AdInfo';
 import type { LocalExtraParameterValue } from './AdProps';
 
 /**
- * Defines a full-screen ad (i.e Intestitial / Rewarded / AppOpen)
+ * Defines the interface for managing full-screen ads such as Interstitial, Rewarded, and AppOpen ads.
  */
 export type FullscreenAdType = {
     /**
-     * Whether or not this ad is ready to be shown.
+     * Checks whether an ad is ready to be shown.
      *
-     * @param adUnitId The ad unit ID of the ad to check whether it is ready to be shown.
+     * @param adUnitId - The ad unit ID to check.
+     * @returns A promise that resolves to `true` if the ad is ready.
      */
     isAdReady(adUnitId: string): Promise<boolean>;
 
     /**
-     * Loads an interstitial ad.
+     * Loads a full-screen ad for the given ad unit ID.
      *
-     * @param adUnitId The ad unit ID to load an ad for.
+     * @param adUnitId - The ad unit ID to load.
      */
     loadAd(adUnitId: string): void;
 
     /**
-     * Shows the loaded interstitial ad, optionallly for a given placement and custom data to tie ad
-     * events to.
+     * Shows a loaded full-screen ad.
      *
-     * @param adUnitId The ad unit ID of the ad to show.
-     * @param placement The placement to tie the showing ad's events to.
-     * @param customData The custom data to tie the showing ad's events to. Maximum size is 8KB.
+     * @param adUnitId - The ad unit ID of the ad to show.
+     * @param placement - Optional placement name for event reporting.
+     * @param customData - Optional custom string data (max size: 8 KB).
      */
     showAd(adUnitId: string, placement?: string | null, customData?: string | null): void;
 
     /**
-     * Sets an extra key/value parameter for the ad.
+     * Sets an extra parameter to pass to the SDK for the specified ad unit.
      *
-     * @param adUnitId The ad unit ID of the ad to set a parameter for.
-     * @param key Parameter key.
-     * @param value Parameter value.
+     * @param adUnitId - The ad unit ID.
+     * @param key - The parameter name.
+     * @param value - The parameter value or `null` to clear it.
      */
     setExtraParameter(adUnitId: string, key: string, value: string | null): void;
 
     /**
-     * Sets a local extra parameter to pass to the adapter instances.
+     * Sets a local extra parameter to pass to the adapter for the specified ad unit.
      *
-     * @param adUnitId The ad unit ID of the ad to set a local parameter for.
-     * @param key Parameter key.
-     * @param value Parameter value.
+     * @param adUnitId - The ad unit ID.
+     * @param key - The parameter name.
+     * @param value - The parameter value (string, number, boolean, object, or null).
      */
     setLocalExtraParameter(adUnitId: string, key: string, value: LocalExtraParameterValue): void;
 
     /**
-     * Adds the specified event listener to receive {@link AdInfo} when a full-screen ad loads a new ad.
+     * Registers a listener for when an ad is successfully loaded.
      *
-     * @param listener Listener to be notified.
+     * @param listener - Callback to be notified with {@link AdInfo}.
      */
     addAdLoadedEventListener(listener: AdEventListener<AdInfo>): void;
 
     /**
-     * Removes the event listener to receive {@link AdInfo} when a full-screen ad loads a new ad.
+     * Unregisters the ad loaded listener.
      */
     removeAdLoadedEventListener(): void;
 
     /**
-     * Adds the specified event listener to receive {@link AdLoadFailedInfo} when a full-screen ad
-     * could not load a new ad.
+     * Registers a listener for when an ad fails to load.
      *
-     * @param listener Listener to be notified.
+     * @param listener - Callback to be notified with {@link AdLoadFailedInfo}.
      */
     addAdLoadFailedEventListener(listener: AdEventListener<AdLoadFailedInfo>): void;
 
     /**
-     * Removes the event listener to receive {@ link adLoadFailedInfo} when a full-screen ad could
-     * not load a new ad.
+     * Unregisters the ad load failure listener.
      */
     removeAdLoadFailedEventListener(): void;
 
     /**
-     * Adds the specified event listener to receive {@link AdInfo} when the user clicks the ad.
+     * Registers a listener for ad click events.
      *
-     * @param listener Listener to be notified.
+     * @param listener - Callback to be notified with {@link AdInfo}.
      */
     addAdClickedEventListener(listener: AdEventListener<AdInfo>): void;
 
     /**
-     * Removes the event listener to receive {@link AdInfo} when the user clicks the ad.
+     * Unregisters the ad click listener.
      */
     removeAdClickedEventListener(): void;
 
     /**
-     * Adds the specified event listener to receive {@link AdInfo} when a full-screen ad displays the ad.
+     * Registers a listener for when an ad is displayed.
      *
-     * @param listener Listener to be notified.
+     * @param listener - Callback to be notified with {@link AdInfo}.
      */
     addAdDisplayedEventListener(listener: AdEventListener<AdInfo>): void;
 
     /**
-     * Removes the event listener to receive {@link AdInfo} when a full-screen ad displays the ad.
+     * Unregisters the ad display listener.
      */
     removeAdDisplayedEventListener(): void;
 
     /**
-     * Adds the specified event listener to receive {@link AdDisplayFailedInfo} when a full-screen
-     * ad fails to display the ad.
+     * Registers a listener for when an ad fails to display.
      *
-     * @param listener Listener to be notified.
+     * @param listener - Callback to be notified with {@link AdDisplayFailedInfo}.
      */
     addAdFailedToDisplayEventListener(listener: AdEventListener<AdDisplayFailedInfo>): void;
 
     /**
-     * Removes the event listener to receive {@link AdDisplayFailedInfo} when a full-screen ad
-     * fails to display the ad.
+     * Unregisters the ad display failure listener.
      */
     removeAdFailedToDisplayEventListener(): void;
 
     /**
-     * Adds the specified event listener to receive {@link AdInfo} when a full-screen ad hides the
-     * ad.
+     * Registers a listener for when an ad is hidden (dismissed).
      *
-     * @param listener Listener to be notified.
+     * @param listener - Callback to be notified with {@link AdInfo}.
      */
     addAdHiddenEventListener(listener: AdEventListener<AdInfo>): void;
 
     /**
-     * Removes the event listener to receive {@link AdInfo} when a full-screen ad hides the ad.
+     * Unregisters the ad hidden listener.
      */
     removeAdHiddenEventListener(): void;
 
     /**
-     * Adds the specified event listener to receive {@link AdInfo} when a full-screen ad
-     * pays ad revenue to the publisher.
+     * Registers a listener for when ad revenue is paid.
      *
-     * @param listener Listener to be notified.
+     * @param listener - Callback to be notified with {@link AdInfo}.
      */
     addAdRevenuePaidListener(listener: AdEventListener<AdInfo>): void;
 
     /**
-     * Removes the event listener to receive {@link AdInfo} when a full-screen ad pays
-     * ad revenue to the publisher.
+     * Unregisters the ad revenue paid listener.
      */
     removeAdRevenuePaidListener(): void;
 };

package/src/types/MRecAd.ts

@@ -1,12 +1,16 @@
 import type { ViewAdType } from './ViewAd';
 import type { AdViewPosition } from '../AdView';
 
+/**
+ * Defines the interface for managing MREC ads.
+ * Extends {@link ViewAdType} with MREC-specific creation logic.
+ */
 export type MRecAdType = ViewAdType & {
     /**
-     * Creates a MREC at the specified position.
+     * Creates an MREC ad at the specified screen position.
      *
-     * @param adUnitId The Ad Unit ID to  to load ads for.
-     * @param position {@link AdViewPosition} position.
+     * @param adUnitId - The ad unit ID to load the ad for.
+     * @param position - The desired position for the MREC, defined by {@link AdViewPosition}.
      */
     createAd(adUnitId: string, position: AdViewPosition): void;
 };

package/src/types/NativeAd.ts

@@ -1,54 +1,55 @@
 /**
- * Represents a native ad for rendering in {@link NativeAdView}. This type is intended for internal use only.
+ * Represents the structure of a native ad used internally by {@link NativeAdView}.
+ * This type is intended for internal use only.
  */
 export type NativeAd = {
     /**
-     * The native ad title text.
+     * The ad title text.
      */
     title?: string | null;
 
     /**
-     * The native ad advertiser text.
+     * The advertiser name.
      */
     advertiser?: string | null;
 
     /**
-     * The native ad body text.
+     * The ad body text.
      */
     body?: string | null;
 
     /**
-     * The native ad CTA button text.
+     * The call-to-action text.
      */
     callToAction?: string | null;
 
     /**
-     * Whether or not this has an image icon.
+     * Indicates whether an icon image is available.
      */
     image?: boolean;
 
     /**
-     * The data of the icon.
+     * The base64-encoded image source for the icon (if provided inline).
      */
     imageSource?: string | null;
 
     /**
-     * The URL string of the icon.
+     * The URL of the icon image.
      */
     url?: string;
 
     /**
-     * The star rating of the native ad.
+     * The star rating of the ad, typically in the range [0.0 – 5.0].
      */
     starRating?: number;
 
     /**
-     * Whether or not the Options view is available.
+     * Whether the native Options view is available.
      */
     isOptionsViewAvailable: boolean;
 
     /**
-     * Whether or not the Media view is available.
+     * Whether the native Media view (video or image) is available.
      */
     isMediaViewAvailable: boolean;
 };

package/src/types/NativeAdViewProps.ts

@@ -1,16 +1,17 @@
 import type { AdProps } from './AdProps';
 
 /**
- * A handler of {@link NativeAdView}.
+ * A reference handler for the {@link NativeAdView} component.
  */
 export type NativeAdViewHandler = {
     /**
-     * Loads a native ad.
+     * Triggers a native ad load.
      */
     loadAd(): void;
 };
 
 /**
- * Represents a {@link NativeAdView}.
+ * Props passed to the {@link NativeAdView} component.
+ * Extends the base {@link AdProps} used for all ad components.
  */
 export type NativeAdViewProps = AdProps;