react-native-applovin-max 8.2.0 → 9.1.0

package/src/nativeAd/NativeAdViewComponents.tsx

@@ -1,150 +1,181 @@
+/**
+ * Provides pre-styled React Native components for each native ad asset view:
+ *
+ * - TitleView
+ * - AdvertiserView
+ * - BodyView
+ * - CallToActionView
+ * - IconView
+ * - OptionsView
+ * - MediaView
+ * - StarRatingView
+ *
+ * Each component pulls ad content and view refs from NativeAdView context,
+ * and must be rendered inside a {@link NativeAdView}.
+ */
+
 import * as React from 'react';
-import { useContext, useRef, useEffect, useCallback, useMemo } from 'react';
-import { findNodeHandle, Text, Image, View, TouchableOpacity, StyleSheet, Platform } from 'react-native';
-import type { ViewProps, ImageProps, TextStyle, StyleProp, TextProps } from 'react-native';
+import { useContext, useMemo } from 'react';
+import { Text, Image, View, TouchableOpacity, StyleSheet, Platform } from 'react-native';
+import type { ViewProps, ImageProps, TextProps } from 'react-native';
 import { NativeAdViewContext } from './NativeAdViewProvider';
-import type { NativeAd } from '../types/NativeAd';
-
-// Custom hook to handle setting native ad view properties and return nativeAd
-const useNativeAdViewProps = (nativeAdProp: keyof NativeAd, ref: React.RefObject<any>, nativePropKey: string) => {
-    const { nativeAd, nativeAdView } = useContext(NativeAdViewContext);
-
-    const setNativeProps = useCallback(() => {
-        if (!nativeAd[nativeAdProp] || !ref.current) return;
-        nativeAdView?.setNativeProps({
-            [nativePropKey]: findNodeHandle(ref.current),
-        });
-    }, [nativeAd, nativeAdProp, nativeAdView, ref, nativePropKey]);
-
-    useEffect(() => {
-        setNativeProps();
-    }, [setNativeProps]);
-
-    return nativeAd;
-};
 
+/**
+ * Renders the native ad’s title.
+ */
 export const TitleView = (props: TextProps) => {
-    const titleRef = useRef<Text | null>(null);
-    const nativeAd = useNativeAdViewProps('title', titleRef, 'titleView');
-
+    const { titleRef, nativeAd } = useContext(NativeAdViewContext);
     return (
         <Text {...props} ref={titleRef}>
-            {nativeAd.title || null}
+            {nativeAd.title ?? ''}
         </Text>
     );
 };
 
+/**
+ * Renders the advertiser name.
+ */
 export const AdvertiserView = (props: TextProps) => {
-    const advertiserRef = useRef<Text | null>(null);
-    const nativeAd = useNativeAdViewProps('advertiser', advertiserRef, 'advertiserView');
-
+    const { advertiserRef, nativeAd } = useContext(NativeAdViewContext);
     return (
         <Text {...props} ref={advertiserRef}>
-            {nativeAd.advertiser || null}
+            {nativeAd.advertiser ?? ''}
         </Text>
     );
 };
 
+/**
+ * Renders the ad’s body text (description).
+ */
 export const BodyView = (props: TextProps) => {
-    const bodyRef = useRef<Text | null>(null);
-    const nativeAd = useNativeAdViewProps('body', bodyRef, 'bodyView');
-
+    const { bodyRef, nativeAd } = useContext(NativeAdViewContext);
     return (
         <Text {...props} ref={bodyRef}>
-            {nativeAd.body || null}
+            {nativeAd.body ?? ''}
         </Text>
     );
 };
 
