@chipmobilesdk/rn-ads 0.2.1 → 0.4.0

package/package.json

@@ -1,49 +1,49 @@
-{
-	"name": "@chipmobilesdk/rn-ads",
-	"version": "0.2.1",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		},
-		"./testing": {
-			"types": "./src/testing/index.ts",
-			"react-native": "./src/testing/index.ts",
-			"default": "./src/testing/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/config",
-		"src/core",
-		"src/diagnostics",
-		"src/engine",
-		"src/react",
-		"src/testing",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-google-mobile-ads": ">=16.0.3 <16.1.0"
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-ads",
+	"version": "0.4.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/config",
+		"src/core",
+		"src/diagnostics",
+		"src/engine",
+		"src/react",
+		"src/testing",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-google-mobile-ads": ">=16.0.3 <16.1.0"
+	},
+	"engines": {
+		"node": ">=22.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-ads/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: sdk-rn-ads
-description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded/app-open behind a provider-neutral contract, placement keys, optional consent orchestration, three-state enablement, bounded retry, per-environment test-ad substitution. Use when adding ads to a screen, running a consent flow without importing AdMob, deferring ads until a purchase check resolves, debugging an ad that never loads, mapping ad units per environment, or answering a Data safety question about advertising."
+description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded/app-open behind a provider-neutral contract, placement keys, optional consent orchestration incl. the privacy options (change my consent) form, three-state enablement, bounded retry, per-environment test-ad substitution, per-placement request throttling. Use when adding ads to a screen, running a consent flow without importing AdMob, adding a Privacy options entry to Settings, deferring ads until a purchase check resolves, debugging an ad that never loads or reports throttled, placing a banner inside a list or a view the user swipes between, mapping ad units per environment, or answering a Data safety question about advertising."
 metadata:
   package: "@chipmobilesdk/rn-ads"
-  packageVersion: "0.2.0"
+  packageVersion: "0.4.0"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -19,6 +19,7 @@ consent.
 
 - Adding a banner, interstitial, rewarded or app-open ad to a screen
 - Running a consent flow in a region that requires one, without importing AdMob
+- Letting a user change their consent later (a "Privacy options" entry in Settings)
 - Deferring ads at startup until a purchase or entitlement check answers
 - Turning ads back on after a subscription lapses or a refund lands
 - Mapping AdMob ad units to placement keys per environment
@@ -30,7 +31,7 @@ consent.
 
 - **Consent UI or copy** — the package *orchestrates* the provider's flow and normalizes
   the outcome, but the form is drawn by the provider and the legal text is theirs. Timing,
-  surrounding copy and the "change your mind" path stay yours.
+  surrounding copy, and where the "change your mind" entry lives stay yours.
 - **Where or how often ads appear** — no frequency cap, no placement rule, no auto-insert.
   The package never shows an ad on its own, app-open included.
 - **Granting the reward** — it reports `reward_earned`; entitlement is the app's.
@@ -45,8 +46,21 @@ gate withheld, **zero** provider calls occur — not even configuration. `childD
 `underAgeOfConsent` and `maxAdContentRating` take effect only if they reach
 `initialize()` *before* the provider starts; changing one later returns
 `requires_reinitialization` rather than silently not applying.
+Once you call `ads.consent.*`, the flow is part of that gate: `initialize()` returns
+`blocked` · `consent_flow_required` until it permits, and the package initializes by
+itself when it does — do not retry `initialize()` in a loop.
 See `## Initialize — consent comes first` and `## Consent`.
 
+## "Change my consent" is covered — never `reset()` + re-show
+
+New in 0.4.0. Show your Settings entry when `consent.getState().privacyOptionsRequirement`
+is `'required'` (hide it on `'unknown'` and `'not_required'`), and call
+`ads.consent.showPrivacyOptionsForm()` from it. Where the entry lives, and its copy, stay
+yours. The result feeds the gate by itself. A withdrawal moves `ready` → `blocked` and
+cancels in-flight loads; a re-grant resumes with **no second native initialization**.
+`consent.reset()` is testing-only — it wipes the stored decision while the form is open.
+See `### Letting users change their choice` under `## Consent`.
+
 ## Three gates, one reason — check this order first
 
 A refused request reports exactly one reason, and the precedence is fixed:
@@ -85,12 +99,38 @@ defect and it is fixed. The result now says which happened:
 
 Existing `ads.setEnabled(false);` call sites still compile untouched.
 
-## Four things not to "fix"
+## A banner in a list or a swipeable view gets throttled — by design
+
+New in 0.3.0. A banner mounted inside a view the user navigates between — a day in a
+calendar, a tab, a row that scrolls in and out — is unmounted and remounted by React on
+every navigation, and **each remount is a billable request**. Ten quick swipes used to be
+ten requests in a few seconds, which ad networks read as invalid traffic. The penalty is
+account-level and no shipped fix recovers it.
+
+So each placement now has a minimum interval between *requests*: **60s for a banner**
+(AdMob's own refresh floor), **off for full-screen formats** — those are loaded by an
+explicit call, not mounted by a renderer, so they never had the problem. A refusal reports
+`throttled` on the placement and emits `request_throttled` with `retryAfterMs`.
+
+Three things to know before you reach for `minRequestIntervalMs: 0`:
+
+- **`throttled` is not `failed` and not a no-fill.** Nothing is wrong and nothing was
+  requested. Collapse the space if you like, but do not log it as an error.
+- **Rotation is exempt.** A width re-adaptation inside one mount is not charged, so a
+  rotated screen keeps its banner.
+- **The better fix is architectural.** Keep the banner outside the subtree that remounts
+  and the throttle never fires. It is a safety net, not a licence to ignore the problem.
+
+This is **not** a frequency cap. It limits how often a placement may *ask*; how often you
+*show* is yours, and the package deliberately ships no pacing (see `## Do not use this for`).
+
+## Five things not to "fix"
 
 - **The bridge pin.** `react-native-google-mobile-ads` is peered at `>=16.0.3 <16.1.0`;
   16.1.0+ carries Kotlin 2.3 metadata that React Native 0.85's pinned compiler cannot
-  read, and the Android build fails outright. `0.2.0` needed no bump — consent and
-  app-open are both already in `16.0.3`. Read `## Compatibility` before widening it.
+  read, and the Android build fails outright. `0.2.0` and `0.4.0` needed no bump —
+  consent, app-open and privacy options are all already in `16.0.3`. Read
+  `## Compatibility` before widening it.
 - **Test ads in dev.** Outside `production`, non-official ad units are replaced with
   Google's test units and reported via `config_warning` / `getSubstitutedPlacements()`.
   That is the safety guarantee working, not a misconfiguration. Never click a production
@@ -101,6 +141,9 @@ Existing `ads.setEnabled(false);` call sites still compile untouched.
 - **A declined consent still reporting `obtained` / `canRequestAds: true`.** That is UMP's
   meaning, not a bug: `OBTAINED` means *an answer was recorded*, and non-personalized ads
   stay servable. The package forwards the provider's verdict rather than inventing one.
+- **A banner reporting `throttled` right after a navigation.** That is 0.3.0's request
+  floor working — see the section above. Lower it knowingly or move the banner out of the
+  remounting subtree; do not set `0` to make the symptom go away.
 
 ## Retry is off unless you ask
 
@@ -120,7 +163,7 @@ on a return **from an ad** — or from a browser an ad opened — is refused wit
 return apart from any other; the package can. It cannot survive process death, and a
 browser opened without a preceding click is undetectable. See `## App open`.
 
-## Public API (v0.2.0)
+## Public API (v0.4.0)
 
 Runtime: `createAds` (throws `AdsConfigError` on a bad catalog or an out-of-range retry
 policy; everything else returns a typed result rather than throwing) · `AdsProvider`,
@@ -129,7 +172,9 @@ policy; everything else returns a typed result rather than throwing) · `AdsProv
 `DEFAULT_SHOW_TIMEOUT_MS`, `DEFAULT_AD_VALIDITY_MS`, `DEFAULT_APP_OPEN_VALIDITY_MS`,
 `DEFAULT_RETRY_POLICY`, `DEFAULT_UNDECIDED_WARNING_MS`, `LOAD_TIMEOUT_BOUNDS`,
 `SHOW_TIMEOUT_BOUNDS`, `AD_VALIDITY_BOUNDS`, `APP_OPEN_VALIDITY_BOUNDS`, `RETRY_BOUNDS`,
-`UNDECIDED_WARNING_BOUNDS` · `createFakeAdsEngine`, `createTestClock` from
+`UNDECIDED_WARNING_BOUNDS`, `DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS`,
+`DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS`, `MIN_REQUEST_INTERVAL_BOUNDS`,
+`defaultMinRequestIntervalMs` · `createFakeAdsEngine`, `createTestClock` from
 `@chipmobilesdk/rn-ads/testing` (test doubles only).
 
 Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setEnablement`, `setAppActive`,
@@ -138,11 +183,13 @@ Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setEnablement`, `setAppA
 `getIgnoredConsentTools`, `dispose`.
 
 Consent namespace (`ads.consent.*`, opt-in — untouched, nothing starts):
-`requestInfoUpdate`, `showFormIfRequired`, `getState`, `subscribe`, `reset`.
+`requestInfoUpdate`, `showFormIfRequired`, `showPrivacyOptionsForm`, `getState`,
+`subscribe`, `reset`.
 
 Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdFormat`,
 `FullScreenFormat`, `Environment`, `Enablement`, `EnablementResult`, `ConsentApi`,
-`ConsentState`, `ConsentSnapshot`, `ConsentTestingOptions`, `RetryPolicy`, `InitStatus`,
+`ConsentState`, `ConsentSnapshot`, `ConsentTestingOptions`, `PrivacyOptionsRequirement`,
+`PrivacyOptionsFormResult`, `RetryPolicy`, `InitStatus`,
 `PlacementState`, `InitResult`, `LoadResult`, `ShowResult`, `PrivacyUpdateResult`,
 `Reward`, `AdEvent`, `AdEventType`, `AdEventListener`, `ConfigWarning`, `ImpressionSource`,
 `AdsErrorCode`, `AdsOperation`, `TimeoutConfig`, `AdContentRating`, `PrivacyBlockReason`,
@@ -151,6 +198,40 @@ Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdF
 Call `dispose()` when the owning screen unmounts; it is idempotent, and so is every
 `Unsubscribe`.
 
+## Upgrading 0.3.x → 0.4.0
+
+No code change: no existing union gained a member. New: `showPrivacyOptionsForm`,
+`ConsentSnapshot.privacyOptionsRequirement`, and the types above. A hand-written
+`ConsentSnapshot` literal (a test mock) needs the new field.
+
+**Three behaviour changes:** `initialize()` after a declined or failed consent flow
+returns `blocked` and initializes nothing (0.3.0 returned `ready` and initialized); a
+consent gate closing while `ready` now reports `blocked` and cancels in-flight loads
+(0.3.0 stayed `ready` and a mounted banner kept requesting); and reopening a gate
+resumes with no second native initialization (0.3.0 initialized again), unless an
+init-time flag changed in between.
+
+**Fixed:** a `load()` in flight when ads are disabled, undecided or disposed now resolves
+(`disabled` / `undecided` / `unavailable`) instead of never settling.
+
+## Upgrading 0.2.x → 0.3.0
+
+One compile-time change and one behaviour change.
+
+| Union | New member |
+|---|---|
+| `PlacementState` | `'throttled'` |
+| `LoadResult` | `{ status: 'throttled', retryAfterMs }` |
+| `AdEventType` | `'request_throttled'` |
+
+**The behaviour change:** banner placements now have a 60s floor between requests. If your
+banner lives inside a list row, a tab, or a view the user swipes between, it will report
+`throttled` after a quick navigation where 0.2.x silently issued another request. That was
+the bug; this is the fix. Read the throttle section above before setting
+`minRequestIntervalMs: 0`.
+
+Full-screen formats are unchanged — their default floor is `0`.
+
 ## Upgrading 0.1.0 → 0.2.0
 
 One required change, compile-time only: five unions gained members, so an exhaustive
@@ -177,11 +258,13 @@ Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
 | First integration | `## Install`, `## Configure` |
 | Consent ordering | `## Initialize — consent comes first` |
 | Running the consent flow | `## Consent` |
+| A "Privacy options" entry, withdrawal and re-grant | `### Letting users change their choice` |
 | Rendering a banner | `## Banner` |
 | Full-screen formats | `## Interstitial and rewarded` |
 | App-open and ad-originated return | `## App open` |
 | Turning ads off, undecided, re-enabling | `## Turning ads off — three states` |
 | Retry and reconciling it against a bill | `## Retry` |
+| Request throttling, banners in lists | `## Request throttling` |
 | Why a request was refused | `## Why an ad did not show` |
 | Results, events, errors, timeouts, cleanup | `## State, events, and errors` |
 | Tests without a device | `## Testing` |

package/src/config/types.ts

@@ -65,6 +65,18 @@ export interface PlacementDefinition {
 	 * override can narrow behavior but never exceed a ceiling (FR-136a).
 	 */
 	readonly retry?: RetryPolicy | false;
+	/**
+	 * Minimum milliseconds between two provider requests for this placement
+	 * (FR-140), added in 0.3.0.
+	 *
+	 * Absent takes the format-aware default: 60s for a banner, off for full-screen
+	 * formats. `0` turns it off here while leaving it on elsewhere.
+	 *
+	 * This is an **account-safety** floor, not a frequency cap: it limits how often
+	 * a placement may *ask* for an ad, never how often the app may *show* one. If
+	 * you are reaching for this to pace interstitials, that belongs in the app.
+	 */
+	readonly minRequestIntervalMs?: number;
 }
 
 /**
@@ -139,11 +151,29 @@ export type ConsentState =
 	 */
 	| 'error';
 
+/**
+ * Whether the user must be offered a way to change their consent choice
+ * (FR-150), added in 0.4.0.
+ *
+ * The provider's verdict, forwarded — never the package's judgement about a
+ * region, exactly as `not_required` in `ConsentState` is not. `required` is the
+ * app's cue to show its own "Privacy options" entry; where that entry lives and
+ * what it says stay the app's.
+ *
+ * `unknown` before the first successful `requestInfoUpdate()`, after `reset()`,
+ * after a failed update, and on a platform with no adapter. It is not `not_required`:
+ * an app that hides the entry on `unknown` is right to, but it must not conclude
+ * the user has no right to one.
+ */
+export type PrivacyOptionsRequirement = 'required' | 'not_required' | 'unknown';
+
 export interface ConsentSnapshot {
 	readonly state: ConsentState;
 	/** Always false when `state` is `error`. */
 	readonly canRequestAds: boolean;
 	readonly isFormAvailable: boolean;
+	/** Whether to offer a "change my choice" entry (FR-150). Added in 0.4.0. */
+	readonly privacyOptionsRequirement: PrivacyOptionsRequirement;
 	readonly error: AdsError | null;
 }
 
@@ -269,6 +299,16 @@ export type PlacementState =
 	| 'failed'
 	/** Mirrors `InitStatus.undecided` so the banner host can report it directly. */
 	| 'undecided'
+	/**
+	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
+	 *
+	 * Deliberately distinct from `failed` and from a no-fill: nothing is wrong,
+	 * nothing was requested, and the same placement will work again shortly. An
+	 * app that collapses its ad slot on `failed` will usually want to collapse on
+	 * this too, but it must be able to tell the two apart when diagnosing why a
+	 * banner is absent.
+	 */
+	| 'throttled'
 	| 'unavailable';
 
 /** FR-047. The provider's reward descriptor, normalized. */