@chipmobilesdk/rn-ads 0.4.0 → 0.5.0

package/src/core/placementMachine.ts

@@ -40,9 +40,19 @@ export const initialPlacement: PlacementSnapshot = {
 	correlationId: null,
 };
 
-/** A load is only legal from a settled state; `loading` is where FR-029 bites. */
+/**
+ * A load is only legal from a settled state; `loading` is where FR-029 bites.
+ * `throttled` is settled too: it records that the last request was refused, and
+ * the throttle itself decides whether the next one may proceed.
+ */
 export function canLoad(state: PlacementState): boolean {
-	return state === 'idle' || state === 'failed' || state === 'consumed' || state === 'ready';
+	return (
+		state === 'idle' ||
+		state === 'failed' ||
+		state === 'consumed' ||
+		state === 'ready' ||
+		state === 'throttled'
+	);
 }
 
 /** Only a ready ad may be shown. Everything else is a determinate refusal (FR-028). */

package/src/core/privacyGate.ts

@@ -15,7 +15,7 @@
  */
 
 import type { PrivacyBlockReason, PrivacyOptions } from '../config/types';
-import type { EnginePrivacy } from '../engine/port';
+import type { EnginePrivacy, EngineRequestOptions } from '../engine/port';
 
 export type GateDecision =
 	| { readonly allowed: true }
@@ -83,3 +83,12 @@ export function toEnginePrivacy(
 		testDeviceIds,
 	};
 }
+
+/**
+ * What every ad request carries. Unset means personalized, matching the
+ * documented default of `PrivacyOptions.personalizedAds`; only an explicit
+ * `false` opts out.
+ */
+export function toEngineRequest(privacy: PrivacyOptions | null): EngineRequestOptions {
+	return { personalizedAds: privacy?.personalizedAds !== false };
+}

package/src/engine/admobEngine.ts

@@ -27,6 +27,7 @@ import type {
 	EngineConsentInfo,
 	EngineConsentOptions,
 	EnginePrivacy,
+	EngineRequestOptions,
 } from './port';
 
 /** The slice of the bridge this adapter uses. Kept local so nothing else sees it. */
@@ -227,7 +228,11 @@ export function createAdMobEngine(): AdsEngine {
 			await mobileAds.initialize();
 		},
 
-		async createFullScreen(format: FullScreenFormat, adUnitId: string) {
+		async createFullScreen(
+			format: FullScreenFormat,
+			adUnitId: string,
+			request?: EngineRequestOptions,
+		) {
 			const module = getProvider();
 			if (!module) {
 				throw new Error('provider_missing');
@@ -242,7 +247,7 @@ export function createAdMobEngine(): AdsEngine {
 			const ad = factory.createForAdRequest(adUnitId, {
 				// The consumer-facing polarity is `personalizedAds`; the provider's
 				// is the inverse. The flip lives here, next to the API needing it.
-				requestNonPersonalizedAdsOnly: false,
+				requestNonPersonalizedAdsOnly: request?.personalizedAds === false,
 			});
 
 			counter += 1;

package/src/engine/port.ts

@@ -23,6 +23,17 @@ export interface EnginePrivacy {
 	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
@@ -108,8 +119,16 @@ export interface AdsEngine {
 	 */
 	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>;
+	/**
+	 * 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>;