+/**
+ * Renders the call-to-action label.
+ * On iOS, wraps the text with a TouchableOpacity for better click behavior.
+ */
 export const CallToActionView = (props: TextProps) => {
-    const callToActionRef = useRef<Text | null>(null);
-    const nativeAd = useNativeAdViewProps('callToAction', callToActionRef, 'callToActionView');
+    const { callToActionRef, nativeAd } = useContext(NativeAdViewContext);
 
-    // TouchableOpacity disables clicking on certain Android devices.
     if (Platform.OS === 'android') {
         return (
             <Text {...props} ref={callToActionRef}>
-                {nativeAd.callToAction || null}
+                {nativeAd.callToAction ?? ''}
             </Text>
         );
-    } else {
-        return (
-            <TouchableOpacity>
-                <Text {...props} ref={callToActionRef}>
-                    {nativeAd.callToAction || null}
-                </Text>
-            </TouchableOpacity>
-        );
     }
+
+    return (
+        <TouchableOpacity>
+            <Text {...props} ref={callToActionRef}>
+                {nativeAd.callToAction ?? ''}
+            </Text>
+        </TouchableOpacity>
+    );
 };
 
+/**
+ * Renders the icon image for the native ad.
+ * Falls back to a blank placeholder if not available.
+ */
 export const IconView = (props: Omit<ImageProps, 'source'>) => {
-    const imageRef = useRef<Image | null>(null);
-    const nativeAd = useNativeAdViewProps('image', imageRef, 'iconView');
-
-    return nativeAd.url ? (
-        <Image {...props} ref={imageRef} source={{ uri: nativeAd.url }} />
-    ) : nativeAd.image ? (
-        <Image {...props} ref={imageRef} source={0} />
-    ) : (
-        <View {...props} />
-    );
+    const { imageRef, nativeAd } = useContext(NativeAdViewContext);
+    const defaultIcon = require('./img/blank_icon.png');
+
+    const imageSource = useMemo(() => {
+        if (nativeAd?.url) {
+            return { uri: nativeAd.url };
+        }
+        if (nativeAd?.imageSource) {
+            return { uri: `data:image/jpeg;base64,${nativeAd.imageSource}` };
+        }
+        return defaultIcon;
+    }, [nativeAd.url, nativeAd.imageSource, defaultIcon]);
+
+    return <Image {...props} ref={imageRef} source={imageSource} />;
 };
 
+/**
+ * Renders the native ad’s options view.
+ */
 export const OptionsView = (props: ViewProps) => {
-    const viewRef = useRef<View | null>(null);
-    useNativeAdViewProps('isOptionsViewAvailable', viewRef, 'optionsView');
-
-    return <View {...props} ref={viewRef} />;
+    const { optionViewRef } = useContext(NativeAdViewContext);
+    return <View {...props} ref={optionViewRef} />;
 };
 
+/**
+ * Renders the native ad’s media content.
+ */
 export const MediaView = (props: ViewProps) => {
-    const viewRef = useRef<View | null>(null);
-    useNativeAdViewProps('isMediaViewAvailable', viewRef, 'mediaView');
-
-    return <View {...props} ref={viewRef} />;
+    const { mediaViewRef } = useContext(NativeAdViewContext);
+    return <View {...props} ref={mediaViewRef} />;
 };
 
