@chipmobilesdk/rn-ads 0.6.0 → 0.7.0

package/src/react/AdsBanner.tsx

@@ -16,14 +16,15 @@
  * a banner through the load/show handle model, which does not fit it.
  */
 
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useId, 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 { admobProvider } from '../engine/admobEngine';
+import { normalizeProviderError } from '../diagnostics/errors';
+import type { AdEvent } from '../diagnostics/events';
+import type { EngineFailureKind } from '../engine/port';
 import { useAds } from './AdsProvider';
-import type { ThrottledResult } from '../core/adsInstance';
+import { getInternals, type ThrottledResult } from '../core/adsInstance';
 import { useAdsStatus } from './hooks';
 
 export interface AdsBannerProps {
@@ -34,20 +35,14 @@ export interface AdsBannerProps {
 	readonly style?: ViewStyle;
 }
 
-interface ProviderBannerModule {
-	BannerAd: React.ComponentType<Record<string, unknown>>;
-	BannerAdSize: Record<string, string>;
-}
-
-// The engine's lazy loader, so the bridge is required in one place (ADS-12 still
-// tracks giving the banner its own seam on the engine port).
-function loadBannerModule(): ProviderBannerModule | null {
-	const result = admobProvider.get();
-	return result.ok ? (result.module as unknown as ProviderBannerModule) : null;
-}
-
 export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps) {
 	const ads = useAds();
+	// The instance's banner wiring (ADS-13). An instance the app wrote by hand has
+	// none, and is treated like a missing one.
+	const internals = useMemo(() => (ads ? getInternals(ads) : null), [ads]);
+	// The throttle token for this mount: stable across renders and minted by React
+	// rather than by a counter, so a render that runs twice charges one slot.
+	const mountToken = useId();
 	// 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
@@ -69,23 +64,29 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 		decided: boolean;
 		refusal: ThrottledResult | null;
 	}>({ decided: false, refusal: null });
+	// Which attempt this mount is on. A refused mount asks again once the window
+	// passes (ADS-06), and each attempt needs its own token: the throttle replays
+	// the stored verdict for a token it has seen.
+	const throttleAttemptRef = useRef(0);
 
-	const provider = useMemo(loadBannerModule, []);
+	// The engine's banner component (ADS-12): the host never names the provider.
+	const banner = useMemo(() => internals?.banner() ?? null, [internals]);
 	// 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.
+	// Keyed on `cycle` so a genuine width change 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. Pure: the cycle's correlation id is minted
+	// in the effect that starts it, not here (ADS-20).
 	const resolved = useMemo(
 		() =>
-			ads && status === 'ready'
-				? { cycle, value: ads.internals.resolveBanner(placementKey) }
+			internals && status === 'ready'
+				? { cycle, value: internals.resolveBanner(placementKey) }
 				: null,
-		[ads, placementKey, cycle, status],
+		[internals, placementKey, cycle, status],
 	);
 	const resolution = resolved?.value ?? null;
 
@@ -95,10 +96,10 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 				return;
 			}
 			stateRef.current = next;
-			ads?.internals.setPlacementState(placementKey, next);
+			internals?.setPlacementState(placementKey, next);
 			onStateChange?.(next);
 		},
-		[ads, onStateChange, placementKey],
+		[internals, onStateChange, placementKey],
 	);
 
 	// FR-140. Decided **during render**, not in the effect below, because the
