@chipmobilesdk/rn-ads 0.3.0 → 0.4.0

package/src/core/adsInstance.ts

@@ -61,7 +61,9 @@ import {
 	buildConsentOptions,
 	INITIAL_CONSENT,
 	needsForm,
+	normalizeConsent,
 	runConsentStep,
+	toConsentError,
 	toGateInput,
 } from './consentFlow';
 
@@ -106,6 +108,12 @@ export interface ThrottledResult {
 	readonly retryAfterMs: number;
 }
 
+/** A gate refusal: what a load gets when it may not ask at all. */
+type LoadRefusal = Extract<
+	LoadResult,
+	{ status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }
+>;
+
 export type ShowResult =
 	| { readonly status: 'shown'; readonly correlationId: string }
 	| { readonly status: 'not_ready' }
@@ -126,6 +134,37 @@ export type ShowResult =
 	| { readonly status: 'timeout' }
 	| { readonly status: 'failed'; readonly error: AdsError };
 
+/**
+ * What `consent.showPrivacyOptionsForm()` reports (FR-151), added in 0.4.0.
+ *
+ * Every refusal is its own member, so an app can tell "there is nothing to
+ * offer here" from "you asked too early" from "it broke" without parsing an
+ * error. None of them throws.
+ */
+export type PrivacyOptionsFormResult =
+	/**
+	 * The provider's form was presented and has closed. `consent` is the state it
+	 * left behind, already applied to the gate. A user who closed the form without
+	 * changing anything lands here too, with the state they already had.
+	 */
+	| { readonly status: 'shown'; readonly consent: ConsentSnapshot }
+	/** The provider does not require privacy options here. Nothing was presented. */
+	| { readonly status: 'not_required' }
+	/**
+	 * The requirement is not known yet: no successful `requestInfoUpdate()` since
+	 * the instance was created or reset, or the last one failed. Nothing was
+	 * presented.
+	 */
+	| { readonly status: 'info_update_required' }
+	/** A consent form is already on screen. Nothing was presented. */
+	| { readonly status: 'busy' }
+	/**
+	 * The form could not be presented or failed while open. The consent state is
+	 * whatever the provider reports it still holds, and never a new grant.
+	 */
+	| { readonly status: 'failed'; readonly error: AdsError }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason };
+
 /**
  * The optional consent capability (FR-101).
  *
@@ -139,6 +178,15 @@ export interface ConsentApi {
 	requestInfoUpdate(): Promise<ConsentSnapshot>;
 	/** Presents the provider's form if one is required. Renders nothing itself. */
 	showFormIfRequired(): Promise<ConsentSnapshot>;
+	/**
+	 * Presents the provider's privacy options form, so a user can change an
+	 * answer already given (FR-151). Added in 0.4.0.
+	 *
+	 * Offer it when `getState().privacyOptionsRequirement` is `required`. Where
+	 * the entry point lives, and what it says, stay the app's. The outcome feeds
+	 * the privacy gate by itself, exactly as `showFormIfRequired` does.
+	 */
+	showPrivacyOptionsForm(): Promise<PrivacyOptionsFormResult>;
 	getState(): ConsentSnapshot;
 	subscribe(listener: (snapshot: ConsentSnapshot) => void): Unsubscribe;
 	/** Clears the stored decision. Inert in production (FR-113). */
@@ -243,6 +291,12 @@ interface PlacementRuntime {
 	handle: EngineAdHandle | null;
 	unsubscribeEngine: Unsubscribe | null;
 	inFlightLoad: Promise<LoadResult> | null;
+	/**
+	 * Settles the in-flight load with a given result. Only a consent withdrawal
+	 * uses it (FR-153): the caller awaiting `load()` is told `blocked` instead of
+	 * waiting on a request that has been abandoned.
+	 */
+	abortLoad: ((result: LoadResult) => void) | null;
 	cancelLoadTimer: Unsubscribe | null;
 	cancelShowTimer: Unsubscribe | null;
 	rewarded: RewardedSession | null;
@@ -296,6 +350,21 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 	let appActive = true;
 	let consent: ConsentSnapshot = INITIAL_CONSENT;
 	let consentStarted = false;
+	/**
+	 * Consent forms currently on screen. A count rather than a flag because
+	 * `showFormIfRequired` has never refused a concurrent call and 0.4.0 does not
+	 * start now; only the privacy options form reads it, to report `busy`.
+	 */
+	let consentFormsOpen = 0;
+	let privacyOptionsFormOpen = false;
+	/**
+	 * Whether the provider has been natively initialized, ever, by this instance.
+	 *
+	 * Tracked apart from the init status because the status can leave `ready` —
+	 * a withdrawn consent moves it to `blocked` — while the native SDK stays
+	 * initialized. Re-granting must resume, not initialize again (FR-022, FR-154).
+	 */
+	let providerInitialized = false;
 	let undecidedWarned = false;
 	let cancelUndecidedTimer: Unsubscribe | null = null;
 	let appliedPrivacy: PrivacyOptions | null = null;
@@ -315,6 +384,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			handle: null,
 			unsubscribeEngine: null,
 			inFlightLoad: null,
+			abortLoad: null,
 			cancelLoadTimer: null,
 			cancelShowTimer: null,
 			rewarded: null,
@@ -594,11 +664,41 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			runtime.handle = null;
 		}
 		runtime.inFlightLoad = null;
