cloudx-react-native 3.10.0 → 3.11.0

package/src/CloudXNativeAdView.tsx

@@ -0,0 +1,419 @@
+import * as React from 'react';
+import { useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState, forwardRef } from 'react';
+import { findNodeHandle, View } from 'react-native';
+import type { NativeSyntheticEvent } from 'react-native';
+import NativeCloudXNativeAdView, { Commands } from './specs/CloudXNativeAdViewNativeComponent';
+import type { CloudXNativeAdInfoEvent, CloudXNativeAdLoadFailedEvent } from './specs/CloudXNativeAdViewNativeComponent';
+import { toNativeExtraParameterEntries } from './extraParameters';
+import { CloudXNativeAssetType } from './types/NativeAd';
+import type { CloudXNativeAdMetadata, CloudXNativeAdViewHandle, CloudXNativeAdViewProps } from './types/NativeAd';
+import type { CloudXAdDisplayFailedInfo, CloudXAdInfo, CloudXAdLoadFailedInfo } from './types/AdInfo';
+import type { CloudXErrorCode } from './CloudXErrorCode';
+import { CloudXNativeAdViewContext, CloudXNativeAdViewProvider } from './CloudXNativeAdViewProvider';
+import { useCloudXSdkInitializationGate } from './useCloudXSdkInitialization';
+
+type NativeViewRef = React.ElementRef<typeof NativeCloudXNativeAdView>;
+
+const parseAdValues = (json?: string | null): Record<string, string> => {
+    if (!json) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+        return {};
+    }
+};
+
+const parseNativeAdMetadata = (json?: string | null): CloudXNativeAdMetadata | null => {
+    if (!json) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === 'object' ? (parsed as CloudXNativeAdMetadata) : null;
+    } catch {
+        return null;
+    }
+};
+
+const toAdInfo = (event: CloudXNativeAdInfoEvent): CloudXAdInfo => {
+    const nativeAd = parseNativeAdMetadata(event.nativeAdJson);
+    return {
+        adUnitId: event.adUnitId,
+        adFormat: event.adFormat,
+        networkName: event.networkName,
+        networkPlacement: event.networkPlacement || null,
+        placement: event.placement || null,
+        creativeId: event.creativeId || null,
+        revenue: event.revenue ?? 0,
+        adValues: parseAdValues(event.adValuesJson),
+        nativeAd,
+    };
+};
+
+const toLoadFailedInfo = (event: CloudXNativeAdLoadFailedEvent): CloudXAdLoadFailedInfo => ({
+    adUnitId: event.adUnitId,
+    code: event.code as CloudXErrorCode,
+    message: event.message || null,
+});
+
+/**
+ * Renders a native ad. Defaults to the SDK's bundled template layouts;
+ * set `renderMode="manual"` to drive layout through the pre-built asset
+ * components (`CloudXTitleView`, `CloudXMediaView`, etc.) instead.
+ *
+ * Manual mode is never inferred from the presence of children — `renderMode`
+ * is always explicit so a publisher's intent is visible at the call site.
+ */
+export const CloudXNativeAdView = forwardRef<CloudXNativeAdViewHandle, CloudXNativeAdViewProps>(
+    function CloudXNativeAdView(props, ref) {
+        const { renderMode = 'template', style, testID, children } = props;
+
+        /*
+         * Gate native ad-view creation on SDK initialization; shared with
+         * CloudXAdViewBase (banner/MREC) via useCloudXSdkInitializationGate.
+         * See that hook for why polling (rather than an init event) is
+         * required.
+         */
+        const isInitialized = useCloudXSdkInitializationGate('CloudXNativeAdView');
+
+        // Dev-only guard: an asset component (CloudXTitleView, etc.) mounted
+        // while renderMode is 'template' silently does nothing on the native
+        // side, which is almost always a publisher forgetting to set
+        // renderMode="manual". Warn once per host instance.
+        const warnedAssetInTemplateMode = useRef(false);
+        const handleAssetRoleRegistered = useCallback(
+            (role: string) => {
+                if (renderMode !== 'template' || warnedAssetInTemplateMode.current) {
+                    return;
+                }
+                warnedAssetInTemplateMode.current = true;
+                console.warn(
+                    `CloudXNativeAdView: <${role}/> is a manual-render asset component, but this ` +
+                        'CloudXNativeAdView has renderMode="template" (the default). Set renderMode="manual" ' +
+                        'to bind asset views, or remove the child to use the bundled template layout.'
+                );
+            },
+            [renderMode]
+        );
+
+        if (!isInitialized) {
+            // Preserve children + view-safe props so a manual layout's asset
+            // views mount and reserve their space before the SDK is ready.
+            // The imperative ref is NOT forwarded here — it stays unset until
+            // the native view mounts, so callers can't dispatch
+            // loadAd/destroyAd at a placeholder.
+            return (
+                <CloudXNativeAdViewProvider onAssetRoleRegistered={handleAssetRoleRegistered}>
+                    <View style={style} testID={testID}>
+                        {children}
+                    </View>
+                </CloudXNativeAdViewProvider>
+            );
+        }
+
+        return (
+            <CloudXNativeAdViewProvider onAssetRoleRegistered={handleAssetRoleRegistered}>
+                <CloudXNativeAdViewImpl {...props} ref={ref} />
+            </CloudXNativeAdViewProvider>
+        );
+    }
+);
+
+export default CloudXNativeAdView;
+
+const CloudXNativeAdViewImpl = forwardRef<CloudXNativeAdViewHandle, CloudXNativeAdViewProps>(
+    function CloudXNativeAdViewImpl(props, ref) {
+        const {
+            adUnitId,
+            placement,
+            customData,
+            template,
+            disableVideoFullScreen,
+            startVideoUnmuted,
+            hideVideoMediaControls,
+            extraParameters,
+            localExtraParameters,
+            renderMode = 'template',
+            onAdLoaded,
+            onAdLoadFailed,
+            onAdDisplayFailed,
+            onAdClicked,
+            onAdExpired,
+            onAdClosed,
+            onAdRevenuePaid,
+            style,
+            testID,
+            children,
+            ...rest
+        } = props;
+
+        const isManual = renderMode === 'manual';
+
+        const {
+            setNativeAd,
+            titleRef,
+            advertiserRef,
+            bodyRef,
+            callToActionRef,
+            iconRef,
+            optionsRef,
+            mediaRef,
+            starRatingRef,
+            mountedAssetRoles,
+        } = useContext(CloudXNativeAdViewContext);
+
+        const nativeRef = useRef<NativeViewRef | null>(null);
+        const pendingMetadata = useRef<CloudXNativeAdMetadata | null>(null);
+        // Cache of the last successfully loaded ad, used to backfill the
+        // CloudXAdInfo fields onAdDisplayFailedEvent doesn't carry (the
+        // native event is a bare {adUnitId, code, message} — a display
+        // failure always follows a prior load of the same ad).
+        const lastAdInfoRef = useRef<CloudXAdInfo | null>(null);
+        const [bindTick, setBindTick] = useState(0);
+
+        const loadAd = useCallback(() => {
+            if (nativeRef.current) {
+                Commands.loadAd(nativeRef.current);
+            }
+        }, []);
+
+        const destroyAd = useCallback(() => {
+            if (nativeRef.current) {
+                Commands.destroyAd(nativeRef.current);
+            }
+            // Clear the shared metadata so asset components stop rendering the
+            // destroyed ad's content and a subsequent load starts clean.
+            pendingMetadata.current = null;
+            lastAdInfoRef.current = null;
+            setNativeAd(null);
+        }, [setNativeAd]);
+
+        /**
+         * Escape hatch for imperative control. The native view auto-loads on
+         * attach and tears down its native ad on unmount; most integrations
+         * never need this ref. Primary lifecycle is still mount/props/unmount.
+         *
+         * `loadAd()` does NOT force a new auction. Both native SDKs re-serve the
+         * ad they already hold while it is neither expired nor destroyed —
+         * including after its impression — so changed targeting is not picked
+         * up. Call `destroyAd()` first to get a genuinely fresh ad.
+         */
+        useImperativeHandle(ref, () => ({ loadAd, destroyAd }), [loadAd, destroyAd]);
+
+        const nativeExtraParameters = useMemo(() => toNativeExtraParameterEntries(extraParameters), [extraParameters]);
+        const nativeLocalExtraParameters = useMemo(
+            () => toNativeExtraParameterEntries(localExtraParameters),
+            [localExtraParameters]
+        );
+
+        const bindAssetView = useCallback((assetRef: React.RefObject<unknown> | undefined, assetName: CloudXNativeAssetType): boolean => {
+            if (!nativeRef.current || !assetRef?.current) return false;
+            const assetTag = findNodeHandle(assetRef.current as React.Component | null);
+            if (assetTag == null) return false;
+            Commands.updateAssetView(nativeRef.current, assetTag, assetName);
+            return true;
+        }, []);
+
+        const handleAdLoaded = useCallback(
+            (event: NativeSyntheticEvent<CloudXNativeAdInfoEvent>) => {
+                const adInfo = toAdInfo(event.nativeEvent);
+                lastAdInfoRef.current = adInfo;
+
+                if (isManual && adInfo.nativeAd) {
+                    pendingMetadata.current = adInfo.nativeAd;
+                    setNativeAd(adInfo.nativeAd);
+                    setBindTick((n) => n + 1);
+                }
+
+                onAdLoaded?.(adInfo);
+            },
+            [isManual, setNativeAd, onAdLoaded]
+        );
+
+        const handleAdLoadFailed = useCallback(
+            (event: NativeSyntheticEvent<CloudXNativeAdLoadFailedEvent>) => {
+                onAdLoadFailed?.(toLoadFailedInfo(event.nativeEvent));
+            },
+            [onAdLoadFailed]
+        );
+
+        const handleAdDisplayFailed = useCallback(
+            (event: NativeSyntheticEvent<CloudXNativeAdLoadFailedEvent>) => {
+                if (!onAdDisplayFailed) return;
+                const { adUnitId: failedAdUnitId, code, message } = event.nativeEvent;
+                // The cached ad info is only a valid description of this
+                // failure if it describes the ad unit that actually failed. A
+                // display failure arriving after a re-target would otherwise
+                // report the previous unit's network, placement and revenue.
+                const cached = lastAdInfoRef.current;
+                const base = cached && cached.adUnitId === failedAdUnitId ? cached : null;
+                const displayFailedInfo: CloudXAdDisplayFailedInfo = {
+                    // The event's own adUnitId is authoritative.
+                    adUnitId: failedAdUnitId || base?.adUnitId || '',
+                    adFormat: base?.adFormat ?? 'NATIVE',
+                    networkName: base?.networkName ?? '',
+                    networkPlacement: base?.networkPlacement ?? null,
+                    placement: base?.placement ?? null,
+                    revenue: base?.revenue ?? 0,
+                    adValues: base?.adValues ?? {},
+                    nativeAd: base?.nativeAd ?? null,
+                    code: code as CloudXErrorCode,
+                    message: message || null,
+                };
+                onAdDisplayFailed(displayFailedInfo);
+            },
+            [onAdDisplayFailed]
+        );
+
+        const handleAdClicked = useCallback(
+            (event: NativeSyntheticEvent<CloudXNativeAdInfoEvent>) => onAdClicked?.(toAdInfo(event.nativeEvent)),
+            [onAdClicked]
+        );
+
+        const handleAdExpired = useCallback(
+            (event: NativeSyntheticEvent<CloudXNativeAdInfoEvent>) => onAdExpired?.(toAdInfo(event.nativeEvent)),
+            [onAdExpired]
+        );
+
+        const handleAdClosed = useCallback(
+            (event: NativeSyntheticEvent<CloudXNativeAdInfoEvent>) => onAdClosed?.(toAdInfo(event.nativeEvent)),
+            [onAdClosed]
+        );
+
+        const handleAdRevenuePaid = useCallback(
+            (event: NativeSyntheticEvent<CloudXNativeAdInfoEvent>) => onAdRevenuePaid?.(toAdInfo(event.nativeEvent)),
+            [onAdRevenuePaid]
+        );
+
+        useEffect(() => {
+            if (!isManual || bindTick === 0) return;
+            const metadata = pendingMetadata.current;
+            if (!metadata) return;
+
+            const iconAvailable = metadata.isIconImageAvailable;
+            const plan: Array<[React.RefObject<unknown> | undefined, CloudXNativeAssetType, boolean]> = [
+                [titleRef, CloudXNativeAssetType.TITLE, Boolean(metadata.title)],
+                [advertiserRef, CloudXNativeAssetType.ADVERTISER, Boolean(metadata.advertiser)],
+                [bodyRef, CloudXNativeAssetType.BODY, Boolean(metadata.body)],
+                [callToActionRef, CloudXNativeAssetType.CALL_TO_ACTION, Boolean(metadata.callToAction)],
+                [iconRef, CloudXNativeAssetType.ICON, iconAvailable],
+                [optionsRef, CloudXNativeAssetType.OPTIONS, metadata.isOptionsViewAvailable],
+                [mediaRef, CloudXNativeAssetType.MEDIA, metadata.isMediaViewAvailable],
+                [starRatingRef, CloudXNativeAssetType.STAR_RATING, metadata.starRating != null && metadata.starRating > 0],
+            ];
+
+            // Asset refs mount asynchronously: components render from context
+            // state that was just set, so on the first frame after onAdLoaded
+            // some refs may still be null. Retry binding across a few frames
+            // and only dispatch renderNativeAd (which registers click +
+            // impression tracking) once every wanted asset is bound — or,
+            // after exhausting retries, render with what did bind and warn.
+            const MAX_BIND_ATTEMPTS = 10;
+            let cancelled = false;
+            // Track every retry timer so unmount can cancel the chain instead
+            // of leaving fire-and-forget timers that dispatch commands at a
+            // recycled or unmounted view tag.
+            const pendingTimers = new Set<ReturnType<typeof setTimeout>>();
+            const scheduleRetry = (fn: () => void): void => {
+                const timer = setTimeout(fn, 16);
+                pendingTimers.add(timer);
+            };
+
+            const attemptBind = (attempt: number, remaining: Set<CloudXNativeAssetType>) => {
+                if (cancelled || pendingMetadata.current == null) return;
+                if (!nativeRef.current) {
+                    if (attempt < MAX_BIND_ATTEMPTS) {
+                        scheduleRetry(() => attemptBind(attempt + 1, remaining));
+                    }
+                    return;
+                }
+
+                for (const [assetRef, assetName, wanted] of plan) {
+                    if (!wanted || !remaining.has(assetName)) continue;
+                    if (bindAssetView(assetRef, assetName)) {
+                        remaining.delete(assetName);
+                    }
+                }
+
+                if (remaining.size > 0 && attempt < MAX_BIND_ATTEMPTS) {
+                    scheduleRetry(() => attemptBind(attempt + 1, remaining));
+                    return;
+                }
+
+                if (remaining.size > 0) {
+                    console.warn(
+                        `CloudXNativeAdView: asset view(s) never mounted for binding: ${[...remaining].join(', ')}. ` +
+                            'Rendering with the bound subset; click/impression tracking may be incomplete.'
+                    );
+                }
+                Commands.renderNativeAd(nativeRef.current);
+            };
+
+            // An asset is only worth waiting for when the ad carries it AND the
+            // publisher mounted its component. Waiting on the ad's asset set
+            // alone made every layout that omits an optional component (an ad
+            // with an advertiser rendered by a layout with no
+            // CloudXAdvertiserView, say) burn all MAX_BIND_ATTEMPTS retries
+            // before dispatching renderNativeAd, delaying impression and click
+            // registration, and warn about it on every such ad.
+            const wanted = new Set(
+                plan
+                    .filter(([, name, w]) => w && mountedAssetRoles.current.has(`CloudX${name}`))
+                    .map(([, name]) => name)
+            );
+            attemptBind(1, wanted);
+
+            return () => {
+                cancelled = true;
+                pendingTimers.forEach((timer) => clearTimeout(timer));
+                pendingTimers.clear();
+            };
+        }, [
+            bindTick,
+            isManual,
+            bindAssetView,
+            titleRef,
+            advertiserRef,
+            bodyRef,
+            callToActionRef,
+            iconRef,
+            optionsRef,
+            mediaRef,
+            starRatingRef,
+            mountedAssetRoles,
+        ]);
+
+        return (
+            <NativeCloudXNativeAdView
+                {...rest}
+                ref={(r) => {
+                    nativeRef.current = r;
+                }}
+                adUnitId={adUnitId}
+                templateName={template}
+                placement={placement ?? null}
+                customData={customData ?? null}
+                disableVideoFullScreen={disableVideoFullScreen}
+                startVideoUnmuted={startVideoUnmuted}
+                hideVideoMediaControls={hideVideoMediaControls}
+                extraParameters={nativeExtraParameters}
+                localExtraParameters={nativeLocalExtraParameters}
+                manualRender={isManual}
+                onAdLoadedEvent={handleAdLoaded}
+                onAdLoadFailedEvent={handleAdLoadFailed}
+                onAdDisplayFailedEvent={handleAdDisplayFailed}
+                onAdClickedEvent={handleAdClicked}
+                onAdExpiredEvent={handleAdExpired}
+                onAdClosedEvent={handleAdClosed}
+                onAdRevenuePaidEvent={handleAdRevenuePaid}
+                style={style}
+                testID={testID}
+            >
+                {children}
+            </NativeCloudXNativeAdView>
+        );
+    }
+);