@@ -111,20 +112,23 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 	// 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) {
+	if (internals && resolution?.ok && containerWidth > 0 && !throttleRef.current.decided) {
 		throttleRef.current = {
 			decided: true,
-			refusal: ads.internals.commitBannerRequest(placementKey, resolution.correlationId),
+			refusal: internals.commitBannerRequest(
+				placementKey,
+				`${mountToken}:${throttleAttemptRef.current}`,
+			),
 		};
 	}
 	const throttleRefusal = throttleRef.current.refusal;
 
 	const usable = Boolean(
-		ads && provider && resolution?.ok && containerWidth > 0 && !throttleRefusal,
+		internals && banner && resolution?.ok && containerWidth > 0 && !throttleRefusal,
 	);
 
 	useEffect(() => {
-		if (!ads || !provider) {
+		if (!internals || !banner) {
 			move('unavailable');
 			return;
 		}
@@ -168,31 +172,39 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 		// collapse the space for both, but only one is worth investigating.
 		if (throttleRefusal) {
 			move('throttled');
-			ads.internals.emit({
+			internals.emit({
 				type: 'request_throttled',
-				timestamp: Date.now(),
+				timestamp: internals.now(),
 				placementKey,
 				format: 'banner',
 				retryAfterMs: throttleRefusal.retryAfterMs,
-				minRequestIntervalMs: ads.internals.throttleFloorFor(placementKey),
+				minRequestIntervalMs: internals.throttleFloorFor(placementKey),
+			});
+			// ADS-06: ask again in this same mount once the window has passed. Until
+			// 0.7.0 a refused banner stayed empty until it was remounted, so a banner
+			// pinned to a screen the user returned to within a minute never filled.
+			return internals.schedule(throttleRefusal.retryAfterMs, () => {
+				throttleRef.current = { decided: false, refusal: null };
+				throttleAttemptRef.current += 1;
+				setCycle(value => value + 1);
 			});
-			return;
 		}
-		correlationRef.current = resolution.correlationId;
+		const correlationId = internals.nextCorrelationId();
+		correlationRef.current = correlationId;
 		loadedInCycleRef.current = false;
-		startedAtRef.current = Date.now();
+		startedAtRef.current = internals.now();
 		move('loading');
-		ads.internals.emit({
+		internals.emit({
 			type: 'load_started',
-			timestamp: Date.now(),
+			timestamp: startedAtRef.current,
 			placementKey,
 			format: 'banner',
-			correlationId: resolution.correlationId,
+			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]);
+	}, [internals, banner, status, resolution, containerWidth, cycle]);
 
 	const onLayout = useCallback((event: LayoutChangeEvent) => {
 		const width = Math.round(event.nativeEvent.layout.width);
@@ -210,22 +222,23 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 	}, []);
 
 	const emit = useCallback(
-		(event: Parameters<NonNullable<typeof ads>['internals']['emit']>[0]) => {
-			ads?.internals.emit(event);
+		(event: AdEvent) => {
+			internals?.emit(event);
 		},
-		[ads],
+		[internals],
 	);
+	const clock = useCallback(() => internals?.now() ?? Date.now(), [internals]);
 
 	const handleLoaded = useCallback(() => {
 		// A second load in one correlation is the provider's auto-refresh: a new
 		// ad, so a new cycle. Under the old correlation its `loaded` and
 		// `impression` were deduplicated away and revenue went uncounted (ADS-05).
 		// For a refresh, `durationMs` is the time since the previous load.
-		if (loadedInCycleRef.current && ads) {
-			correlationRef.current = ads.internals.nextCorrelationId();
+		if (loadedInCycleRef.current && internals) {
+			correlationRef.current = internals.nextCorrelationId();
 		}
 		loadedInCycleRef.current = true;
-		const loadedAt = Date.now();
+		const loadedAt = clock();
 		move('ready');
 		emit({
 			type: 'loaded',
@@ -236,32 +249,32 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 			durationMs: loadedAt - startedAtRef.current,
 		});
 		startedAtRef.current = loadedAt;
-	}, [ads, emit, move, placementKey]);
+	}, [internals, clock, emit, move, placementKey]);
 
 	const handleFailed = useCallback(
-		(error: unknown) => {
-			const normalized = normalizeProviderError(error, {
-				operation: 'load',
-				placementKey,
-				format: 'banner',
-			});
+		(error: unknown, kind?: EngineFailureKind) => {
+			const normalized = normalizeProviderError(
+				error,
+				{ operation: 'load', placementKey, format: 'banner' },
+				kind,
+			);
 			move('failed');
 			emit({
 				type: 'load_failed',
-				timestamp: Date.now(),
+				timestamp: clock(),
 				placementKey,
 				format: 'banner',
 				correlationId: correlationRef.current ?? undefined,
 				error: normalized,
 			});
 		},
-		[emit, move, placementKey],
+		[clock, emit, move, placementKey],
 	);
 
 	const handleImpression = useCallback(() => {
 		emit({
 			type: 'impression',
-			timestamp: Date.now(),
+			timestamp: clock(),
 			placementKey,
 			format: 'banner',
 			correlationId: correlationRef.current ?? undefined,
@@ -270,17 +283,17 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 			// reconciliation, so it is recorded rather than flattened (R5).
 			source: 'provider',
 		});
-	}, [emit, placementKey]);
+	}, [clock, emit, placementKey]);
 
 	const handleClicked = useCallback(() => {
 		emit({
 			type: 'click',
-			timestamp: Date.now(),
+			timestamp: clock(),
 			placementKey,
 			format: 'banner',
 			correlationId: correlationRef.current ?? undefined,
 		});
-	}, [emit, placementKey]);
+	}, [clock, emit, placementKey]);
 
 	// FR-041: nothing survives unmount. No retained native view, no dangling
 	// correlation, no state written into a disposed instance.
@@ -290,7 +303,7 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 		};
 	}, []);
 