+		runtime.abortLoad = null;
 		runtime.rewarded = null;
 		runtime.cancelRetry?.();
 		runtime.cancelRetry = null;
 	}
 
+	/**
+	 * Stops every request a gate that just closed forbids (FR-125, FR-153,
+	 * FR-159) — ads turned off, turned undecided, or consent withdrawn.
+	 *
+	 * In-flight loads are abandoned and their resources released, a loaded ad
+	 * that may no longer be shown is released with them, and an ad already on
+	 * screen is left alone — the provider offers no safe way to close it.
+	 *
+	 * An abandoned load *settles*: its caller gets `refusal`, the same answer a
+	 * load started now would get. Until 0.4.0 disabling released the resources
+	 * but never resolved the caller's promise, so an app awaiting `load()` across
+	 * a purchase of ad removal waited forever — and a handle the provider handed
+	 * back after the disable was adopted and went on loading.
+	 */
+	function haltPlacements(refusal: LoadRefusal): void {
+		for (const [key, runtime] of placements) {
+			if (runtime.snapshot.state === 'showing') {
+				continue;
+			}
+			const abort = runtime.abortLoad;
+			releasePlacementResources(key);
+			dispatchPlacement(key, { type: 'RESET' });
+			if (abort) {
+				emitRefusal('load', refusal, key, resolved.placements.get(key)?.format);
+				abort(refusal);
+			}
+		}
+	}
+
 	/** App-open expires on its own, shorter window (FR-130). */
 	function validityFor(format: AdFormat): number {
 		return format === 'app_open'
@@ -612,6 +712,10 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			// The adapter applies privacy configuration before initializing the
 			// provider; that ordering is the whole reason FR-017 is enforceable.
 			await engine.initialize(enginePrivacy);
+			// Recorded before the status moves, and whether or not it moves: a gate
+			// that closed while this was in flight leaves the status `blocked`, but
+			// the provider is initialized all the same and must not be again.
+			providerInitialized = true;
 			appliedPrivacy = privacy;
 			setInit(initReducer(init, { type: 'SUCCEED' }));
 			warnSubstitutionOnce();
@@ -736,8 +840,14 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				runtime.cancelLoadTimer?.();
 				runtime.cancelLoadTimer = null;
 				runtime.inFlightLoad = null;
+				if (runtime.abortLoad === finish) {
+					runtime.abortLoad = null;
+				}
 				resolve(result);
 			};
