@chipmobilesdk/rn-ads 0.4.0 → 0.5.1

package/src/core/adOriginatedReturn.ts

@@ -1,134 +1,134 @@
-/**
- * Ad-originated return detection (FR-128).
- *
- * This is the reason app-open belongs in the package rather than in the app.
- * Every other app-open rule — when to show one, how often, on which screens — is
- * policy the app owns. This one is not policy; it is a fact only the package
- * holds. When a user dismisses a full-screen ad, or comes back from a browser an
- * ad opened, the app sees an ordinary return to the foreground and has no way to
- * tell it apart from any other. Showing an app-open ad on that return means
- * showing an ad immediately after an ad, which is both a poor experience and the
- * kind of thing store review notices.
- *
- * The package knows, because it holds the full-screen lock and it sees the click
- * events. So it refuses, with a reason distinct from `busy` and `not_ready` so
- * the app can tell what happened.
- *
- * **Bounded on both sides, deliberately.** Arming has to be tied to something
- * that actually happened, and it has to expire:
- *
- *   - Armed when the provider reports a full-screen ad opened, or on a click —
- *     that second case is a browser the ad opened, which is the only signal the
- *     provider gives for it. Arming is deliberately not tied to the app
- *     reporting that it went to the background; see `noteFullScreenShown`.
- *   - Disarmed without firing if the app was away longer than
- *     `AD_RETURN_MAX_AWAY_MS`. Someone who left, did something else, and came
- *     back an hour later is not returning from an ad, and treating them as if
- *     they were would refuse a legitimate show.
- *   - Refusals last `AD_RETURN_GRACE_MS` after the return, then stop. The window
- *     only needs to cover the moment right after the return, where an app-open
- *     show would otherwise fire. A window that outlived that moment would start
- *     refusing shows that have nothing to do with the ad.
- *
- * Three limits are worth stating plainly, because they are limits rather than
- * defects and the documentation must not imply otherwise:
- *
- *   1. It cannot survive process death. If the OS kills the app while an ad is
- *      on screen, the return is a cold start and nothing links it to the ad.
- *   2. It depends on the app reporting `setAppActive` faithfully — an obligation
- *      0.1.0 already imposes for staleness re-evaluation, not a new one.
- *   3. A browser opened by an ad without a preceding click event is undetectable.
- *
- * Pure state. No listener, no timer — it is driven entirely by transitions the
- * package already observes, which is why `dispose()` has nothing extra to
- * release for it.
- */
-
-import { AD_CLICK_WINDOW_MS, AD_RETURN_GRACE_MS, AD_RETURN_MAX_AWAY_MS } from './timers';
-
-export interface AdOriginatedTracker {
-	/** A full-screen ad is on screen, per the provider's own `opened` callback. */
-	noteFullScreenShown(nowMs: number): void;
-	/** Record an ad click — the only signal that an ad opened a browser. */
-	noteClick(nowMs: number): void;
-	/** The app went to the background. Kept for the click case's timing. */
-	noteBackground(nowMs: number): void;
-	/** The app came back. Decides whether this return was ad-originated. */
-	noteForeground(nowMs: number): void;
-	/** Whether an app-open show should be refused right now. */
-	isRefusing(nowMs: number): boolean;
-	/** Drops all state. For dispose, and for tests asserting a clean slate. */
-	reset(): void;
-}
-
-export function createAdOriginatedTracker(): AdOriginatedTracker {
-	let lastClickAtMs: number | null = null;
-	let armedAtMs: number | null = null;
-	let refusalUntilMs: number | null = null;
-
-	return {
-		/**
-		 * Arming happens here — when the provider says an ad is on screen — and
-		 * deliberately **not** when the app reports going to the background.
-		 *
-		 * That was the first design and it does not survive a real device. React
-		 * Native delivers app-state changes over the bridge, and while the app is
-		 * backgrounded its JS thread is throttled, so the `background` event is
-		 * routinely processed only once the app is already returning. By then the
-		 * ad has been dismissed and the full-screen lock released, so sampling the
-		 * lock at that moment reports "no ad was showing" and the return is let
-		 * through — the exact case FR-128 exists to catch. Arming on a fact the
-		 * provider reports, rather than on the timeliness of an event, removes the
-		 * race entirely.
-		 */
-		noteFullScreenShown(nowMs) {
-			armedAtMs = nowMs;
-		},
-
-		noteClick(nowMs) {
-			lastClickAtMs = nowMs;
-			// A click is itself grounds to arm: the ad may be opening a browser,
-			// and if it is, no `opened` callback will follow.
-			armedAtMs = nowMs;
-		},
-
-		noteBackground(nowMs) {
-			// Only meaningful for the browser case, and only as a refinement: a
-			// background that closely follows a click is that browser opening.
-			if (lastClickAtMs !== null && nowMs - lastClickAtMs <= AD_CLICK_WINDOW_MS) {
-				armedAtMs = nowMs;
-			}
-		},
-
-		noteForeground(nowMs) {
-			if (armedAtMs === null) {
-				return;
-			}
-			const away = nowMs - armedAtMs;
-			armedAtMs = null;
-			lastClickAtMs = null;
-			if (away > AD_RETURN_MAX_AWAY_MS) {
-				// Too long to still be attributable to the ad. Not a refusal.
-				return;
-			}
-			refusalUntilMs = nowMs + AD_RETURN_GRACE_MS;
-		},
-
-		isRefusing(nowMs) {
-			if (refusalUntilMs === null) {
-				return false;
-			}
-			if (nowMs >= refusalUntilMs) {
-				refusalUntilMs = null;
-				return false;
-			}
-			return true;
-		},
-
-		reset() {
-			lastClickAtMs = null;
-			armedAtMs = null;
-			refusalUntilMs = null;
-		},
-	};
-}
+/**
+ * Ad-originated return detection (FR-128).
+ *
+ * This is the reason app-open belongs in the package rather than in the app.
+ * Every other app-open rule — when to show one, how often, on which screens — is
+ * policy the app owns. This one is not policy; it is a fact only the package
+ * holds. When a user dismisses a full-screen ad, or comes back from a browser an
+ * ad opened, the app sees an ordinary return to the foreground and has no way to
+ * tell it apart from any other. Showing an app-open ad on that return means
+ * showing an ad immediately after an ad, which is both a poor experience and the
+ * kind of thing store review notices.
+ *
+ * The package knows, because it holds the full-screen lock and it sees the click
+ * events. So it refuses, with a reason distinct from `busy` and `not_ready` so
+ * the app can tell what happened.
+ *
+ * **Bounded on both sides, deliberately.** Arming has to be tied to something
+ * that actually happened, and it has to expire:
+ *
+ *   - Armed when the provider reports a full-screen ad opened, or on a click —
+ *     that second case is a browser the ad opened, which is the only signal the
+ *     provider gives for it. Arming is deliberately not tied to the app
+ *     reporting that it went to the background; see `noteFullScreenShown`.
+ *   - Disarmed without firing if the app was away longer than
+ *     `AD_RETURN_MAX_AWAY_MS`. Someone who left, did something else, and came
+ *     back an hour later is not returning from an ad, and treating them as if
+ *     they were would refuse a legitimate show.
+ *   - Refusals last `AD_RETURN_GRACE_MS` after the return, then stop. The window
+ *     only needs to cover the moment right after the return, where an app-open
+ *     show would otherwise fire. A window that outlived that moment would start
+ *     refusing shows that have nothing to do with the ad.
+ *
+ * Three limits are worth stating plainly, because they are limits rather than
+ * defects and the documentation must not imply otherwise:
+ *
+ *   1. It cannot survive process death. If the OS kills the app while an ad is
+ *      on screen, the return is a cold start and nothing links it to the ad.
+ *   2. It depends on the app reporting `setAppActive` faithfully — an obligation
+ *      0.1.0 already imposes for staleness re-evaluation, not a new one.
+ *   3. A browser opened by an ad without a preceding click event is undetectable.
+ *
+ * Pure state. No listener, no timer — it is driven entirely by transitions the
+ * package already observes, which is why `dispose()` has nothing extra to
+ * release for it.
+ */
+
+import { AD_CLICK_WINDOW_MS, AD_RETURN_GRACE_MS, AD_RETURN_MAX_AWAY_MS } from './timers';
+
+export interface AdOriginatedTracker {
+	/** A full-screen ad is on screen, per the provider's own `opened` callback. */
+	noteFullScreenShown(nowMs: number): void;
+	/** Record an ad click — the only signal that an ad opened a browser. */
+	noteClick(nowMs: number): void;
+	/** The app went to the background. Kept for the click case's timing. */
+	noteBackground(nowMs: number): void;
+	/** The app came back. Decides whether this return was ad-originated. */
+	noteForeground(nowMs: number): void;
+	/** Whether an app-open show should be refused right now. */
+	isRefusing(nowMs: number): boolean;
+	/** Drops all state. For dispose, and for tests asserting a clean slate. */
+	reset(): void;
+}
+
+export function createAdOriginatedTracker(): AdOriginatedTracker {
+	let lastClickAtMs: number | null = null;
+	let armedAtMs: number | null = null;
+	let refusalUntilMs: number | null = null;
+
+	return {
+		/**
+		 * Arming happens here — when the provider says an ad is on screen — and
+		 * deliberately **not** when the app reports going to the background.
+		 *
+		 * That was the first design and it does not survive a real device. React
+		 * Native delivers app-state changes over the bridge, and while the app is
+		 * backgrounded its JS thread is throttled, so the `background` event is
+		 * routinely processed only once the app is already returning. By then the
+		 * ad has been dismissed and the full-screen lock released, so sampling the
+		 * lock at that moment reports "no ad was showing" and the return is let
+		 * through — the exact case FR-128 exists to catch. Arming on a fact the
+		 * provider reports, rather than on the timeliness of an event, removes the
+		 * race entirely.
+		 */
+		noteFullScreenShown(nowMs) {
+			armedAtMs = nowMs;
+		},
+
+		noteClick(nowMs) {
+			lastClickAtMs = nowMs;
+			// A click is itself grounds to arm: the ad may be opening a browser,
+			// and if it is, no `opened` callback will follow.
+			armedAtMs = nowMs;
+		},
+
+		noteBackground(nowMs) {
+			// Only meaningful for the browser case, and only as a refinement: a
+			// background that closely follows a click is that browser opening.
+			if (lastClickAtMs !== null && nowMs - lastClickAtMs <= AD_CLICK_WINDOW_MS) {
+				armedAtMs = nowMs;
+			}
+		},
+
+		noteForeground(nowMs) {
+			if (armedAtMs === null) {
+				return;
+			}
+			const away = nowMs - armedAtMs;
+			armedAtMs = null;
+			lastClickAtMs = null;
+			if (away > AD_RETURN_MAX_AWAY_MS) {
+				// Too long to still be attributable to the ad. Not a refusal.
+				return;
+			}
+			refusalUntilMs = nowMs + AD_RETURN_GRACE_MS;
+		},
+
+		isRefusing(nowMs) {
+			if (refusalUntilMs === null) {
+				return false;
+			}
+			if (nowMs >= refusalUntilMs) {
+				refusalUntilMs = null;
+				return false;
+			}
+			return true;
+		},
+
+		reset() {
+			lastClickAtMs = null;
+			armedAtMs = null;
+			refusalUntilMs = null;
+		},
+	};
+}