-	if (!ads || !provider) {
+	if (!internals || !banner) {
 		// FR-042, UX-003 — out of the tree entirely, blocking no touch.
 		return null;
 	}
@@ -318,34 +331,22 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 		}
 	}
 
-	const { BannerAd, BannerAdSize } = provider;
+	const BannerComponent = banner.Component;
 	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
+			{usable && adUnitId && resolution?.ok ? (
+				<BannerComponent
 					key={`${placementKey}-${cycle}`}
-					unitId={adUnitId}
-					size={BannerAdSize.ANCHORED_ADAPTIVE_BANNER}
-					requestOptions={{ requestNonPersonalizedAdsOnly }}
-					onAdLoaded={handleLoaded}
-					onAdFailedToLoad={handleFailed}
-					onAdImpression={handleImpression}
-					onAdClicked={handleClicked}
+					adUnitId={adUnitId}
+					personalizedAds={resolution.personalizedAds}
+					onLoaded={handleLoaded}
+					onFailed={handleFailed}
+					onImpression={handleImpression}
+					onClicked={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',
-	});
-}

package/src/testing/clock.ts

@@ -0,0 +1,75 @@
+/**
+ * A clock the test drives (ADS-11).
+ *
+ * Every bounded wait in this package — retry backoff, the request throttle, a
+ * consent form that never answers — is measured against a clock. Injecting this
+ * one is what lets a suite assert the behaviour at the boundary instead of
+ * sleeping and hoping.
+ */
+import type { Scheduler } from '../core/timers';
+
+/**
+ * A clock a test can move by hand.
+ *
+ * Retry backoff, app-open expiry, the undecided-state warning, and the
+ * ad-originated-return windows are all time-dependent, and all four must be
+ * assertable exactly rather than approximately. Advancing a clock makes "two
+ * retries, 2s then 4s" a precise assertion; sleeping would make it a flaky one.
+ *
+ * Callbacks fire in due order, and a callback scheduled *during* an advance is
+ * honored within the same advance if its deadline has also passed — matching how
+ * real timers behave when work chains.
+ */
+export interface TestClock {
+	now(): number;
+	advance(ms: number): void;
+	readonly scheduler: Scheduler;
+	pending(): number;
+}
+
+export function createTestClock(startMs = 1_000_000): TestClock {
+	let current = startMs;
+	let sequence = 0;
+	const timers = new Map<number, { at: number; callback: () => void }>();
+
+	const scheduler: Scheduler = {
+		setTimeout(callback, ms) {
+			sequence += 1;
+			timers.set(sequence, { at: current + ms, callback });
+			return sequence;
+		},
+		clearTimeout(handle) {
+			timers.delete(handle as number);
+		},
+	};
+
+	return {
+		now: () => current,
+		advance(ms) {
+			const target = current + ms;
+			// Loop rather than iterate once: a fired callback may schedule another
+			// timer that is also due before `target`, which is exactly what a retry
+			// chain does.
+			for (;;) {
+				let nextId: number | null = null;
+				let nextAt = Number.POSITIVE_INFINITY;
+				for (const [id, timer] of timers) {
+					if (timer.at <= target && timer.at < nextAt) {
+						nextAt = timer.at;
+						nextId = id;
+					}
+				}
+				if (nextId === null) {
+					break;
+				}
+				const timer = timers.get(nextId)!;
+				timers.delete(nextId);
+				current = timer.at;
+				timer.callback();
+			}
+			current = target;
+		},
+		scheduler,
+		pending: () => timers.size,
+	};
+}

package/src/testing/index.ts

@@ -16,85 +16,23 @@
  * so test doubles cannot reach a production bundle.
  */
 