+			// `settled` is what makes this safe: a handle the provider hands back
+			// after an abort is disposed by the `.then` below instead of adopted.
+			runtime.abortLoad = finish;
 
 			runtime.cancelLoadTimer = timers.after(resolved.timeouts.load, () => {
 				const error = new AdsError('load_timeout', {
@@ -924,6 +1034,15 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 	 * total native initialization count across a whole consent flow stays at one
 	 * (FR-022, SC-102). When consent closes the gate, requests stop and every
 	 * pending retry is cancelled with them (FR-137).
+	 *
+	 * Since 0.4.0 a closed gate also moves a `ready` instance to `blocked` and
+	 * abandons in-flight loads (FR-153). 0.3.0 left the status at `ready`, which
+	 * was harmless while the only consent outcome that could close the gate ran
+	 * before anything was loaded. The privacy options form changes that: a user
+	 * can withdraw consent with a banner mounted, and a banner host keyed on
+	 * `ready` would otherwise keep requesting. Re-granting resumes through
+	 * `initialize`, which knows the provider is already up and does not touch it
+	 * again (FR-154).
 	 */
 	async function reevaluateAfterConsent(): Promise<void> {
 		if (disposed || !currentPrivacy) {
@@ -932,7 +1051,8 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		const decision = currentGate();
 		if (!decision.allowed) {
 			cancelAllRetries();
-			if (decision.kind === 'blocked' && init.status !== 'ready') {
+			if (decision.kind === 'blocked') {
+				haltPlacements({ status: 'blocked', reason: decision.reason });
 				setInit(initReducer(init, { type: 'BLOCK', reason: decision.reason }));
 			}
 			return;
@@ -943,6 +1063,31 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		await instance.initialize(currentPrivacy);
 	}
 
+	/**
+	 * Answers `initialize` without a native call when the provider is already up
+	 * (FR-022, FR-154), or returns `null` to let a real initialization proceed.
+	 *
+	 * The status leaves `ready` when a gate closes, but nothing is torn down, so
+	 * the gate reopening resumes. Init-time-only flags that changed in the
+	 * meantime fall through to a real initialization: it is the only way they can
+	 * take effect, and it is what 0.3.0 did.
+	 *
+	 * Only reached once the caller has passed the whole gate, consent flow
+	 * included, so an app that re-runs `initialize` on a consent change cannot
+	 * reopen what the user just closed.
+	 */
+	function resumeInitialized(privacy: PrivacyOptions): InitResult | null {
+		if (
+			!providerInitialized ||
+			!canStart(init.status) ||
+			requiresReinitialization(appliedPrivacy, privacy)
+		) {
+			return null;
+		}
+		setInit(initReducer(init, { type: 'RESUME' }));
+		return { status: 'ready' };
+	}
+
 	const instance: AdsInstance = {
 		async initialize(privacy) {
 			if (disposed) {
@@ -976,12 +1121,19 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				return result;
 			}
 
-			const gate = evaluateGate(privacy);
-			if (!gate.allowed) {
-				// FR-017. Nothing provider-facing happens here at all — not a
+			if (!decision.allowed && decision.kind === 'blocked') {
+				// FR-017, FR-158. Nothing provider-facing happens here at all — not a
 				// configuration call, not an initialization. The engine is untouched.
-				setInit(initReducer(init, { type: 'BLOCK', reason: gate.reason }));
-				const result = { status: 'blocked', reason: gate.reason } as const;
+				//
+				// `decision` is the full gate: the app's own input *and*, once the app
+				// has opted into it, the package's consent flow. Until 0.4.0 this
+				// checked the app's input alone, so a user who declined the consent
+				// form still got a natively initialized SDK — `load` refused, but the
+				// provider was up, which is exactly what the provider's own guidance
+				// says not to do before `canRequestAds`. The consent flow opening the
+				// gate later initializes it, through `reevaluateAfterConsent`.
+				setInit(initReducer(init, { type: 'BLOCK', reason: decision.reason }));
+				const result = { status: 'blocked', reason: decision.reason } as const;
 				emitRefusal('initialize', result);
 				return result;
 			}
@@ -990,6 +1142,11 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				return { status: 'ready' };
 			}
 
+			const resumed = resumeInitialized(privacy);
+			if (resumed) {
+				return resumed;
+			}
+
 			// FR-022, SC-005. Racing callers share one operation, so the provider
 			// initializes exactly once however many arrive.
 			if (inFlightInit) {
@@ -1066,13 +1223,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				// screen is left alone — the provider offers no safe way to close
 				// it, and yanking it would be worse than letting it finish.
 				cancelAllRetries();
-				for (const [key, runtime] of placements) {
-					if (runtime.snapshot.state === 'showing') {
-						continue;
-					}
-					releasePlacementResources(key);
-					dispatchPlacement(key, { type: 'RESET' });
-				}
+				haltPlacements(next === 'disabled' ? { status: 'disabled' } : { status: 'undecided' });
 				setInit(initReducer(init, { type: next === 'disabled' ? 'DISABLE' : 'UNDECIDE' }));
 				if (next === 'undecided') {
 					armUndecidedWarning();
@@ -1484,16 +1635,24 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 					return consent;
 				}
 				consentStarted = true;
-				if (!needsForm(consent)) {
+				if (!needsForm(consent) || privacyOptionsFormOpen) {
 					// Nothing to present. Not an error: a region that does not
 					// require consent is the normal case, and showing a form there
 					// is exactly what FR-107 forbids the package from deciding.
+					// Nor is a privacy options form already on screen — one
+					// provider form at a time.
 					return consent;
 				}
-				const next = await runConsentStep(
-					() => engine.consent.showFormIfRequired(),
-					'consent form failed',
-				);
+				consentFormsOpen += 1;
+				let next: ConsentSnapshot;
+				try {
+					next = await runConsentStep(
+						() => engine.consent.showFormIfRequired(),
+						'consent form failed',
+					);
+				} finally {
+					consentFormsOpen -= 1;
+				}
 				if (disposed) {
 					return consent;
 				}
@@ -1502,6 +1661,62 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				return next;
 			},
 
+			async showPrivacyOptionsForm() {
+				// The refusals, most immovable first — the same reading order as
+				// the request gates, so the answer is the most useful one rather
+				// than the first one checked.
+				if (disposed) {
+					return { status: 'unavailable', reason: 'provider_missing' };
+				}
+				if (!engine.isAvailable()) {
+					return { status: 'unavailable', reason: 'unsupported_platform' };
+				}
+				if (privacyOptionsFormOpen || consentFormsOpen > 0) {
+					return { status: 'busy' };
+				}
+				if (consent.privacyOptionsRequirement === 'unknown') {
+					return { status: 'info_update_required' };
+				}
+				if (consent.privacyOptionsRequirement !== 'required') {
+					// The provider's verdict, not a region guess of ours (FR-150).
+					return { status: 'not_required' };
+				}
+
+				privacyOptionsFormOpen = true;
+				let next: ConsentSnapshot;
+				let failure: AdsError | null = null;
+				try {
+					next = normalizeConsent(await engine.consent.showPrivacyOptionsForm());
+				} catch (cause) {
+					failure = toConsentError(cause, 'privacy options form failed');
+					// The form did not complete, so the stored decision is the
+					// provider's to report — ask it rather than assume. Collapsing to
+					// `error` the way a failed first-time form does would revoke a
+					// consent the user never changed: that form runs while the gate is
+					// already closed, this one usually while it is open. If the
+					// provider cannot answer either, the gate closes; a failure is
+					// never consent (FR-106). Nothing is asked of a disposed instance.
+					next = disposed
+						? consent
+						: await runConsentStep(
+								() => engine.consent.getInfo(),
+								'consent information could not be read after the privacy options form failed',
+							);
+				} finally {
+					privacyOptionsFormOpen = false;
+				}
+				// dispose() during the form: the form is the provider's and stays
+				// until the user closes it, but its outcome reaches nobody (FR-157).
+				if (disposed) {
+					return { status: 'unavailable', reason: 'provider_missing' };
+				}
+				setConsent(next);
+				await reevaluateAfterConsent();
+				return failure
+					? { status: 'failed', error: failure }
+					: { status: 'shown', consent: next };
+			},
+
 			getState() {
 				return consent;
 			},
@@ -1638,9 +1853,14 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			disposed = true;
 			cancelAllRetries();
 			disarmUndecidedWarning();
-			for (const key of placements.keys()) {
+			for (const [key, runtime] of placements) {
+				const abort = runtime.abortLoad;
 				releasePlacementResources(key);
-				placements.get(key)?.listeners.clear();
+				runtime.listeners.clear();
+				// Settled rather than left hanging, with the answer a `load` after
+				// dispose gets (FR-159). No refusal event goes with it: nothing is
+				// emitted after dispose (FR-035).
+				abort?.({ status: 'unavailable', reason: 'provider_missing' });
 			}
 			timers.clearAll();
 			requestThrottle.clear();

package/src/core/consentFlow.ts

@@ -34,6 +34,7 @@ export const INITIAL_CONSENT: ConsentSnapshot = {
 	state: 'undetermined',
 	canRequestAds: false,
 	isFormAvailable: false,
+	privacyOptionsRequirement: 'unknown',
 	error: null,
 };
 
@@ -59,6 +60,7 @@ export function normalizeConsent(info: EngineConsentInfo): ConsentSnapshot {
 		state,
 		canRequestAds: info.canRequestAds === true,
 		isFormAvailable: info.isFormAvailable === true,
+		privacyOptionsRequirement: info.privacyOptions,
 		error: null,
 	};
 }
@@ -70,9 +72,19 @@ export function normalizeConsent(info: EngineConsentInfo): ConsentSnapshot {
  * There is no failure mode in which "the flow broke" should mean "go ahead", and
  * making that structural rather than conditional means no future edit can
  * accidentally reintroduce the inference.
+ *
+ * The privacy-options requirement is `unknown` for the same reason: a broken
+ * flow has no provider verdict to forward, and reporting `not_required` would be
+ * the package deciding the user has no right to change their mind (FR-150).
  */
 export function consentFailure(error: AdsError): ConsentSnapshot {
-	return { state: 'error', canRequestAds: false, isFormAvailable: false, error };
+	return {
+		state: 'error',
+		canRequestAds: false,
+		isFormAvailable: false,
+		privacyOptionsRequirement: 'unknown',
+		error,
+	};
 }
 
 export function toConsentError(cause: unknown, message: string): AdsError {
@@ -161,6 +173,7 @@ export function createConsentPortGuard(port: ConsentPort | undefined): ConsentPo
 	return {
 		requestInfoUpdate: unavailable,
 		showFormIfRequired: unavailable,
+		showPrivacyOptionsForm: unavailable,
 		getInfo: unavailable,
 		reset: () => undefined,
 	};

package/src/core/initMachine.ts

@@ -23,6 +23,13 @@ export type InitEvent =
 	| { readonly type: 'UNDECIDE' }
 	| { readonly type: 'ENABLE' }
 	| { readonly type: 'SUCCEED' }
+	/**
+	 * Back to `ready` with no native call, because the provider was initialized
+	 * earlier and nothing has torn it down since (FR-154). The instance decides
+	 * whether that holds; this machine only refuses to resume from a state a
+	 * fresh start could not leave either.
+	 */
+	| { readonly type: 'RESUME' }
 	| { readonly type: 'FAIL'; readonly error: AdsError };
 
 export interface InitSnapshot {
@@ -165,6 +172,12 @@ export function initReducer(state: InitSnapshot, event: InitEvent): InitSnapshot
 			// resurrect a state the app deliberately left.
 			return state.status === 'initializing' ? at('ready') : state;
 
+		case 'RESUME':
+			// Same guard as START, for the same reason: `disabled`, `undecided` and
+			// `unavailable` are not left by a gate reopening. `canStart` excludes
+			// them, and `initializing`, whose own outcome is still on its way.
+			return canStart(state.status) ? at('ready') : state;
+
 		case 'FAIL':
 			return state.status === 'initializing' ? at('failed', { error: event.error }) : state;
 

package/src/engine/admobEngine.ts

@@ -61,6 +61,7 @@ interface ProviderModule {
 interface ProviderConsent {
 	requestInfoUpdate(options?: Record<string, unknown>): Promise<ProviderConsentInfo>;
 	loadAndShowConsentFormIfRequired(): Promise<ProviderConsentInfo>;
+	showPrivacyOptionsForm(): Promise<ProviderConsentInfo>;
 	getConsentInfo(): Promise<ProviderConsentInfo>;
 	reset(): void;
 }
@@ -69,6 +70,7 @@ interface ProviderConsentInfo {
 	status?: string;
 	canRequestAds?: boolean;
 	isConsentFormAvailable?: boolean;
+	privacyOptionsRequirementStatus?: string;
 }
 
 /**
@@ -119,9 +121,25 @@ function toEngineConsentInfo(info: ProviderConsentInfo): EngineConsentInfo {
 		status: normalized,
 		canRequestAds: info.canRequestAds === true,
 		isFormAvailable: info.isConsentFormAvailable === true,
+		privacyOptions: toEnginePrivacyOptions(info.privacyOptionsRequirementStatus),
 	};
 }
 
+/**
+ * Same rule as the status: an unrecognized value is `unknown`, never a guess in
+ * either direction (FR-150).
+ */
+function toEnginePrivacyOptions(value: string | undefined): EngineConsentInfo['privacyOptions'] {
+	switch (String(value ?? 'UNKNOWN').toUpperCase()) {
+		case 'REQUIRED':
+			return 'required';
+		case 'NOT_REQUIRED':
+			return 'not_required';
+		default:
+			return 'unknown';
+	}
+}
+
 function loadProvider(): ProviderModule | null {
 	try {
 		return require('react-native-google-mobile-ads') as ProviderModule;
@@ -362,6 +380,14 @@ function createAdMobConsent(getProvider: () => ProviderModule | null): ConsentPo
 			return toEngineConsentInfo(info);
 		},
 
+		async showPrivacyOptionsForm() {
+			// Present in the pinned bridge 16.0.3, so no range change (FR-155).
+			// Resolves with the consent information as it stands once the form
+			// closes, whether the user changed anything or not.
+			const info = await requireConsent().showPrivacyOptionsForm();
+			return toEngineConsentInfo(info);
+		},
+
 		async getInfo() {
 			return toEngineConsentInfo(await requireConsent().getConsentInfo());
 		},

package/src/engine/port.ts

@@ -52,6 +52,8 @@ 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 {
@@ -76,6 +78,13 @@ export interface ConsentPort {
 	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. */