package/src/CloudXNativeAdViewComponents.tsx

@@ -0,0 +1,203 @@
+/**
+ * Pre-built asset components for the manual-render `<CloudXNativeAdView/>`
+ * flow. Each component reads its content + ref from
+ * @{link CloudXNativeAdViewContext} and renders a minimal RN primitive so the
+ * publisher can style it with `style` / `textStyle` props without reaching
+ * into SDK internals.
+ *
+ * Mount these as descendants of a `<CloudXNativeAdView/>`. A component
+ * mounted outside the provider renders empty rather than throwing, so
+ * publisher layouts can be shown before the first ad loads. Each component
+ * calls `registerAssetRole` on mount so the host view can warn if it is used
+ * while `renderMode` is `'template'` (see CloudXNativeAdViewProvider).
+ */
+
+import * as React from 'react';
+import { useContext, useEffect, useMemo } from 'react';
+import { Image, Platform, StyleSheet, Text, TouchableOpacity, View } from 'react-native';
+import type { ImageProps, TextProps, ViewProps } from 'react-native';
+import { CloudXNativeAdViewContext } from './CloudXNativeAdViewProvider';
+
+// React Native's legacy component types expect `Ref<T>` (T is non-null),
+// while `useRef<T | null>(null)` yields `RefObject<T | null>`. The shapes
+// are compatible at runtime; the cast documents that we are intentionally
+// bridging the two.
+type TextRefLegacy = React.Ref<Text>;
+type ImageRefLegacy = React.Ref<Image>;
+type ViewRefLegacy = React.Ref<View>;
+
+/** Renders the headline. */
+export const CloudXTitleView: React.FC<TextProps> = (props) => {
+    const { titleRef, nativeAd, registerAssetRole } = useContext(CloudXNativeAdViewContext);
+    useEffect(() => registerAssetRole('CloudXTitleView'), [registerAssetRole]);
+    return (
+        <Text {...props} ref={titleRef as TextRefLegacy}>
+            {nativeAd?.title ?? ''}
+        </Text>
+    );
+};
+
+/** Renders the advertiser / sponsor name. */
+export const CloudXAdvertiserView: React.FC<TextProps> = (props) => {
+    const { advertiserRef, nativeAd, registerAssetRole } = useContext(CloudXNativeAdViewContext);
+    useEffect(() => registerAssetRole('CloudXAdvertiserView'), [registerAssetRole]);
+    return (
+        <Text {...props} ref={advertiserRef as TextRefLegacy}>
+            {nativeAd?.advertiser ?? ''}
+        </Text>
+    );
+};
+
+/** Renders the body / description copy. */
+export const CloudXBodyView: React.FC<TextProps> = (props) => {
+    const { bodyRef, nativeAd, registerAssetRole } = useContext(CloudXNativeAdViewContext);
+    useEffect(() => registerAssetRole('CloudXBodyView'), [registerAssetRole]);
+    return (
+        <Text {...props} ref={bodyRef as TextRefLegacy}>
+            {nativeAd?.body ?? ''}
+        </Text>
+    );
+};
+
+/**
+ * Renders the call-to-action label.
+ *
+ * iOS wraps the Text in a TouchableOpacity so publishers get the standard
+ * press-feedback animation; the Text ref is what the native bridge tags,
+ * and UIKit's touch dispatch lets the SDK's gesture recognizer run.
+ *
+ * Android renders a bare Text. RN's gesture responder system treats a
+ * wrapping TouchableOpacity as a touch-capturing ancestor, which blocks
+ * the OnClickListener the 3P SDK installs on the Text when registering
+ * it for click handling. Without the wrapper, the SDK-set listener
+ * receives the tap normally.
+ */
+export const CloudXCallToActionView: React.FC<TextProps> = (props) => {
+    const { callToActionRef, nativeAd, registerAssetRole } = useContext(CloudXNativeAdViewContext);
+    useEffect(() => registerAssetRole('CloudXCallToActionView'), [registerAssetRole]);
+    const label = nativeAd?.callToAction ?? '';
+
+    const content = (
+        <Text {...props} ref={callToActionRef as TextRefLegacy}>
+            {label}
+        </Text>
+    );
+
+    if (Platform.OS === 'android') {
+        return content;
+    }
+
+    return <TouchableOpacity activeOpacity={0.8}>{content}</TouchableOpacity>;
+};
+
+/**
+ * Renders the icon. Prefers the remote URL when available (fast CDN fetch),
+ * falling back to the base64-encoded bytes surfaced by the bridge for
+ * adapters that only ship a pre-loaded drawable.
+ */
+export const CloudXIconView: React.FC<Omit<ImageProps, 'source'>> = (props) => {
+    const { iconRef, nativeAd, registerAssetRole } = useContext(CloudXNativeAdViewContext);
+    useEffect(() => registerAssetRole('CloudXIconView'), [registerAssetRole]);
+
+    const source = useMemo(() => {
+        if (nativeAd?.url) return { uri: nativeAd.url };
+        if (nativeAd?.imageSource) return { uri: `data:image/png;base64,${nativeAd.imageSource}` };
+        return undefined;
+    }, [nativeAd?.url, nativeAd?.imageSource]);
+
+    if (!source) {
+        // Placeholder path: only forward View-safe props. Spreading ImageProps
+        // (resizeMode, fadeDuration, …) onto a <View/> triggers RN warnings.
+        const { style, testID } = props;
+        return <View style={style} testID={testID} ref={iconRef as unknown as ViewRefLegacy} />;
+    }
+    return <Image {...props} ref={iconRef as ImageRefLegacy} source={source} />;
+};
+
+/**
+ * Renders the ad-choices / options container. The adapter's actual options
+ * view is inserted as a native child of this element by the bridge.
+ */
+export const CloudXOptionsView: React.FC<ViewProps> = (props) => {
+    const { optionsRef, registerAssetRole } = useContext(CloudXNativeAdViewContext);
+    useEffect(() => registerAssetRole('CloudXOptionsView'), [registerAssetRole]);
+    // collapsable={false} keeps a real native view alive for the SDK to insert
+    // into. A layout-only style lets the renderer flatten this view away;
+    // findNodeHandle still returns a shadow tag, so binding reports success
+    // while the native lookup finds nothing and the asset is never inserted.
+    return <View {...props} collapsable={false} ref={optionsRef as ViewRefLegacy} />;
+};
+
+/**
+ * Renders the media container. The adapter's media view (static image or
+ * video surface) is inserted as a native child of this element by the
+ * bridge.
+ */
+export const CloudXMediaView: React.FC<ViewProps> = (props) => {
+    const { mediaRef, registerAssetRole } = useContext(CloudXNativeAdViewContext);
+    useEffect(() => registerAssetRole('CloudXMediaView'), [registerAssetRole]);
+    // collapsable={false} keeps a real native view alive for the SDK to insert
+    // into. A layout-only style lets the renderer flatten this view away;
+    // findNodeHandle still returns a shadow tag, so binding reports success
+    // while the native lookup finds nothing and the asset is never inserted.
+    return <View {...props} collapsable={false} ref={mediaRef as ViewRefLegacy} />;
+};
+
+type StarRatingViewProps = ViewProps & {
+    /** Color for filled stars. Defaults to #ffe234. */
+    color?: string;
+    /** Color for empty stars. Defaults to #dedede. */
+    shadowColor?: string;
+    /** Star size in points. Defaults to 10. */
+    size?: number;
+};
+
+/**
+ * Renders the star rating using Unicode glyphs. Partial fractions are
+ * clipped so a 3.5-star rating displays as 3.5 stars.
+ */
+export const CloudXStarRatingView: React.FC<StarRatingViewProps> = ({ color = '#ffe234', shadowColor = '#dedede', size = 10, style }) => {
+    const { nativeAd, starRatingRef, registerAssetRole } = useContext(CloudXNativeAdViewContext);
+    useEffect(() => registerAssetRole('CloudXStarRatingView'), [registerAssetRole]);
+    const maxStars = 5;
+
+    const containerStyle = useMemo(() => StyleSheet.flatten([style, styles.starRatingContainer]), [style]);
+
+    const rating = Math.max(0, Math.min(maxStars, nativeAd?.starRating ?? 0));
+
+    if (!rating) {
+        return <View style={containerStyle} ref={starRatingRef as ViewRefLegacy} />;
+    }
+
+    const stars = Array.from({ length: maxStars }).map((_, index) => {
+        const isFull = rating > index;
+        const width = Math.min(size, Math.max(0, (rating - index) * size));
+        return (
+            <View key={index}>
+                <Text style={{ fontSize: size, color: isFull ? color : shadowColor }}>{String.fromCodePoint(0x2606)}</Text>
+                {isFull && (
+                    <View style={[{ width }, styles.starRatingOverlay]}>
+                        <Text style={{ fontSize: size, color }}>{String.fromCodePoint(0x2605)}</Text>
+                    </View>
+                )}
+            </View>
+        );
+    });
+
+    return (
+        <View style={containerStyle} ref={starRatingRef as ViewRefLegacy}>
+            {stars}
+        </View>
+    );
+};
+
+const styles = StyleSheet.create({
+    starRatingContainer: {
+        flexDirection: 'row',
+        alignItems: 'center',
+    },
+    starRatingOverlay: {
+        overflow: 'hidden',
+        position: 'absolute',
+    },
+});