package/src/core/adsInstance.ts

@@ -50,7 +50,12 @@ import {
 	placementReducer,
 	type PlacementSnapshot,
 } from './placementMachine';
-import { evaluateGate, requiresReinitialization, toEnginePrivacy } from './privacyGate';
+import {
+	evaluateGate,
+	requiresReinitialization,
+	toEnginePrivacy,
+	toEngineRequest,
+} from './privacyGate';
 import { evaluateGates, type ConsentGateInput, type GateDecision } from './gates';
 import { createRewardedSession, type RewardedSession } from './rewardedSession';
 import { createTimerSet, isStale, type Scheduler } from './timers';
@@ -82,7 +87,13 @@ export type PrivacyUpdateResult =
 	| { readonly status: 'requires_reinitialization' }
 	| { readonly status: 'disabled' }
 	| { readonly status: 'undecided' }
-	| { readonly status: 'unavailable'; readonly reason: UnavailableReason };
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	/**
+	 * The initialization this update triggered failed (added in 0.5.0). Before,
+	 * it was reported as `applied`, so the app never retried and no ad ever
+	 * showed, with nothing to say why.
+	 */
+	| { readonly status: 'failed'; readonly error: AdsError };
 
 export type LoadResult =
 	| { readonly status: 'loaded'; readonly correlationId: string }
