@chipmobilesdk/rn-ads 0.4.0 → 0.5.1

package/src/engine/port.ts

@@ -1,125 +1,144 @@
-/**
- * The internal engine port (NFR-008, FR-006).
- *
- * This interface names no platform and no ad provider. That is what makes an
- * iOS adapter an additive change: it implements this, and nothing in the public
- * contract moves. `core/` talks only to this shape; the AdMob bridge exists
- * behind exactly one implementation of it, in `admobEngine.ts`.
- *
- * Banners are absent on purpose. The provider owns a banner's whole lifecycle
- * through a React component, so `react/AdsBanner` adapts those callbacks
- * directly rather than routing them through a handle model that would have to
- * pretend a banner is a load-then-show resource.
- */
-
-import type { AdContentRating, FullScreenFormat, Reward, Unsubscribe } from '../config/types';
-
-/** Privacy state as the engine needs it — no consumer-facing shape leaks in. */
-export interface EnginePrivacy {
-	readonly childDirected?: boolean;
-	readonly underAgeOfConsent?: boolean;
-	readonly maxAdContentRating?: AdContentRating;
-	readonly personalizedAds?: boolean;
-	readonly testDeviceIds?: readonly string[];
-}
-
-/**
- * Provider callbacks, normalized to the vocabulary the core state machines use.
- * `rewarded` and `dismissed` are separate members because they are separate
- * facts that can arrive in either order (FR-049).
- */
-export type EngineAdEvent =
-	| { readonly type: 'loaded' }
-	| { readonly type: 'failed'; readonly cause: unknown }
-	| { readonly type: 'opened' }
-	| { readonly type: 'clicked' }
-	| { readonly type: 'dismissed' }
-	| { readonly type: 'rewarded'; readonly reward: Reward };
-
-/** An opaque reference to one loaded ad. Never exposed publicly. */
-export interface EngineAdHandle {
-	readonly id: string;
-}
-
-/**
- * Consent status as the engine reports it — the provider's own vocabulary,
- * lowercased, with nothing provider-shaped attached. `core/consentFlow.ts`
- * normalizes this into the public `ConsentState`; keeping the two separate is
- * what lets an iOS adapter map a different mechanism onto the same public shape
- * without either side changing.
- */
-export interface EngineConsentInfo {
-	readonly status: 'unknown' | 'required' | 'not_required' | 'obtained';
-	readonly canRequestAds: boolean;
-	readonly isFormAvailable: boolean;
-	/** Whether the provider requires a "change my choice" entry point (FR-150). */
-	readonly privacyOptions: 'unknown' | 'required' | 'not_required';
-}
-
-export interface EngineConsentOptions {
-	/** Already stripped by config validation when the environment is production. */
-	readonly debugGeography?: 'disabled' | 'eea' | 'not_eea' | 'regulated_us_state' | 'other';
-	readonly underAgeOfConsent?: boolean;
-	readonly testDeviceIds?: readonly string[];
-}
-
-/**
- * The provider's consent platform, behind the same boundary as everything else.
- *
- * It is a separate member of `AdsEngine` rather than more methods on it because
- * it is a genuinely separate native module - the ads SDK and the consent SDK
- * initialize independently and neither requires the other.
- *
- * The package orchestrates; it never renders. `showFormIfRequired` asks the
- * provider to present its own form and reports what came back (FR-103).
- */
-export interface ConsentPort {
-	/** Refreshes consent information, applying any testing options. */
-	requestInfoUpdate(options: EngineConsentOptions): Promise<EngineConsentInfo>;
-	/** Presents the provider's form if one is required; a no-op otherwise. */
-	showFormIfRequired(): Promise<EngineConsentInfo>;
-	/**
-	 * Presents the provider's privacy options form, through which a user changes
-	 * an answer already given (FR-151). Resolves when the form closes, whether or
-	 * not anything changed; rejects if it could not be presented. The caller has
-	 * already checked the requirement, so the adapter does not re-check.
-	 */
-	showPrivacyOptionsForm(): Promise<EngineConsentInfo>;
-	/** Last known information without contacting the network. */
-	getInfo(): Promise<EngineConsentInfo>;
-	/** Clears the stored decision. Inert in production by configuration. */
-	reset(): void;
-}
-
-export interface AdsEngine {
-	/**
-	 * True when this platform has a working adapter. Checked before anything
-	 * else so an unsupported platform never loads the provider at all (FR-025).
-	 */
-	isAvailable(): boolean;
-
-	/**
-	 * Applies privacy configuration and then initializes the provider. The order
-	 * matters: child-directed and under-age flags only take effect if they reach
-	 * the provider before it initializes (FR-017, R9).
-	 *
-	 * The caller guarantees this is invoked at most once per instance; the
-	 * engine does not have to be idempotent itself.
-	 */
-	initialize(privacy: EnginePrivacy): Promise<void>;
-
-	/** Creates and begins loading one full-screen ad. Resolves on request, not on load. */
-	createFullScreen(format: FullScreenFormat, adUnitId: string): Promise<EngineAdHandle>;
-
-	/** Presents a loaded ad. Rejects if the provider refuses to present. */
-	show(handle: EngineAdHandle): Promise<void>;
-
-	/** Provider callbacks for one handle. Returns an unsubscribe (FR-005). */
-	subscribe(handle: EngineAdHandle, listener: (event: EngineAdEvent) => void): Unsubscribe;
-
-	/** Releases the handle's provider resources. Safe to call more than once. */
-	dispose(handle: EngineAdHandle): void;
-
-	/** The provider's consent platform. Only touched if the app opts in (FR-102). */
-	readonly consent: ConsentPort;
-}
+/**
+ * The internal engine port (NFR-008, FR-006).
+ *
+ * This interface names no platform and no ad provider. That is what makes an
+ * iOS adapter an additive change: it implements this, and nothing in the public
+ * contract moves. `core/` talks only to this shape; the AdMob bridge exists
+ * behind exactly one implementation of it, in `admobEngine.ts`.
+ *
+ * Banners are absent on purpose. The provider owns a banner's whole lifecycle
+ * through a React component, so `react/AdsBanner` adapts those callbacks
+ * directly rather than routing them through a handle model that would have to
+ * pretend a banner is a load-then-show resource.
+ */
+
+import type { AdContentRating, FullScreenFormat, Reward, Unsubscribe } from '../config/types';
+
+/** Privacy state as the engine needs it — no consumer-facing shape leaks in. */
+export interface EnginePrivacy {
+	readonly childDirected?: boolean;
+	readonly underAgeOfConsent?: boolean;
+	readonly maxAdContentRating?: AdContentRating;
+	readonly personalizedAds?: boolean;
+	readonly testDeviceIds?: readonly string[];
+}
+
+/**
+ * Privacy that applies to each ad request rather than to initialization.
+ *
+ * `personalizedAds` is here, not only in `EnginePrivacy`, because the provider
+ * reads it per request and `updatePrivacy` may change it without
+ * reinitializing: a request must carry the value current at request time.
+ */
+export interface EngineRequestOptions {
+	readonly personalizedAds: boolean;
+}
+
+/**
+ * Provider callbacks, normalized to the vocabulary the core state machines use.
+ * `rewarded` and `dismissed` are separate members because they are separate
+ * facts that can arrive in either order (FR-049).
+ */
+export type EngineAdEvent =
+	| { readonly type: 'loaded' }
+	| { readonly type: 'failed'; readonly cause: unknown }
+	| { readonly type: 'opened' }
+	| { readonly type: 'clicked' }
+	| { readonly type: 'dismissed' }
+	| { readonly type: 'rewarded'; readonly reward: Reward };
+
+/** An opaque reference to one loaded ad. Never exposed publicly. */
+export interface EngineAdHandle {
+	readonly id: string;
+}
+
+/**
+ * Consent status as the engine reports it — the provider's own vocabulary,
+ * lowercased, with nothing provider-shaped attached. `core/consentFlow.ts`
+ * normalizes this into the public `ConsentState`; keeping the two separate is
+ * what lets an iOS adapter map a different mechanism onto the same public shape
+ * without either side changing.
+ */
+export interface EngineConsentInfo {
+	readonly status: 'unknown' | 'required' | 'not_required' | 'obtained';
+	readonly canRequestAds: boolean;
+	readonly isFormAvailable: boolean;
+	/** Whether the provider requires a "change my choice" entry point (FR-150). */
+	readonly privacyOptions: 'unknown' | 'required' | 'not_required';
+}
+
+export interface EngineConsentOptions {
+	/** Already stripped by config validation when the environment is production. */
+	readonly debugGeography?: 'disabled' | 'eea' | 'not_eea' | 'regulated_us_state' | 'other';
+	readonly underAgeOfConsent?: boolean;
+	readonly testDeviceIds?: readonly string[];
+}
+
+/**
+ * The provider's consent platform, behind the same boundary as everything else.
+ *
+ * It is a separate member of `AdsEngine` rather than more methods on it because
+ * it is a genuinely separate native module - the ads SDK and the consent SDK
+ * initialize independently and neither requires the other.
+ *
+ * The package orchestrates; it never renders. `showFormIfRequired` asks the
+ * provider to present its own form and reports what came back (FR-103).
+ */
+export interface ConsentPort {
+	/** Refreshes consent information, applying any testing options. */
+	requestInfoUpdate(options: EngineConsentOptions): Promise<EngineConsentInfo>;
+	/** Presents the provider's form if one is required; a no-op otherwise. */
+	showFormIfRequired(): Promise<EngineConsentInfo>;
+	/**
+	 * Presents the provider's privacy options form, through which a user changes
+	 * an answer already given (FR-151). Resolves when the form closes, whether or
+	 * not anything changed; rejects if it could not be presented. The caller has
+	 * already checked the requirement, so the adapter does not re-check.
+	 */
+	showPrivacyOptionsForm(): Promise<EngineConsentInfo>;
+	/** Last known information without contacting the network. */
+	getInfo(): Promise<EngineConsentInfo>;
+	/** Clears the stored decision. Inert in production by configuration. */
+	reset(): void;
+}
+
+export interface AdsEngine {
+	/**
+	 * True when this platform has a working adapter. Checked before anything
+	 * else so an unsupported platform never loads the provider at all (FR-025).
+	 */
+	isAvailable(): boolean;
+
+	/**
+	 * Applies privacy configuration and then initializes the provider. The order
+	 * matters: child-directed and under-age flags only take effect if they reach
+	 * the provider before it initializes (FR-017, R9).
+	 *
+	 * The caller guarantees this is invoked at most once per instance; the
+	 * engine does not have to be idempotent itself.
+	 */
+	initialize(privacy: EnginePrivacy): Promise<void>;
+
+	/**
+	 * Creates and begins loading one full-screen ad. Resolves on request, not on
+	 * load. `request` is optional so engines written against 0.4.0 still satisfy
+	 * the port; an engine that ignores it requests personalized ads.
+	 */
+	createFullScreen(
+		format: FullScreenFormat,
+		adUnitId: string,
+		request?: EngineRequestOptions,
+	): Promise<EngineAdHandle>;
+
+	/** Presents a loaded ad. Rejects if the provider refuses to present. */
+	show(handle: EngineAdHandle): Promise<void>;
+
+	/** Provider callbacks for one handle. Returns an unsubscribe (FR-005). */
+	subscribe(handle: EngineAdHandle, listener: (event: EngineAdEvent) => void): Unsubscribe;
+
+	/** Releases the handle's provider resources. Safe to call more than once. */
+	dispose(handle: EngineAdHandle): void;
+
+	/** The provider's consent platform. Only touched if the app opts in (FR-102). */
+	readonly consent: ConsentPort;
+}