-export const StarRatingView = (props: ViewProps) => {
-    const { style, ...restProps } = props;
+/**
+ * Props for the {@link StarRatingView} component, which displays a star rating
+ * using Unicode stars (★ and ☆) styled with color, shadow, and size.
+ */
+type StarRatingViewProps = ViewProps & {
+    /**
+     * The color used for filled (active) stars.
+     * Defaults to gold (#ffe234).
+     */
+    color?: string;
+
+    /**
+     * The color used for empty (inactive) stars.
+     * Defaults to light gray (#dedede).
+     */
+    shadowColor?: string;
+
+    /**
+     * The size of each star, which also determines their visual size.
+     * Defaults to 10.
+     */
+    size?: number;
+};
 
+/**
+ * Renders the star rating of the ad, using Unicode stars (★ and ☆).
+ * Filled stars are rendered over hollow stars using a clipped view.
+ */
+export const StarRatingView = ({ color = '#ffe234', shadowColor = '#dedede', size = 10, style }: StarRatingViewProps) => {
+    const { nativeAd } = useContext(NativeAdViewContext);
     const maxStarCount = 5;
-    const starColor = StyleSheet.flatten((style as StyleProp<TextStyle>) || {}).color ?? '#ffe234';
-    const starSize = StyleSheet.flatten((style as StyleProp<TextStyle>) || {}).fontSize ?? 10;
 
-    const { nativeAd } = useContext(NativeAdViewContext);
+    const containerStyle = useMemo(() => StyleSheet.flatten([style, styles.starRatingContainer]), [style]);
 
-    // Memoize the star rendering process
     const stars = useMemo(() => {
-        if (!nativeAd.starRating) {
-            return Array.from({ length: maxStarCount }).map((_, index) => (
-                <Text key={index} style={{ fontSize: starSize }}>
-                    {' '}
-                </Text>
-            ));
-        }
+        const starRating = Math.max(0, Math.min(maxStarCount, nativeAd.starRating ?? 0));
 
         return Array.from({ length: maxStarCount }).map((_, index) => {
-            const starRating = nativeAd.starRating!;
-            const width = (starRating - index) * starSize;
+            const isFull = starRating > index;
+            const width = Math.min(size, Math.max(0, (starRating - index) * size));
+
             return (
                 <View key={index}>
-                    <Text style={{ fontSize: starSize, color: starColor }}>{String.fromCodePoint(0x2606)}</Text>
-                    {starRating > index && (
-                        <View style={[{ width: width }, styles.starRating]}>
-                            <Text style={{ fontSize: starSize, color: starColor }}>{String.fromCodePoint(0x2605)}</Text>
+                    <Text style={{ fontSize: size, color: isFull ? color : shadowColor }}>{String.fromCodePoint(0x2606)}</Text>
+                    {isFull && (
+                        <View style={[{ width }, styles.starRating]}>
+                            <Text style={{ fontSize: size, color }}>{String.fromCodePoint(0x2605)}</Text>
                         </View>
                     )}
                 </View>
             );
         });
-    }, [nativeAd.starRating, starColor, starSize]);
+    }, [nativeAd.starRating, color, shadowColor, size]);
 
-    return (
-        <View {...restProps} style={[style, styles.starRatingContainer]}>
-            {stars}
-        </View>
-    );
+    if (!nativeAd.starRating) {
+        return <View style={containerStyle} />;
+    }
+
+    return <View style={containerStyle}>{stars}</View>;
 };
 
 const styles = StyleSheet.create({

package/src/nativeAd/NativeAdViewProvider.tsx

@@ -1,43 +1,91 @@
+/**
+ * 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 } from 'react';
+import { useState, createContext, useRef } from 'react';
 import type { ReactNode } from 'react';
-import type { NativeMethods } from 'react-native';
+import type { Image, NativeMethods, Text, View } from 'react-native';
 import type { NativeAd } from '../types/NativeAd';
-import type { NativeAdViewProps } from '../types/NativeAdViewProps';
+import type { NativeProps } from '../specs/AppLovinMAXNativeAdViewNativeComponent';
+
+/**
+ * Native component type for the rendered NativeAdView.
+ */
+export type NativeAdViewType = React.Component<NativeProps> & NativeMethods;
 
-export type NativeAdViewType = React.Component<NativeAdViewProps> & 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>;
+    bodyRef: React.RefObject<TextRef>;
+    callToActionRef: React.RefObject<TextRef>;
+    imageRef: React.RefObject<ImageRef>;
+    optionViewRef: React.RefObject<ViewRef>;
+    mediaViewRef: React.RefObject<ViewRef>;
     nativeAd: NativeAd;
-    nativeAdView: NativeAdViewType | null;
     setNativeAd: React.Dispatch<React.SetStateAction<NativeAd>>;
-    setNativeAdView: React.Dispatch<React.SetStateAction<NativeAdViewType | null>>;
 };
 
+// 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 },
+    bodyRef: { current: null },
+    callToActionRef: { current: null },
+    imageRef: { current: null },
+    optionViewRef: { current: null },
+    mediaViewRef: { current: null },
     nativeAd: defaultNativeAd,
-    nativeAdView: null,
     setNativeAd: () => {},
-    setNativeAdView: () => {},
 });
 