@@ -231,7 +242,13 @@ export interface AdsInstance {
 /** What `AdsBanner` needs. Deliberately not documented as consumer API. */
 export interface InstanceInternals {
 	resolveBanner(placementKey: string):
-		| { readonly ok: true; readonly adUnitId: string; readonly correlationId: string }
+		| {
+				readonly ok: true;
+				readonly adUnitId: string;
+				readonly correlationId: string;
+				/** Current at resolution time, so a banner request honors `updatePrivacy`. */
+				readonly personalizedAds: boolean;
+		  }
 		| { readonly ok: false; readonly result: LoadResult };
 	/**
 	 * Takes the throttle slot for a banner cycle (FR-140).
@@ -247,10 +264,7 @@ export interface InstanceInternals {
 	 * Emits nothing and sets no state: it is called during render, so the host
 	 * reports the refusal from its effect instead.
 	 */
-	commitBannerRequest(
-		placementKey: string,
-		correlationId: string,
-	): ThrottledResult | null;
+	commitBannerRequest(placementKey: string, correlationId: string): ThrottledResult | null;
 	/** The configured floor for a placement, so the host can report the cause. */
 	throttleFloorFor(placementKey: string): number;
 	emit(event: AdEvent): void;
@@ -604,6 +618,10 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 	 * guard clause. On refusal it moves the placement to `throttled` and emits,
 	 * which is what makes the refusal observable rather than a silent absence of
 	 * ads — the app would otherwise have no way to tell this from no-fill.
+	 *
+	 * A placement still holding a `ready` ad keeps that state: the refusal is
+	 * about asking again, and overwriting it would strand an ad that was already
+	 * paid for and is still showable.
 	 */
 	function reportThrottled(
 		key: string,
@@ -612,7 +630,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		minRequestIntervalMs: number,
 	): LoadResult {
 		const runtime = placements.get(key);
-		if (runtime) {
+		if (runtime && runtime.snapshot.state !== 'ready') {
 			setPlacement(key, { ...runtime.snapshot, state: 'throttled' });
 		}
 		events.emit({
@@ -701,9 +719,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 
 	/** App-open expires on its own, shorter window (FR-130). */
 	function validityFor(format: AdFormat): number {
-		return format === 'app_open'
-			? resolved.timeouts.appOpenValidity
-			: resolved.timeouts.adValidity;
+		return format === 'app_open' ? resolved.timeouts.appOpenValidity : resolved.timeouts.adValidity;
 	}
 
 	async function doInitialize(privacy: PrivacyOptions): Promise<InitResult> {
@@ -870,7 +886,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			});
 
 			engine
-				.createFullScreen(format, adUnitId)
+				.createFullScreen(format, adUnitId, toEngineRequest(currentPrivacy))
 				.then(handle => {
 					if (disposed || settled) {
 						engine.dispose(handle);
@@ -984,7 +1000,9 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			if (!error || !error.retryable) {
 				return result;
 			}
-			if (!canRetry(policy, runtime.retryAttempts) || !permitsRequests(enablement)) {
+			// The whole gate, not just enablement: a retry is a new provider request
+			// and needs the same permission the first one had (FR-017).
+			if (!canRetry(policy, runtime.retryAttempts) || !currentGate().allowed) {
 				return result;
 			}
 
@@ -1017,7 +1035,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				};
 			});
 
-			if (!waited || disposed || !permitsRequests(enablement)) {
+			if (!waited || disposed || !currentGate().allowed) {
 				return result;
 			}
 
@@ -1163,7 +1181,8 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 
 		async updatePrivacy(privacy) {
 			if (disposed) {
-				return { status: 'disabled' };
+				// The same answer initialize and load give a disposed instance.
+				return { status: 'unavailable', reason: 'provider_missing' };
 			}
 			if (enablement === 'undecided') {
 				return { status: 'undecided' };
@@ -1184,6 +1203,11 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			currentPrivacy = privacy;
 			const gate = evaluateGate(privacy);
 			if (!gate.allowed) {
+				// FR-017, FR-137, FR-153: the same teardown as a consent outcome that
+				// closes the gate. Without it a retry already waiting on its backoff
+				// would still reach the provider after the app withdrew consent.
+				cancelAllRetries();
+				haltPlacements({ status: 'blocked', reason: gate.reason });
 				setInit(initReducer(init, { type: 'BLOCK', reason: gate.reason }));
 				return { status: 'blocked', reason: gate.reason };
 			}
@@ -1193,12 +1217,24 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			if (init.status === 'ready') {
 				return { status: 'applied' };
 			}
+			// Exhaustive on purpose (ADS-04): the old ternary mapped only `ready` and
+			// `blocked`, and every other outcome — `failed` included — fell through to
+			// `applied`. A new InitResult member now fails to compile here.
 			const result = await instance.initialize(privacy);
-			return result.status === 'ready'
-				? { status: 'applied' }
-				: result.status === 'blocked'
-					? { status: 'blocked', reason: result.reason }
-					: { status: 'applied' };
+			switch (result.status) {
+				case 'ready':
+					return { status: 'applied' };
+				case 'blocked':
+				case 'disabled':
+				case 'undecided':
+				case 'unavailable':
+				case 'failed':
+					return result;
+				default: {
+					const unreachable: never = result;
+					return unreachable;
+				}
+			}
 		},
 
 		setEnabled(next) {
@@ -1362,18 +1398,11 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				return runtime.inFlightLoad;
 			}
 
-			// FR-140. Checked after the in-flight join so a caller that merely
-			// arrived twice for one cycle is answered by the join, not charged a
-			// throttle slot — and before the correlation id and `load_started`,
-			// because a refused request is not a cycle and must not look like one
-			// in the event stream.
-			const throttled = checkThrottle(placementKey, definition.format);
-			if (throttled) {
-				return throttled;
-			}
-
 			if (runtime.snapshot.state === 'showing') {
-				return { status: 'failed', error: new AdsError('busy', { operation: 'load', placementKey }) };
+				return {
+					status: 'failed',
+					error: new AdsError('busy', { operation: 'load', placementKey }),
+				};
 			}
 
 			if (!canLoad(runtime.snapshot.state)) {
@@ -1383,6 +1412,17 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				};
 			}
 
+			// FR-140. Checked after the in-flight join so a caller that merely
+			// arrived twice for one cycle is answered by the join, not charged a
+			// throttle slot; after the busy and not-ready guards so a load that was
+			// never going to request anything does not spend one either; and before
+			// the correlation id and `load_started`, because a refused request is
+			// not a cycle and must not look like one in the event stream.
+			const throttled = checkThrottle(placementKey, definition.format);
+			if (throttled) {
+				return throttled;
+			}
+
 			releasePlacementResources(placementKey);
 
 			const correlationId = correlation.next();
@@ -1712,9 +1752,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				}
 				setConsent(next);
 				await reevaluateAfterConsent();
-				return failure
-					? { status: 'failed', error: failure }
-					: { status: 'shown', consent: next };
+				return failure ? { status: 'failed', error: failure } : { status: 'shown', consent: next };
 			},
 
 			getState() {
@@ -1800,14 +1838,14 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 					ok: true,
 					adUnitId: resolved.catalog.byKey.get(placementKey)!,
 					correlationId: correlation.next(),
+					personalizedAds: toEngineRequest(currentPrivacy).personalizedAds,
 				};
 			},
 			commitBannerRequest(placementKey, correlationId) {
 				if (!resolved.placements.has(placementKey)) {
 					return null;
 				}
-				const minRequestIntervalMs =
-					resolved.minRequestIntervalByKey.get(placementKey) ?? 0;
+				const minRequestIntervalMs = resolved.minRequestIntervalByKey.get(placementKey) ?? 0;
 				const decision = requestThrottle.tryAcquire(
 					placementKey,
 					minRequestIntervalMs,
@@ -1883,7 +1921,8 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 function createDefaultEngine(): AdsEngine {
 	// Deferred require keeps the provider off the import graph of every module
 	// that merely mentions `createAds`.
-	const { createAdMobEngine } = require('../engine/admobEngine') as typeof import('../engine/admobEngine');
+	const { createAdMobEngine } =
+		require('../engine/admobEngine') as typeof import('../engine/admobEngine');
 	return createAdMobEngine();
 }