-import type { FullScreenFormat, Reward, Unsubscribe } from '../config/types';
-import type { Scheduler } from '../core/timers';
+import type { AdFormat, FullScreenFormat, Reward, Unsubscribe } from '../config/types';
+export { createTestClock, type TestClock } from './clock';
+import { createTestClock, type TestClock } from './clock';
+
+import { testAdUnitFor } from '../engine/testAdUnits';
 import type {
 	AdsEngine,
 	ConsentPort,
 	EngineAdEvent,
 	EngineAdHandle,
+	EngineBannerProps,
 	EngineConsentInfo,
 	EngineConsentOptions,
 	EnginePrivacy,
 	EngineRequestOptions,
 } from '../engine/port';
 
-/**
- * A clock a test can move by hand.
- *
- * Retry backoff, app-open expiry, the undecided-state warning, and the
- * ad-originated-return windows are all time-dependent, and all four must be
- * assertable exactly rather than approximately. Advancing a clock makes "two
- * retries, 2s then 4s" a precise assertion; sleeping would make it a flaky one.
- *
- * Callbacks fire in due order, and a callback scheduled *during* an advance is
- * honored within the same advance if its deadline has also passed — matching how
- * real timers behave when work chains.
- */
-export interface TestClock {
-	now(): number;
-	advance(ms: number): void;
-	readonly scheduler: Scheduler;
-	pending(): number;
-}
-
-export function createTestClock(startMs = 1_000_000): TestClock {
-	let current = startMs;
-	let sequence = 0;
-	const timers = new Map<number, { at: number; callback: () => void }>();
-
-	const scheduler: Scheduler = {
-		setTimeout(callback, ms) {
-			sequence += 1;
-			timers.set(sequence, { at: current + ms, callback });
-			return sequence;
-		},
-		clearTimeout(handle) {
-			timers.delete(handle as number);
-		},
-	};
-
-	return {
-		now: () => current,
-		advance(ms) {
-			const target = current + ms;
-			// Loop rather than iterate once: a fired callback may schedule another
-			// timer that is also due before `target`, which is exactly what a retry
-			// chain does.
-			for (;;) {
-				let nextId: number | null = null;
-				let nextAt = Number.POSITIVE_INFINITY;
-				for (const [id, timer] of timers) {
-					if (timer.at <= target && timer.at < nextAt) {
-						nextAt = timer.at;
-						nextId = id;
-					}
-				}
-				if (nextId === null) {
-					break;
-				}
-				const timer = timers.get(nextId)!;
-				timers.delete(nextId);
-				current = timer.at;
-				timer.callback();
-			}
-			current = target;
-		},
-		scheduler,
-		pending: () => timers.size,
-	};
-}
-
 export type FakeConsentCall =
 	| { readonly kind: 'requestInfoUpdate'; readonly options: EngineConsentOptions }
 	| { readonly kind: 'showFormIfRequired' }
@@ -212,6 +150,11 @@ function nextMicrotask(task: () => void): void {
 	Promise.resolve().then(task);
 }
 
+/** The fake engine's banner component. */
+function FakeBanner(_props: EngineBannerProps): null {
+	return null;
+}
+
 export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEngine {
 	const calls: FakeEngineCall[] = [];
 	const consentCalls: FakeConsentCall[] = [];
@@ -353,6 +296,14 @@ export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEng
 			return options.available !== false;
 		},
 
+		// Renders nothing. A test finds it in the tree by its `adUnitId` prop and
+		// calls `onLoaded`, `onFailed`, `onImpression` or `onClicked` itself, which
+		// is how a banner is driven without mocking a native module (ADS-12).
+		banner: {
+			isAvailable: () => options.available !== false,
+			Component: FakeBanner,
+		},
+
 		async initialize(privacy) {
 			record({ kind: 'initialize', privacy });
 			if (options.failInitialize !== undefined) {
@@ -473,3 +424,13 @@ export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEng
 
 export { adsEngineChecks, runAdsEngineConformance } from './conformance';
 export type { AdsEngineHarness, AdsEngineSubject } from './conformance';
+
+/** Google's official test ad unit for each format, as the package substitutes them (FR-011). */
+export function allTestAdUnits(): Readonly<Record<AdFormat, string>> {
+	return {
+		banner: testAdUnitFor('banner'),
+		interstitial: testAdUnitFor('interstitial'),
+		rewarded: testAdUnitFor('rewarded'),
+		app_open: testAdUnitFor('app_open'),
+	};
+}