package/src/engine/testAdUnits.ts

@@ -1,61 +1,61 @@
-/**
- * Google's official test ad units (FR-013).
- *
- * PRIVATE. Never exported from `src/index.ts`.
- *
- * FR-013 forbids the package from carrying production identifiers, credentials,
- * or host-app rules, and explicitly permits official test identifiers provided
- * they are documented as such — this file is that documentation.
- *
- * They are hard-coded rather than read from configuration on purpose: FR-011's
- * substitution guarantee must hold even when the app's configuration is the
- * thing that is wrong, so it cannot depend on the app supplying anything. They
- * are also not re-exported from the provider bridge's own `TestIds`, because
- * that would put a provider symbol on this package's dependency path for a
- * value that is really just four documented constants (FR-002).
- *
- * Source: Google Mobile Ads "Test ads" documentation, cross-checked against the
- * bridge's `src/TestIds.ts` at version 16.0.3. These identifiers are public,
- * are the same for every publisher, and always fill.
- */
-
-import type { AdFormat } from '../config/types';
-
-/** Android. iOS units are added alongside these when the iOS adapter lands (FR-006). */
-const ANDROID_TEST_AD_UNITS: Readonly<Record<AdFormat, string>> = {
-	// The adaptive-banner unit, not the fixed-size one, because adaptive is the
-	// format this package actually requests (FR-038).
-	banner: 'ca-app-pub-3940256099942544/9214589741',
-	interstitial: 'ca-app-pub-3940256099942544/1033173712',
-	rewarded: 'ca-app-pub-3940256099942544/5224354917',
-	// Added in 0.2.0 alongside the app-open format. Cross-checked against the
-	// bridge's own `TestIds.APP_OPEN` at 16.0.3.
-	app_open: 'ca-app-pub-3940256099942544/9257395921',
-};
-
-export function testAdUnitFor(format: AdFormat): string {
-	return ANDROID_TEST_AD_UNITS[format];
-}
-
-/**
- * Whether an identifier is one of ours.
- *
- * This is the structural test that drives substitution: anything that is not a
- * known official test unit is treated as production-owned. Deliberately not a
- * parse of AdMob's publisher-id format — a rule like that becomes wrong the day
- * Google changes the format, and being wrong here means either sending a
- * production request or blocking a legitimate one.
- */
-export function isOfficialTestAdUnit(adUnitId: string): boolean {
-	for (const value of Object.values(ANDROID_TEST_AD_UNITS)) {
-		if (value === adUnitId) {
-			return true;
-		}
-	}
-	return false;
-}
-
-/** Exposed for the package's own tests and for documentation generation. */
-export function allTestAdUnits(): Readonly<Record<AdFormat, string>> {
-	return ANDROID_TEST_AD_UNITS;
-}
+/**
+ * Google's official test ad units (FR-013).
+ *
+ * PRIVATE. Never exported from `src/index.ts`.
+ *
+ * FR-013 forbids the package from carrying production identifiers, credentials,
+ * or host-app rules, and explicitly permits official test identifiers provided
+ * they are documented as such — this file is that documentation.
+ *
+ * They are hard-coded rather than read from configuration on purpose: FR-011's
+ * substitution guarantee must hold even when the app's configuration is the
+ * thing that is wrong, so it cannot depend on the app supplying anything. They
+ * are also not re-exported from the provider bridge's own `TestIds`, because
+ * that would put a provider symbol on this package's dependency path for a
+ * value that is really just four documented constants (FR-002).
+ *
+ * Source: Google Mobile Ads "Test ads" documentation, cross-checked against the
+ * bridge's `src/TestIds.ts` at version 16.0.3. These identifiers are public,
+ * are the same for every publisher, and always fill.
+ */
+
+import type { AdFormat } from '../config/types';
+
+/** Android. iOS units are added alongside these when the iOS adapter lands (FR-006). */
+const ANDROID_TEST_AD_UNITS: Readonly<Record<AdFormat, string>> = {
+	// The adaptive-banner unit, not the fixed-size one, because adaptive is the
+	// format this package actually requests (FR-038).
+	banner: 'ca-app-pub-3940256099942544/9214589741',
+	interstitial: 'ca-app-pub-3940256099942544/1033173712',
+	rewarded: 'ca-app-pub-3940256099942544/5224354917',
+	// Added in 0.2.0 alongside the app-open format. Cross-checked against the
+	// bridge's own `TestIds.APP_OPEN` at 16.0.3.
+	app_open: 'ca-app-pub-3940256099942544/9257395921',
+};
+
+export function testAdUnitFor(format: AdFormat): string {
+	return ANDROID_TEST_AD_UNITS[format];
+}
+
+/**
+ * Whether an identifier is one of ours.
+ *
+ * This is the structural test that drives substitution: anything that is not a
+ * known official test unit is treated as production-owned. Deliberately not a
+ * parse of AdMob's publisher-id format — a rule like that becomes wrong the day
+ * Google changes the format, and being wrong here means either sending a
+ * production request or blocking a legitimate one.
+ */
+export function isOfficialTestAdUnit(adUnitId: string): boolean {
+	for (const value of Object.values(ANDROID_TEST_AD_UNITS)) {
+		if (value === adUnitId) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/** Exposed for the package's own tests and for documentation generation. */
+export function allTestAdUnits(): Readonly<Record<AdFormat, string>> {
+	return ANDROID_TEST_AD_UNITS;
+}

package/src/react/AdsBanner.tsx

@@ -190,23 +190,20 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 		// 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 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]) => {
@@ -309,6 +306,8 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 
 	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}`}>
@@ -317,6 +316,7 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 					key={`${placementKey}-${cycle}`}
 					unitId={adUnitId}
 					size={BannerAdSize.ANCHORED_ADAPTIVE_BANNER}
+					requestOptions={{ requestNonPersonalizedAdsOnly }}
 					onAdLoaded={handleLoaded}
 					onAdFailedToLoad={handleFailed}
 					onAdImpression={handleImpression}

package/src/react/AdsProvider.tsx

@@ -1,57 +1,57 @@
-/**
- * Instance context (US1).
- *
- * Supplies one `AdsInstance` to the tree so `AdsBanner` and the hooks can reach
- * it without every screen threading it through props.
- *
- * The provider does not create the instance. The app does, and passes it in —
- * because `createAds` throws on a misconfigured catalog (FR-008, FR-012), and a
- * throw during render is a far worse place to discover that than a throw at
- * startup where the app can decide what to do about it.
- */
-
-import React, { createContext, useContext, useEffect, type ReactNode } from 'react';
-import { AppState, type AppStateStatus } from 'react-native';
-
-import type { AdsInstance } from '../core/adsInstance';
-
-const AdsContext = createContext<AdsInstance | null>(null);
-
-export interface AdsProviderProps {
-	readonly instance: AdsInstance;
-	/**
-	 * Whether the provider forwards foreground/background transitions to the
-	 * instance. On by default: FR-034's "never show while inactive" and
-	 * "re-evaluate a stale ad on return" both depend on the instance being told.
-	 * Turn it off only when the app already drives `setAppActive` itself.
-	 */
-	readonly trackAppState?: boolean;
-	readonly children: ReactNode;
-}
-
-export function AdsProvider({ instance, trackAppState = true, children }: AdsProviderProps) {
-	useEffect(() => {
-		if (!trackAppState) {
-			return;
-		}
-		const subscription = AppState.addEventListener('change', (status: AppStateStatus) => {
-			instance.setAppActive(status === 'active');
-		});
-		return () => {
-			subscription.remove();
-		};
-	}, [instance, trackAppState]);
-
-	return <AdsContext.Provider value={instance}>{children}</AdsContext.Provider>;
-}
-
-/**
- * Returns the instance, or null outside a provider.
- *
- * Null rather than a throw on purpose: a screen that renders a banner should
- * degrade to rendering nothing when ads are not wired up, not take the screen
- * down with it (NFR-005).
- */
-export function useAds(): AdsInstance | null {
-	return useContext(AdsContext);
-}
+/**
+ * Instance context (US1).
+ *
+ * Supplies one `AdsInstance` to the tree so `AdsBanner` and the hooks can reach
+ * it without every screen threading it through props.
+ *
+ * The provider does not create the instance. The app does, and passes it in —
+ * because `createAds` throws on a misconfigured catalog (FR-008, FR-012), and a
+ * throw during render is a far worse place to discover that than a throw at
+ * startup where the app can decide what to do about it.
+ */
+
+import React, { createContext, useContext, useEffect, type ReactNode } from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+
+import type { AdsInstance } from '../core/adsInstance';
+
+const AdsContext = createContext<AdsInstance | null>(null);
+
+export interface AdsProviderProps {
+	readonly instance: AdsInstance;
+	/**
+	 * Whether the provider forwards foreground/background transitions to the
+	 * instance. On by default: FR-034's "never show while inactive" and
+	 * "re-evaluate a stale ad on return" both depend on the instance being told.
+	 * Turn it off only when the app already drives `setAppActive` itself.
+	 */
+	readonly trackAppState?: boolean;
+	readonly children: ReactNode;
+}
+
+export function AdsProvider({ instance, trackAppState = true, children }: AdsProviderProps) {
+	useEffect(() => {
+		if (!trackAppState) {
+			return;
+		}
+		const subscription = AppState.addEventListener('change', (status: AppStateStatus) => {
+			instance.setAppActive(status === 'active');
+		});
+		return () => {
+			subscription.remove();
+		};
+	}, [instance, trackAppState]);
+
+	return <AdsContext.Provider value={instance}>{children}</AdsContext.Provider>;
+}
+
+/**
+ * Returns the instance, or null outside a provider.
+ *
+ * Null rather than a throw on purpose: a screen that renders a banner should
+ * degrade to rendering nothing when ads are not wired up, not take the screen
+ * down with it (NFR-005).
+ */
+export function useAds(): AdsInstance | null {
+	return useContext(AdsContext);
+}