@chipmobilesdk/rn-ads 0.4.0 → 0.5.0

package/src/react/AdsBanner.tsx

@@ -1,337 +1,340 @@
-/**
- * Adaptive banner host (FR-038 – FR-042).
- *
- * The app puts this where it wants a banner. The component never inserts itself
- * into the tree, never overlays app content, and ships no placeholder — the
- * surrounding layout, and any loading or fallback presentation, belong to the
- * app and its theme (FR-040, UX-001).
- *
- * When ads are disabled or unavailable it renders `null` rather than a
- * zero-height view. That is not a micro-optimization: a rendered empty view
- * still sits in the accessibility tree and can take screen-reader focus ahead of
- * real content. `null` leaves the tree entirely (UX-003).
- *
- * The provider owns the banner's whole lifecycle through its own component, so
- * this adapts those callbacks into the normalized event model instead of routing
- * a banner through the load/show handle model, which does not fit it.
- */
-
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { View, type LayoutChangeEvent, type ViewStyle } from 'react-native';
-
-import type { PlacementState } from '../config/types';
-import { AdsError, normalizeProviderError } from '../diagnostics/errors';
-import { useAds } from './AdsProvider';
-import type { ThrottledResult } from '../core/adsInstance';
-import { useAdsStatus } from './hooks';
-
-export interface AdsBannerProps {
-	readonly placementKey: string;
-	/** Called on every state change so the app can hold or reclaim the space. */
-	readonly onStateChange?: (state: PlacementState) => void;
-	/** Applied to the container only. Never to ad content, which is not ours. */
-	readonly style?: ViewStyle;
-}
-
-interface ProviderBannerModule {
-	BannerAd: React.ComponentType<Record<string, unknown>>;
-	BannerAdSize: Record<string, string>;
-}
-
-function loadBannerModule(): ProviderBannerModule | null {
-	try {
-		return require('react-native-google-mobile-ads') as ProviderBannerModule;
-	} catch {
-		return null;
-	}
-}
-
-export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps) {
-	const ads = useAds();
-	// The reported state lives in a ref rather than in component state: the host
-	// itself renders the same tree for every state, so storing it would only
-	// force re-renders the PERF-002 budget does not need to spend. The instance
-	// holds the authoritative value; `onStateChange` tells the app.
-	const stateRef = useRef<PlacementState>('idle');
-	const [containerWidth, setContainerWidth] = useState(0);
-	// A new cycle id remounts the provider component, which is how a width change
-	// produces a genuinely re-adapted banner rather than a stretched old one.
-	const [cycle, setCycle] = useState(0);
-	const correlationRef = useRef<string | null>(null);
-	const startedAtRef = useRef(0);
-	// Whether this mount has already taken a throttle slot, and the refusal if it
-	// was refused. Resets with the mount, which is exactly the granularity FR-140
-	// needs.
-	const throttleRef = useRef<{
-		decided: boolean;
-		refusal: ThrottledResult | null;
-	}>({ decided: false, refusal: null });
-
-	const provider = useMemo(loadBannerModule, []);
-	// Initialization is asynchronous and a banner is almost always mounted before
-	// it finishes. Without this the resolution below would be computed once, while
-	// the instance was still `not_started`, be refused, and never be retried — the
-	// banner would sit at `unavailable` forever on a perfectly healthy app.
-	const status = useAdsStatus();
-
-	// Keyed on `cycle` so a genuine width change mints a fresh correlation id and
-	// starts a new, separately traceable load (FR-038, FR-052), and on `status` so
-	// the banner recovers the moment the instance becomes able to request.
-	const resolved = useMemo(
-		() =>
-			ads && status === 'ready'
-				? { cycle, value: ads.internals.resolveBanner(placementKey) }
-				: null,
-		[ads, placementKey, cycle, status],
-	);
-	const resolution = resolved?.value ?? null;
-
-	const move = useCallback(
-		(next: PlacementState) => {
-			if (stateRef.current === next) {
-				return;
-			}
-			stateRef.current = next;
-			ads?.internals.setPlacementState(placementKey, next);
-			onStateChange?.(next);
-		},
-		[ads, onStateChange, placementKey],
-	);
-
-	// FR-140. Decided **during render**, not in the effect below, because the
-	// provider component requests an ad as part of this very render — an effect
-	// would refuse a request that had already gone out.
-	//
-	// Charged once per mount, guarded by the ref. That granularity is the whole
-	// distinction the throttle turns on: a fresh mount is the navigation burst it
-	// exists to stop (swiping between days, switching tabs, a row scrolling in and
-	// out), while a later cycle in the *same* mount is a width re-adaptation —
-	// rotation — which must not be refused or a rotated screen loses its banner
-	// for up to a minute.
-	if (ads && resolution?.ok && containerWidth > 0 && !throttleRef.current.decided) {
-		throttleRef.current = {
-			decided: true,
-			refusal: ads.internals.commitBannerRequest(placementKey, resolution.correlationId),
-		};
-	}
-	const throttleRefusal = throttleRef.current.refusal;
-
-	const usable = Boolean(
-		ads && provider && resolution?.ok && containerWidth > 0 && !throttleRefusal,
-	);
-
-	useEffect(() => {
-		if (!ads || !provider) {
-			move('unavailable');
-			return;
-		}
-		// `not_started` and `initializing` are transient: the app is still on its
-		// way and the banner will resolve shortly, so report `idle` rather than
-		// `unavailable` and let the app keep its layout decision open. Every other
-		// non-ready status — disabled, blocked, failed, unsupported — means there
-		// will be no ad, and the app should reclaim the space (FR-039, FR-042).
-		//
-		// `undecided` is the exception added in 0.2.0, and it is the entire reason
-		// the third state exists. It is reported as itself rather than folded into
-		// either neighbour: `idle` would say "an ad is coming", which is not known
-		// yet, and `unavailable` would say "there will be none", which is also not
-		// known. Only by reporting it honestly can the app decide whether to hold
-		// the space — the choice that keeps a paying user from watching an ad
-		// flash in and out (FR-116).
-		if (status !== 'ready') {
-			move(
-				status === 'undecided'
-					? 'undecided'
-					: status === 'not_started' || status === 'initializing'
-						? 'idle'
-						: 'unavailable',
-			);
-			return;
-		}
-		if (!resolution?.ok) {
-			move('unavailable');
-			return;
-		}
-		if (containerWidth <= 0) {
-			// FR-039: a zero-width container is reported rather than turned into a
-			// request for an ad at a nonsensical size.
-			move('idle');
-			return;
-		}
-		// The slot was taken during render; here is where the refusal becomes
-		// observable. Reported as `throttled` rather than folded into
-		// `unavailable`: that would say "there will be no ad here", when in fact
-		// this placement asked too recently and will work again shortly. Most apps
-		// collapse the space for both, but only one is worth investigating.
-		if (throttleRefusal) {
-			move('throttled');
-			ads.internals.emit({
-				type: 'request_throttled',
-				timestamp: Date.now(),
-				placementKey,
-				format: 'banner',
-				retryAfterMs: throttleRefusal.retryAfterMs,
-				minRequestIntervalMs: ads.internals.throttleFloorFor(placementKey),
-			});
-			return;
-		}
-		correlationRef.current = resolution.correlationId;
-		startedAtRef.current = Date.now();
-		move('loading');
-		ads.internals.emit({
-			type: 'load_started',
-			timestamp: Date.now(),
-			placementKey,
-			format: 'banner',
-			correlationId: resolution.correlationId,
-		});
-		// Deliberately keyed on `cycle`, not on every render: FR-041 forbids a
-		// re-render from producing a second uncontrolled request.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ads, provider, status, resolution, containerWidth, cycle]);
-
-	const onLayout = useCallback(
-		(event: LayoutChangeEvent) => {
-			const width = Math.round(event.nativeEvent.layout.width);
-			setContainerWidth(previous => {
-				if (previous === width) {
-					return previous;
-				}
-				// FR-038: a genuine width or orientation change re-adapts. The
-				// rounding above stops sub-pixel layout jitter from doing so.
-				if (previous > 0 && width > 0) {
-					setCycle(value => value + 1);
-				}
-				return width;
-			});
-		},
-		[],
-	);
-
-	const emit = useCallback(
-		(event: Parameters<NonNullable<typeof ads>['internals']['emit']>[0]) => {
-			ads?.internals.emit(event);
-		},
-		[ads],
-	);
-
-	const handleLoaded = useCallback(() => {
-		move('ready');
-		emit({
-			type: 'loaded',
-			timestamp: Date.now(),
-			placementKey,
-			format: 'banner',
-			correlationId: correlationRef.current ?? undefined,
-			durationMs: Date.now() - startedAtRef.current,
-		});
-	}, [emit, move, placementKey]);
-
-	const handleFailed = useCallback(
-		(error: unknown) => {
-			const normalized = normalizeProviderError(error, {
-				operation: 'load',
-				placementKey,
-				format: 'banner',
-			});
-			move('failed');
-			emit({
-				type: 'load_failed',
-				timestamp: Date.now(),
-				placementKey,
-				format: 'banner',
-				correlationId: correlationRef.current ?? undefined,
-				error: normalized,
-			});
-		},
-		[emit, move, placementKey],
-	);
-
-	const handleImpression = useCallback(() => {
-		emit({
-			type: 'impression',
-			timestamp: Date.now(),
-			placementKey,
-			format: 'banner',
-			correlationId: correlationRef.current ?? undefined,
-			// A real provider impression, unlike the derived one full-screen
-			// formats get. The distinction is load-bearing for revenue
-			// reconciliation, so it is recorded rather than flattened (R5).
-			source: 'provider',
-		});
-	}, [emit, placementKey]);
-
-	const handleClicked = useCallback(() => {
-		emit({
-			type: 'click',
-			timestamp: Date.now(),
-			placementKey,
-			format: 'banner',
-			correlationId: correlationRef.current ?? undefined,
-		});
-	}, [emit, placementKey]);
-
-	// FR-041: nothing survives unmount. No retained native view, no dangling
-	// correlation, no state written into a disposed instance.
-	useEffect(() => {
-		return () => {
-			correlationRef.current = null;
-		};
-	}, []);
-
-	if (!ads || !provider) {
-		// FR-042, UX-003 — out of the tree entirely, blocking no touch.
-		return null;
-	}
-
-	// A terminal non-ready status means there will be no ad at all, so leave the
-	// tree rather than render an empty host. `not_started` and `initializing` are
-	// excluded on purpose: the host must stay mounted through them, because it is
-	// what measures the container and starts the load once the instance is ready.
-	//
-	// `undecided` is excluded for the same reason: the app may still resolve it to
-	// enabled, and a host that unmounted would have to re-measure the container
-	// from scratch when it did. It renders no ad meanwhile — it renders the same
-	// empty measuring host it renders while initializing — and it reports
-	// `undecided` so the app can size the space it decided to keep.
-	if (status === 'disabled' || status === 'unavailable' || status === 'failed') {
-		return null;
-	}
-
-	if (resolution && !resolution.ok) {
-		const refusal = resolution.result;
-		// `undecided` deliberately absent: unlike `disabled`, it is not a settled
-		// no, so the host stays mounted (FR-116).
-		if (refusal.status === 'disabled' || refusal.status === 'unavailable') {
-			return null;
-		}
-	}
-
-	const { BannerAd, BannerAdSize } = provider;
-	const adUnitId = resolution?.ok ? resolution.adUnitId : null;
-
-	return (
-		<View style={style} onLayout={onLayout} testID={`ads-banner-${placementKey}`}>
-			{usable && adUnitId ? (
-				<BannerAd
-					key={`${placementKey}-${cycle}`}
-					unitId={adUnitId}
-					size={BannerAdSize.ANCHORED_ADAPTIVE_BANNER}
-					onAdLoaded={handleLoaded}
-					onAdFailedToLoad={handleFailed}
-					onAdImpression={handleImpression}
-					onAdClicked={handleClicked}
-				/>
-			) : null}
-		</View>
-	);
-}
-
-/** Exposed for tests that assert the failure taxonomy without a renderer. */
-export function bannerUnavailableError(placementKey: string): AdsError {
-	return new AdsError('unsupported_platform', {
-		operation: 'load',
-		placementKey,
-		format: 'banner',
-	});
-}
+/**
+ * Adaptive banner host (FR-038 – FR-042).
+ *
+ * The app puts this where it wants a banner. The component never inserts itself
+ * into the tree, never overlays app content, and ships no placeholder — the
+ * surrounding layout, and any loading or fallback presentation, belong to the
+ * app and its theme (FR-040, UX-001).
+ *
+ * When ads are disabled or unavailable it renders `null` rather than a
+ * zero-height view. That is not a micro-optimization: a rendered empty view
+ * still sits in the accessibility tree and can take screen-reader focus ahead of
+ * real content. `null` leaves the tree entirely (UX-003).
+ *
+ * The provider owns the banner's whole lifecycle through its own component, so
+ * this adapts those callbacks into the normalized event model instead of routing
+ * a banner through the load/show handle model, which does not fit it.
+ */
+
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { View, type LayoutChangeEvent, type ViewStyle } from 'react-native';
+
+import type { PlacementState } from '../config/types';
+import { AdsError, normalizeProviderError } from '../diagnostics/errors';
+import { useAds } from './AdsProvider';
+import type { ThrottledResult } from '../core/adsInstance';
+import { useAdsStatus } from './hooks';
+
+export interface AdsBannerProps {
+	readonly placementKey: string;
+	/** Called on every state change so the app can hold or reclaim the space. */
+	readonly onStateChange?: (state: PlacementState) => void;
+	/** Applied to the container only. Never to ad content, which is not ours. */
+	readonly style?: ViewStyle;
+}
+
+interface ProviderBannerModule {
+	BannerAd: React.ComponentType<Record<string, unknown>>;
+	BannerAdSize: Record<string, string>;
+}
+
+function loadBannerModule(): ProviderBannerModule | null {
+	try {
+		return require('react-native-google-mobile-ads') as ProviderBannerModule;
+	} catch {
+		return null;
+	}
+}
+
+export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps) {
+	const ads = useAds();
+	// The reported state lives in a ref rather than in component state: the host
+	// itself renders the same tree for every state, so storing it would only
+	// force re-renders the PERF-002 budget does not need to spend. The instance
+	// holds the authoritative value; `onStateChange` tells the app.
+	const stateRef = useRef<PlacementState>('idle');
+	const [containerWidth, setContainerWidth] = useState(0);
+	// A new cycle id remounts the provider component, which is how a width change
+	// produces a genuinely re-adapted banner rather than a stretched old one.
+	const [cycle, setCycle] = useState(0);
+	const correlationRef = useRef<string | null>(null);
+	const startedAtRef = useRef(0);
+	// Whether this mount has already taken a throttle slot, and the refusal if it
+	// was refused. Resets with the mount, which is exactly the granularity FR-140
+	// needs.
+	const throttleRef = useRef<{
+		decided: boolean;
+		refusal: ThrottledResult | null;
+	}>({ decided: false, refusal: null });
+
+	const provider = useMemo(loadBannerModule, []);
+	// Initialization is asynchronous and a banner is almost always mounted before
+	// it finishes. Without this the resolution below would be computed once, while
+	// the instance was still `not_started`, be refused, and never be retried — the
+	// banner would sit at `unavailable` forever on a perfectly healthy app.
+	const status = useAdsStatus();
+
+	// Keyed on `cycle` so a genuine width change mints a fresh correlation id and
+	// starts a new, separately traceable load (FR-038, FR-052), and on `status` so
+	// the banner recovers the moment the instance becomes able to request.
+	const resolved = useMemo(
+		() =>
+			ads && status === 'ready'
+				? { cycle, value: ads.internals.resolveBanner(placementKey) }
+				: null,
+		[ads, placementKey, cycle, status],
+	);
+	const resolution = resolved?.value ?? null;
+
+	const move = useCallback(
+		(next: PlacementState) => {
+			if (stateRef.current === next) {
+				return;
+			}
+			stateRef.current = next;
+			ads?.internals.setPlacementState(placementKey, next);
+			onStateChange?.(next);
+		},
+		[ads, onStateChange, placementKey],
+	);
+
+	// FR-140. Decided **during render**, not in the effect below, because the
+	// provider component requests an ad as part of this very render — an effect
+	// would refuse a request that had already gone out.
+	//
+	// Charged once per mount, guarded by the ref. That granularity is the whole
+	// distinction the throttle turns on: a fresh mount is the navigation burst it
+	// exists to stop (swiping between days, switching tabs, a row scrolling in and
+	// out), while a later cycle in the *same* mount is a width re-adaptation —
+	// rotation — which must not be refused or a rotated screen loses its banner
+	// for up to a minute.
+	if (ads && resolution?.ok && containerWidth > 0 && !throttleRef.current.decided) {
+		throttleRef.current = {
+			decided: true,
+			refusal: ads.internals.commitBannerRequest(placementKey, resolution.correlationId),
+		};
+	}
+	const throttleRefusal = throttleRef.current.refusal;
+
+	const usable = Boolean(
+		ads && provider && resolution?.ok && containerWidth > 0 && !throttleRefusal,
+	);
+
+	useEffect(() => {
+		if (!ads || !provider) {
+			move('unavailable');
+			return;
+		}
+		// `not_started` and `initializing` are transient: the app is still on its
+		// way and the banner will resolve shortly, so report `idle` rather than
+		// `unavailable` and let the app keep its layout decision open. Every other
+		// non-ready status — disabled, blocked, failed, unsupported — means there
+		// will be no ad, and the app should reclaim the space (FR-039, FR-042).
+		//
+		// `undecided` is the exception added in 0.2.0, and it is the entire reason
+		// the third state exists. It is reported as itself rather than folded into
+		// either neighbour: `idle` would say "an ad is coming", which is not known
+		// yet, and `unavailable` would say "there will be none", which is also not
+		// known. Only by reporting it honestly can the app decide whether to hold
+		// the space — the choice that keeps a paying user from watching an ad
+		// flash in and out (FR-116).
+		if (status !== 'ready') {
+			move(
+				status === 'undecided'
+					? 'undecided'
+					: status === 'not_started' || status === 'initializing'
+						? 'idle'
+						: 'unavailable',
+			);
+			return;
+		}
+		if (!resolution?.ok) {
+			move('unavailable');
+			return;
+		}
+		if (containerWidth <= 0) {
+			// FR-039: a zero-width container is reported rather than turned into a
+			// request for an ad at a nonsensical size.
+			move('idle');
+			return;
+		}
+		// The slot was taken during render; here is where the refusal becomes
+		// observable. Reported as `throttled` rather than folded into
+		// `unavailable`: that would say "there will be no ad here", when in fact
+		// this placement asked too recently and will work again shortly. Most apps
+		// collapse the space for both, but only one is worth investigating.
+		if (throttleRefusal) {
+			move('throttled');
+			ads.internals.emit({
+				type: 'request_throttled',
+				timestamp: Date.now(),
+				placementKey,
+				format: 'banner',
+				retryAfterMs: throttleRefusal.retryAfterMs,
+				minRequestIntervalMs: ads.internals.throttleFloorFor(placementKey),
+			});
+			return;
+		}
+		correlationRef.current = resolution.correlationId;
+		startedAtRef.current = Date.now();
+		move('loading');
+		ads.internals.emit({
+			type: 'load_started',
+			timestamp: Date.now(),
+			placementKey,
+			format: 'banner',
+			correlationId: resolution.correlationId,
+		});
+		// Deliberately keyed on `cycle`, not on every render: FR-041 forbids a
+		// re-render from producing a second uncontrolled request.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ads, provider, status, resolution, containerWidth, cycle]);
+
+	const onLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const width = Math.round(event.nativeEvent.layout.width);
+			setContainerWidth(previous => {
+				if (previous === width) {
+					return previous;
+				}
+				// FR-038: a genuine width or orientation change re-adapts. The
+				// rounding above stops sub-pixel layout jitter from doing so.
+				if (previous > 0 && width > 0) {
+					setCycle(value => value + 1);
+				}
+				return width;
+			});
+		},
+		[],
+	);
+
+	const emit = useCallback(
+		(event: Parameters<NonNullable<typeof ads>['internals']['emit']>[0]) => {
+			ads?.internals.emit(event);
+		},
+		[ads],
+	);
+
+	const handleLoaded = useCallback(() => {
+		move('ready');
+		emit({
+			type: 'loaded',
+			timestamp: Date.now(),
+			placementKey,
+			format: 'banner',
+			correlationId: correlationRef.current ?? undefined,
+			durationMs: Date.now() - startedAtRef.current,
+		});
+	}, [emit, move, placementKey]);
+
+	const handleFailed = useCallback(
+		(error: unknown) => {
+			const normalized = normalizeProviderError(error, {
+				operation: 'load',
+				placementKey,
+				format: 'banner',
+			});
+			move('failed');
+			emit({
+				type: 'load_failed',
+				timestamp: Date.now(),
+				placementKey,
+				format: 'banner',
+				correlationId: correlationRef.current ?? undefined,
+				error: normalized,
+			});
+		},
+		[emit, move, placementKey],
+	);
+
+	const handleImpression = useCallback(() => {
+		emit({
+			type: 'impression',
+			timestamp: Date.now(),
+			placementKey,
+			format: 'banner',
+			correlationId: correlationRef.current ?? undefined,
+			// A real provider impression, unlike the derived one full-screen
+			// formats get. The distinction is load-bearing for revenue
+			// reconciliation, so it is recorded rather than flattened (R5).
+			source: 'provider',
+		});
+	}, [emit, placementKey]);
+
+	const handleClicked = useCallback(() => {
+		emit({
+			type: 'click',
+			timestamp: Date.now(),
+			placementKey,
+			format: 'banner',
+			correlationId: correlationRef.current ?? undefined,
+		});
+	}, [emit, placementKey]);
+
+	// FR-041: nothing survives unmount. No retained native view, no dangling
+	// correlation, no state written into a disposed instance.
+	useEffect(() => {
+		return () => {
+			correlationRef.current = null;
+		};
+	}, []);
+
+	if (!ads || !provider) {
+		// FR-042, UX-003 — out of the tree entirely, blocking no touch.
+		return null;
+	}
+
+	// A terminal non-ready status means there will be no ad at all, so leave the
+	// tree rather than render an empty host. `not_started` and `initializing` are
+	// excluded on purpose: the host must stay mounted through them, because it is
+	// what measures the container and starts the load once the instance is ready.
+	//
+	// `undecided` is excluded for the same reason: the app may still resolve it to
+	// enabled, and a host that unmounted would have to re-measure the container
+	// from scratch when it did. It renders no ad meanwhile — it renders the same
+	// empty measuring host it renders while initializing — and it reports
+	// `undecided` so the app can size the space it decided to keep.
+	if (status === 'disabled' || status === 'unavailable' || status === 'failed') {
+		return null;
+	}
+
+	if (resolution && !resolution.ok) {
+		const refusal = resolution.result;
+		// `undecided` deliberately absent: unlike `disabled`, it is not a settled
+		// no, so the host stays mounted (FR-116).
+		if (refusal.status === 'disabled' || refusal.status === 'unavailable') {
+			return null;
+		}
+	}
+
+	const { BannerAd, BannerAdSize } = provider;
+	const adUnitId = resolution?.ok ? resolution.adUnitId : null;
+	// The provider's polarity is the inverse of the consumer-facing option.
+	const requestNonPersonalizedAdsOnly = resolution?.ok ? !resolution.personalizedAds : false;
+
+	return (
+		<View style={style} onLayout={onLayout} testID={`ads-banner-${placementKey}`}>
+			{usable && adUnitId ? (
+				<BannerAd
+					key={`${placementKey}-${cycle}`}
+					unitId={adUnitId}
+					size={BannerAdSize.ANCHORED_ADAPTIVE_BANNER}
+					requestOptions={{ requestNonPersonalizedAdsOnly }}
+					onAdLoaded={handleLoaded}
+					onAdFailedToLoad={handleFailed}
+					onAdImpression={handleImpression}
+					onAdClicked={handleClicked}
+				/>
+			) : null}
+		</View>
+	);
+}
+
+/** Exposed for tests that assert the failure taxonomy without a renderer. */
+export function bannerUnavailableError(placementKey: string): AdsError {
+	return new AdsError('unsupported_platform', {
+		operation: 'load',
+		placementKey,
+		format: 'banner',
+	});
+}