+/**
+ * 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);
+    const bodyRef = useRef<TextRef | null>(null);
+    const callToActionRef = useRef<TextRef | null>(null);
+    const imageRef = useRef<ImageRef | null>(null);
+    const optionViewRef = useRef<ViewRef | null>(null);
+    const mediaViewRef = useRef<ViewRef | null>(null);
     const [nativeAd, setNativeAd] = useState<NativeAd>(defaultNativeAd);
-    const [nativeAdView, setNativeAdView] = useState<NativeAdViewType | null>(null);
 
+    /**
+     * Memoized context value to avoid unnecessary renders.
+     */
     const providerValue = React.useMemo(
         () => ({
+            titleRef,
+            advertiserRef,
+            bodyRef,
+            callToActionRef,
+            imageRef,
+            optionViewRef,
+            mediaViewRef,
             nativeAd,
-            nativeAdView,
             setNativeAd,
-            setNativeAdView,
         }),
-        [nativeAd, nativeAdView]
+        [nativeAd]
     );
 
     return <NativeAdViewContext.Provider value={providerValue}>{children}</NativeAdViewContext.Provider>;

package/src/specs/AppLovinMAXAdViewNativeComponent.ts

@@ -0,0 +1,157 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import type { Double, DirectEventHandler, WithDefault } from 'react-native/Libraries/Types/CodegenTypes';
+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;
+    adViewId?: Double;
+    networkName: string;
+    networkPlacement: string;
+    creativeId?: string | null;
+    placement?: string | null;
+    revenue: Double;
+    revenuePrecision: string;
+    latencyMillis: Double;
+    dspName?: string | null;
+    size: Readonly<{
+        width: Double;
+        height: Double;
+    }>;
+}>;
+
+/**
+ * Payload for ad load failure events.
+ */
+export type AdLoadFailedEvent = Readonly<{
+    adUnitId: string;
+    adViewId?: Double;
+    code: Double;
+    message?: string | null;
+    mediatedNetworkErrorCode: Double;
+    mediatedNetworkErrorMessage: string;
+    adLoadFailureInfo?: string | null;
+}>;
+
+/**
+ * Payload for ad display failure events.
+ */
+export type AdDisplayFailedEvent = Readonly<{
+    adUnitId: string;
+    adFormat: string;
+    adViewId?: Double;
+    networkName: string;
+    networkPlacement: string;
+    creativeId?: string | null;
+    placement?: string | null;
+    revenue: Double;
+    revenuePrecision: string;
+    latencyMillis: Double;
+    dspName?: string | null;
+    size: Readonly<{
+        width: Double;
+        height: Double;
+    }>;
+    code: Double;
+    message?: string | null;
+    mediatedNetworkErrorCode: Double;
+    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 {
+    /**
+     * 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

@@ -0,0 +1,153 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import type { Double, DirectEventHandler } from 'react-native/Libraries/Types/CodegenTypes';
+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;
+    networkName: string;
+    networkPlacement: string;
+    creativeId?: string | null;
+    placement?: string | null;
+    revenue: Double;
+    revenuePrecision: string;
+    latencyMillis: Double;
+    dspName?: string | null;
+    size: Readonly<{
+        width: Double;
+        height: Double;
+    }>;
+
+    /**
+     * Optional native ad content for display in asset views.
+     */
+    nativeAd?: Readonly<{
+        title?: string;
+        advertiser?: string;
+        body?: string;
+        callToAction?: string;
+        starRating?: Double;
+        mediaContentAspectRatio?: Double;
+        isIconImageAvailable: boolean;
+        isOptionsViewAvailable: boolean;
+        isMediaViewAvailable: boolean;
+    }>;
+
+    /**
+     * Full internal native ad payload used for runtime rendering and view mapping.
+     */
+    nativeAdImpl: Readonly<{
+        title?: string | null;
+        advertiser?: string | null;
+        body?: string | null;
+        callToAction?: string | null;
+        image?: boolean;
+        imageSource?: string | null;
+        url?: string;
+        starRating?: Double;
+        isOptionsViewAvailable: boolean;
+        isMediaViewAvailable: boolean;
+    }>;
+}>;
+
+/**
+ * Payload for native ad load failure events.
+ */
+export type AdLoadFailedEvent = Readonly<{
+    adUnitId: string;
+    code: Double;
+    message?: string | null;
+    mediatedNetworkErrorCode: Double;
+    mediatedNetworkErrorMessage: string;
+    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;
+    }>;
+
+    /** 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 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 {
+    /**
+     * 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>;