react-native-applovin-max 9.0.0 → 9.2.0

package/src/types/AdInfo.ts

@@ -2,85 +2,83 @@ import type { ErrorCode } from '../ErrorCode';
 import type { AdViewId } from './AdViewProps';
 
 /**
- * Represents an ad that has been served by AppLovin MAX.
+ * Represents a successfully loaded ad served by AppLovin MAX.
  */
 export type AdInfo = {
     /**
-     * The ad unit ID for which this ad was loaded.
+     * The ad unit ID that was used to load this ad.
      */
     adUnitId: string;
 
     /**
-     * The format of this ad.
+     * The format of the ad.
      */
     adFormat: string;
 
     /**
-     * The unique ID of the native UI component AdView.
+     * The unique identifier of the associated native AdView component, if any.
      */
     adViewId?: AdViewId;
 
     /**
-     * The creative ID tied to the ad, if any. You can report creative issues to the corresponding
-     * ad network using this ID.
+     * The creative ID associated with the ad.
+     * This can be used to report issues with the creative.
      *
-     * @see {@link https://support.applovin.com/hc/en-us/articles/13986039797389-Creative-Debugger#h_01HC10588YYDNZMS1GPCVRD2E7}
+     * @see https://support.applovin.com/hc/en-us/articles/13986039797389
      */
     creativeId?: string | null;
 
     /**
-     * The ad network from which this ad was loaded.
-     *
-     * @see {@link https://support.applovin.com/hc/en-us/articles/13986039797389-Creative-Debugger#h_01HC10588YWTJHYE1E35HWQTX7}
+     * The name of the ad network that served the ad.
      */
     networkName: string;
 
     /**
-     * The ad network placement for which this ad was loaded.
+     * The name of the placement as configured on the ad network side.
      */
     networkPlacement: string;
 
     /**
-     * The placement name that you assign when you integrate each ad format, for granular reporting
-     * in postbacks.
+     * The custom placement name defined in your integration.
+     * Used for postback reporting.
      */
     placement?: string | null;
 
     /**
-     *  The ad’s revenue amount. In the case where no revenue amount exists, or it is not available
-     *  yet, returns 0.
+     * The revenue generated from the ad impression, in USD.
+     * Defaults to 0 if not available.
      */
     revenue: number;
 
     /**
-     * The precision of the revenue value for this ad.
+     * The precision level of the revenue value reported for this ad.
      *
-     * Possible values are:
-     * - "publisher_defined" - If the revenue is the price assigned to the line item by the publisher.
-     * - "exact" - If the revenue is the resulting price of a real-time auction.
-     * - "estimated" - If the revenue is the price obtained by auto-CPM.
-     * - "undefined" - If we do not have permission from the ad network to share impression-level data.
-     * - "" - An empty string, if revenue and precision are not valid (for example, in test mode).
+     * Possible values:
+     * - `"exact"` — Revenue from a real-time auction.
+     * - `"estimated"` — Revenue estimated via auto-CPM.
+     * - `"publisher_defined"` — Revenue set manually by the publisher.
+     * - `"undefined"` — The ad network does not permit impression-level revenue data.
+     * - `""` — Empty when revenue and precision are unavailable (e.g., in test mode).
      */
     revenuePrecision: string;
 
     /**
-     * The DSP network that provides the loaded ad when the ad is served through AppLovin Exchange.
+     * The name of the DSP (Demand-Side Platform), if served through AppLovin Exchange.
      */
     dspName?: string | null;
 
     /**
-     * The latency of the mediation ad load request in milliseconds.
+     * Total mediation load time in milliseconds.
      */
     latencyMillis: number;
 
     /**
-     * The underlying waterfall of ad responses.
+     * The full ad waterfall associated with this ad request.
      */
     waterfall?: AdWaterfallInfo;
 
     /**
-     * The native ad info.
+     * The native ad, if available.
      */
     nativeAd?: AdNativeInfo | null;
 
@@ -94,264 +92,259 @@ export type AdInfo = {
 };
 
 /**
- * Encapsulates various data for MAX load errors.
+ * Represents a failure when attempting to load an ad.
  */
 export type AdLoadFailedInfo = {
     /**
-     * The ad unit ID for which this ad was loaded.
+     * The ad unit ID for which the load failed.
      */
     adUnitId: string;
 
     /**
-     * The unique ID of the native UI component AdView.
+     * The native AdView component ID, if available.
      */
     adViewId?: AdViewId;
 
     /**
-     * The error code for the error.
+     * AppLovin MAX-defined error code.
      */
     code: ErrorCode;
 
     /**
-     * The error message for the error.
+     * Descriptive message for the error.
      */
     message?: string | null;
 
     /**
-     * The mediated network's error code for the error.
+     * Error code from the mediated network.
      */
     mediatedNetworkErrorCode: number;
 
     /**
-     * The mediated network's error message for the error.
+     * Error message from the mediated network.
      */
     mediatedNetworkErrorMessage: string;
 
     /**
-     * The message for the error.
+     * Additional debug information for ad load failure (legacy).
      */
     adLoadFailureInfo?: string | null;
 
     /**
-     * The underlying waterfall of ad responses.
+     * Waterfall data associated with the failed request.
      */
     waterfall?: AdWaterfallInfo | null;
 };
 
 /**
- * Encapsulates various data for MAX display errors.
+ * Represents an error that occurred when displaying an ad.
  */
 export type AdDisplayFailedInfo = AdInfo & {
     /**
-     * The error code for the error.
+     * AppLovin MAX-defined error code.
      */
     code: ErrorCode;
 
     /**
-     * The error message for the error.
+     * Descriptive message for the error.
      */
     message?: string | null;
 
     /**
-     * The mediated network's error code for the error.
+     * Error code from the mediated network.
      */
     mediatedNetworkErrorCode: number;
 
     /**
-     * The mediated network's error message for the error.
+     * Error message from the mediated network.
      */
     mediatedNetworkErrorMessage: string;
 };
 
 /**
- * Represents a reward given to the user.
+ * Represents a successful reward event from a rewarded ad.
  */
 export type AdRewardInfo = AdInfo & {
     /**
-     * The reward label.
+     * The label of the reward.
      */
     rewardLabel?: string | null;
 
     /**
-     * The rewarded amount.
+     * The reward amount, as a string.
      */
     rewardAmount: string;
 };
 
 /**
- * Represents a native ad.
+ * Describes metadata for a native ad, including asset availability.
  */
 export type AdNativeInfo = {
     /**
-     * The native ad title text for {@link TitleView}.
+     * Title text of the native ad for use in {@link TitleView}.
      */
     title?: string;
 
     /**
-     * The native ad advertiser text for {@link AdvertiserView}.
+     * Advertiser name for {@link AdvertiserView}.
      */
     advertiser?: string;
 
     /**
-     * The native ad body text for {@link BodyView}}.
+     * Body text for {@link BodyView}.
      */
     body?: string;
 
     /**
-     * The native ad CTA (call to action) text for {@link CallToActionView}.
+     * Call-to-action label for {@link CallToActionView}.
      */
     callToAction?: string;
 
     /**
-     * The star rating of the native ad in the [0.0, 5.0] range for {@link StarRatingView}, if provided by the network.
+     * Star rating (0.0 to 5.0) for {@link StarRatingView}.
      */
     starRating?: number;
 
     /**
-     * The aspect ratio (width-to-height) for {@link MediaView} if provided by the network.
+     * Aspect ratio (width / height) for {@link MediaView}, if available.
      */
     mediaContentAspectRatio?: number;
 
     /**
-     * Whether or not the content for {@link IconView} is available.
+     * Whether an icon image is available for {@link IconView}.
      */
     isIconImageAvailable: boolean;
 
     /**
-     * Whether or not the content for {@link OptionsView} is available.
+     * Whether the options menu view is available for {@link OptionsView}.
      */
     isOptionsViewAvailable: boolean;
 
     /**
-     * Whether or not the content for {@link MediaView} is available.
+     * Whether a media view is available for {@link MediaView}.
      */
     isMediaViewAvailable: boolean;
 };
 
 /**
- * Represents an ad waterfall, encapsulating various metadata such as total latency, underlying ad
- * responses, etc.
+ * Contains metadata about the ad waterfall evaluated during an ad request.
  */
 export type AdWaterfallInfo = {
     /**
-     * The ad waterfall name.
+     * The waterfall name for this request.
      */
     name: string;
 
     /**
-     * The ad waterfall test name.
+     * The test name, if the waterfall is part of an A/B test.
      */
     testName: string;
 
     /**
-     * The list of {@link AdNetworkResponseInfo} info objects relating to each ad in the waterfall,
-     * ordered by their position.
+     * Ordered list of network responses attempted during mediation.
      */
     networkResponses: AdNetworkResponseInfo[];
 
     /**
-     * The total latency in milliseconds for this waterfall to finish processing.
+     * Total time taken to complete the waterfall, in milliseconds.
      */
     latencyMillis: number;
 };
 
 /**
- * This enum contains possible states of an ad in the waterfall.
- * Each adapter response {@link AdNetworkResponseInfo} corresponds to one of these states.
+ * Enumeration of possible ad load states for each network in the waterfall.
  */
 export enum AdLoadState {
     /**
-     * The AppLovin MAX SDK did not attempt to load an ad from this network in the waterfall because
-     * an ad higher in the waterfall loaded successfully.
+     * SDK did not attempt to load an ad from this network.
      */
     LoadStateAdLoadNotAttempted = 0,
 
     /**
-     * An ad successfully loaded from this network.
+     * An ad was successfully loaded from this network.
      */
     LoadStateAdLoaded = 1,
 
     /**
-     * An ad failed to load from this network.
+     * The network failed to load an ad.
      */
     LoadStateAdFailedToLoad = 2,
 }
 
 /**
- * Encapsulates load and display errors.
+ * General error info object used in waterfall response details.
  */
 export type AdErrorInfo = {
     /**
-     * The error code for the error.
+     * AppLovin MAX-defined error code.
      */
     code: ErrorCode;
 
     /**
-     * The error message for the error.
+     * Descriptive error message.
      */
     message?: string;
 
     /**
-     * @deprecated
+     * @deprecated Use `message` instead.
      */
     adLoadFailureInfo?: string;
 };
 
 /**
- * This class represents an ad response in a waterfall.
+ * Contains information about a single mediated network response.
  */
 export type AdNetworkResponseInfo = {
     /**
-     * The state of the ad that this object represents. For more info, see the {@link AdLoadState} enum.
+     * The result of the load attempt.
      */
     adLoadState: AdLoadState;
 
     /**
-     * The mediated network that this adapter response info object represents.
+     * Metadata about the mediated network.
      */
     mediatedNetwork?: AdMediatedNetworkInfo;
 
     /**
-     * The credentials used to load an ad from this adapter, as entered in the AppLovin MAX dashboard.
+     * A key-value map of adapter-specific credentials, as configured in the MAX dashboard.
      */
     credentials: { [key: string]: string | number | boolean | object | null };
 
     /**
-     * The ad load error this network response resulted in. Will be unavailable if an attempt to
-     * load an ad has not been made or an ad was loaded successfully (i.e. {@link adLoadState}
-     * is NOT LoadStateAdFailedToLoad).
+     * The ad load error resulting from this network response. This will be unavailable if no ad load
+     * attempt was made or if the ad loaded successfully (i.e., [adLoadState] is NOT [LoadStateAdFailedToLoad]).
      */
     error?: AdErrorInfo;
 
     /**
-     * The amount of time the network took to load (either successfully or not) an ad, in milliseconds.
-     * If an attempt to load an ad has not been made (i.e. {@link adLoadState} is LoadStateAdLoadNotAttempted),
-     * the value will be -1.
+     * The amount of time, in milliseconds, the network took to load an ad—regardless of success.
+     * If no ad load attempt was made (i.e., [adLoadState] is [LoadStateAdLoadNotAttempted]),
+     * this value will be -1.
      */
     latencyMillis: number;
 };
 
 /**
- * This class represents information for a mediated network.
+ * Metadata about a mediated ad network.
  */
 export type AdMediatedNetworkInfo = {
     /**
-     * The name of the mediated network.
+     * Name of the mediated network.
      */
     name: string;
 
     /**
-     * The class name of the adapter for the mediated network.
+     * Fully-qualified adapter class name.
      */
     adapterClassName: string;
 
     /**
-     * The version of the adapter for the mediated network.
+     * Version of the adapter.
      */
     adapterVersion: string;
 
     /**
-     * The version of the mediated network’s SDK.
+     * Version of the mediated network’s SDK.
      */
     sdkVersion: string;
 };

package/src/types/AdProps.ts

@@ -1,64 +1,63 @@
 import type { AdDisplayFailedInfo, AdInfo, AdLoadFailedInfo } from './AdInfo';
 
 /**
- * Local extra parameters can be of type: string, number, boolean, array, map, and null.
+ * Represents the allowed value types for local extra parameters passed to the ad adapter.
+ * Can be a primitive, object, or null.
  */
 export type LocalExtraParameterValue = string | number | boolean | object | null;
 
 /**
- * Defines the base properties for the UI component ads i.e {@link AdView} and {@link NativeAdView}.
+ * Defines the base props shared by ad UI components like {@link AdView} and {@link NativeAdView}.
  */
 export type AdProps = {
     /**
-     * A string value representing the ad unit ID to load ads for.
+     * The ad unit ID used to load ads.
      */
     adUnitId: string;
 
     /**
-     * A string value representing the placement name that you assign when you integrate each ad
-     * format, for granular reporting in ad events.
+     * The placement name defined in your integration, used for granular reporting.
      */
     placement?: string | null;
 
     /**
-     * The custom data to tie the showing ad to.
+     * Optional custom data to attach to the ad, used for analytics or targeting.
      */
     customData?: string | null;
 
     /**
-     * A dictionary value representing the extra parameters to set a list of key-value string pairs
-     * for the ad.
+     * Extra parameters to be sent as key-value string pairs.
      */
     extraParameters?: { [key: string]: string };
 
     /**
-     * A dictionary value representing the local extra parameters to set a list of key-value pairs
-     * to pass to the adapter instances.
+     * Local extra parameters sent to the adapter instance.
+     * Supports string and boolean values only.
      */
     localExtraParameters?: { [key: string]: string | boolean };
 
     /**
-     * A callback fuction that {@link AdView} or {@link NativeAdView} fires when it loads a new ad.
+     * Called when a new ad is successfully loaded.
      */
     onAdLoaded?: (adInfo: AdInfo) => void;
 
     /**
-     * A callback fuction that {@link AdView} or {@link NativeAdView} fires when it could not load a new ad.
+     * Called when the SDK fails to load a new ad.
      */
     onAdLoadFailed?: (error: AdLoadFailedInfo) => void;
 
     /**
-     * A callback fuction that {@link AdView} or {@link NativeAdView} fires when it fails to display the ad.
+     * Called when the ad fails to display after being loaded.
      */
     onAdDisplayFailed?: (error: AdDisplayFailedInfo) => void;
 
     /**
-     * A callback fuction that {@link AdView} or {@link NativeAdView} fires when the user clicks the ad.
+     * Called when the ad is clicked by the user.
      */
     onAdClicked?: (adInfo: AdInfo) => void;
 
     /**
-     * A callback fuction that {@link AdView} or {@link NativeAdView} fires when it pays ad revenue to the publisher.
+     * Called when ad revenue is paid to the publisher.
      */
     onAdRevenuePaid?: (adInfo: AdInfo) => void;
 };

package/src/types/AdViewProps.ts

@@ -3,95 +3,99 @@ import type { AdInfo } from './AdInfo';
 import type { AdFormat } from '../AdView';
 
 /**
- * A handler of {@link AdView}.
+ * A reference to the {@link AdView} instance, allowing imperative control.
  */
 export type AdViewHandler = {
     /**
-     * If the {@link loadOnMount} attribute is set to false, you can call this API to start loading ads in this AdView.
+     * Triggers a manual ad load starting.
+     * This is only needed if {@link loadOnMount} is set to `false`.
      */
     loadAd(): void;
 };
 
 /**
- * A unique identifier for referencing a specific AdView instance.
+ * A unique identifier for referencing a specific {@link AdView} instance.
  *
- * - If the value is a number, it represents the ID of a preloaded or assigned AdView.
- * - A value of `undefined` indicates that the AdView has not been preloaded or assigned an ID yet.
+ * - A number represents the ID of a preloaded or managed AdView.
+ * - `undefined` means the AdView is not preloaded or assigned an ID.
  */
 export type AdViewId = number | undefined;
 
 /**
- * Represents an {@link AdView} - Banner / MREC.
+ * Props used to configure and render an {@link AdView} (i.e. Banner or MREC).
  */
 export type AdViewProps = AdProps & {
     /**
-     * An enum value representing the ad format to load ads for. Must be either
-     * {@link AdFormat.BANNER} or {@link AdFormat.MREC}.
+     * The ad format to load for this view.
+     * Must be {@link AdFormat.BANNER} or {@link AdFormat.MREC}.
      */
     adFormat: AdFormat;
 
     /**
-     * A unique identifier representing the AdView instance.
-     * Used to manage and track the specific AdView.
+     * A unique identifier for the AdView instance.
+     * Used for tracking and preloading specific ad views.
      */
     adViewId?: AdViewId;
 
     /**
-     * A boolean indicating whether adaptive banners are enabled.
+     * Enables adaptive banner sizing if `true`.
+     * Ignored for MREC ads.
      */
     adaptiveBannerEnabled?: boolean;
 
     /**
-     * A boolean indicating whether auto-refresh is enabled.
-     * Auto-refresh is enabled by default.
+     * Enables or disables automatic ad refresh.
+     * Defaults to `true`.
      */
     autoRefresh?: boolean;
 
     /**
-     * A boolean indicating whether an ad should load automatically
-     * when the {@link AdView} is mounted. Defaults to `true`.
+     * If `true`, the ad will be loaded automatically when the component mounts.
+     * Set to `false` for ads to be loaded manually using the ref after the component mounts.
+     *
+     * @default true
      */
     loadOnMount?: boolean;
 
     /**
-     * A callback function triggered when the {@link AdView} expands the ad.
-     *
-     * @param adInfo - Information about the ad that was expanded.
+     * Called when the ad is expanded.
      */
     onAdExpanded?: (adInfo: AdInfo) => void;
 
     /**
-     * A callback function triggered when the {@link AdView} collapses the ad.
-     *
-     * @param adInfo - Information about the ad that was collapsed.
+     * Called when the ad collapses back to its original state.
      */
     onAdCollapsed?: (adInfo: AdInfo) => void;
 };
 
 /**
- * A list of options to create a native UI component for preloading {@link AdView}.
+ * Options used when preloading a native UI {@link AdView} component.
  */
 export type NativeUIComponentAdViewOptions = {
     /**
-     * A string value representing the placement name that you assign when you integrate each ad
-     * format, for granular reporting in ad events.
+     * Whether adaptive banner sizing is enabled. Defaults to `true`.
+     */
+    isAdaptive?: boolean;
+
+    /**
+     * The placement name used for analytics and reporting.
      */
     placement?: string | null;
 
     /**
-     * The custom data to tie the showing ad to.
+     * Custom data to associate with the ad for postbacks or targeting.
      */
     customData?: string | null;
 
     /**
-     * A dictionary value representing the extra parameters to set a list of key-value string pairs
-     * for the ad.
+     * A dictionary of key-value pairs used to pass extra parameters
+     * to the SDK (string-only values).
      */
     extraParameters?: { [key: string]: string | null };
 
     /**
-     * A dictionary value representing the local extra parameters to set a list of key-value pairs
-     * to pass to the adapter instances.
+     * A dictionary of key-value pairs used to pass local extra parameters
+     * to the mediation adapter (string, boolean, number, etc.).
      */
     localExtraParameters?: { [key: string]: LocalExtraParameterValue };
 };