@chipmobilesdk/rn-ads 0.2.1 → 0.3.0

package/README.md

@@ -1,671 +1,771 @@
-# @chipmobilesdk/rn-ads
-
-Reusable advertising capability for ChipMobileSdk-family React Native apps.
-
-The package owns **capability**: a safe, consistent, provider-neutral way to request and present ads. Your app owns **policy**: where ads appear, when, how often, to whom, under what consent, and whether they appear at all. There is no placement rule, no frequency cap, and no screen name in this package.
-
-**You never import the Google Mobile Ads SDK.** You name a placement key you chose, and the package does the rest.
-
----
-
-## Scope
-
-| | 0.2.0 |
-|---|---|
-| **Platform** | Android only. iOS returns `unavailable` / `unsupported_platform` and never breaks a build. |
-| **Provider** | Google AdMob, via `react-native-google-mobile-ads` |
-| **Formats** | Anchored adaptive banner, interstitial, rewarded, app-open |
-| **Consent** | Optional orchestration of the provider's consent flow — you still import nothing of theirs |
-| **Deferred** | Native, rewarded-interstitial, mediation, iOS — see [Known limitations](#known-limitations) |
-
-## Compatibility
-
-| | Supported |
-|---|---|
-| React | `>=19` (verified against 19.2.3) |
-| React Native | `>=0.85`, New Architecture (verified against 0.85.3) |
-| Node | `>=22.11.0` |
-| Android | `minSdk 24`, `compileSdk 36`, `targetSdk 36`, Kotlin 2.1.x |
-| Provider bridge | `react-native-google-mobile-ads` **`>=16.0.3 <16.1.0`** |
-| Google Mobile Ads Android SDK | 24.9.0 (transitive) |
-| Google UMP (consent) | 4.0.0 (transitive) |
-
-> **`0.2.0` required no bridge bump.** The pinned `16.0.3` already exposes everything the consent flow and the app-open format need — verified against the installed type declarations rather than assumed from documentation. The Kotlin constraint below is therefore untouched by this release.
-
-> **Why the bridge range is closed at the top.** Bridge 16.1.0+ moves to Google Mobile Ads 25.x, which is compiled with Kotlin 2.3.0 metadata. React Native 0.85.3 pins the Kotlin **compiler** at 2.1.x, and the build fails with `Module was compiled with an incompatible version of Kotlin`. Raising the root `ext.kotlinVersion` does not fix it — that moves only `kotlin-stdlib`, not the compiler. An open caret would let a routine `npm install` walk straight back into a build failure, so the range refuses rather than drifts. Revisit when React Native ships a Kotlin 2.3 compiler.
-
----
-
-## Install
-
-```sh
-npm install @chipmobilesdk/rn-ads react-native-google-mobile-ads@16.0.3
-```
-
-### Required Android configuration
-
-Add your AdMob **application ID** to the app's `app.json`. The bridge's Gradle script reads this key and merges it into `AndroidManifest.xml`; without it the native SDK crashes on startup.
-
-```jsonc
-{
-  "react-native-google-mobile-ads": {
-    // Google's public test application ID. Replace with your own for release.
-    "android_app_id": "ca-app-pub-3940256099942544~3347511713"
-  }
-}
-```
-
-**The shared package carries no application ID and no ad unit ID.** Both are per-app configuration.
-
-### Permissions merged into your manifest
-
-Contributed by the provider, not requested by this package:
-
-Verified against a real merged manifest, not a list from documentation:
-
-| Permission | Source |
-|---|---|
-| `android.permission.INTERNET` | bridge manifest |
-| `android.permission.ACCESS_NETWORK_STATE` | bridge manifest |
-| `android.permission.WAKE_LOCK` | bridge manifest |
-| `com.google.android.gms.permission.AD_ID` | `play-services-ads-api` |
-| `android.permission.ACCESS_ADSERVICES_AD_ID` | `play-services-ads-api` |
-| `android.permission.ACCESS_ADSERVICES_ATTRIBUTION` | `play-services-ads-api` |
-| `android.permission.ACCESS_ADSERVICES_TOPICS` | `play-services-ads-api` |
-
-**Re-verified for `0.2.0`.** Adding the app-open format and activating the consent module contributed **no new permission** — both live in the already-pinned bridge, so the merged result is byte-identical to `0.1.0`'s.
-
-The last three are **Android Privacy Sandbox** permissions covering the Privacy Sandbox ad ID, attribution reporting, and the Topics API. They matter for your Data safety declaration and they are easy to miss, because they appear only in the merged result — no library README lists them.
-
-Verify the actual merged result before release — read the file, don't trust this table:
-
-```sh
-cd android && ./gradlew :app:assembleDebug
-# then inspect android/app/build/intermediates/merged_manifests/**/AndroidManifest.xml
-```
-
-**To remove advertising identifier access** (required for child-directed apps under Play Families policy).
-
-Removing `AD_ID` alone is **not enough** — verified by rebuild, the three Privacy Sandbox permissions survive it and must be removed explicitly:
-
-```xml
-<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />
-<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" tools:node="remove" />
-<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" tools:node="remove" />
-<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" tools:node="remove" />
-```
-
-Your `<manifest>` tag needs `xmlns:tools="http://schemas.android.com/tools"`. Rebuild and re-inspect the merged manifest to confirm — do not assume.
-
----
-
-## Configure
-
-Placement keys are **yours**. Provider ad unit IDs appear here in configuration and nowhere else in your code.
-
-```ts
-import { createAds } from '@chipmobilesdk/rn-ads';
-
-const ads = createAds({
-  enabled: true,                 // your feature flag; false makes everything a safe no-op
-  environment: 'development',    // 'development' | 'test' | 'production'
-  placements: [
-    { key: 'home_footer',       format: 'banner',       androidAdUnitId: 'ca-app-pub-…/…' },
-    { key: 'level_break',       format: 'interstitial', androidAdUnitId: 'ca-app-pub-…/…' },
-    { key: 'completion_reward', format: 'rewarded',     androidAdUnitId: 'ca-app-pub-…/…' },
-  ],
-});
-```
-
-`createAds` **throws** on a malformed catalog — duplicate key, missing ad unit, unknown format, out-of-band timeout — naming the offending placement. Every other failure in the package is a typed result, never a throw.
-
-Reading configuration requires no dotenv library, no remote-config service, and no feature-flag system. Supply the values however you like.
-
-### How production traffic is made impossible
-
-In `development` and `test`, any ad unit that is not one of Google's official test units is **replaced** with one, and the substitution is reported — as a `config_warning` event naming every affected placement, and in observable state via `ads.getSubstitutedPlacements()`.
-
-```
-environment: development
-  home_footer -> ca-app-pub-REAL…/1234567890
-
-  ⚠ config_warning: test_ad_unit_substituted
-      placementKeys: ['home_footer']
-  → request sent with ca-app-pub-3940256099942544/9214589741
-  → your app keeps working
-```
-
-In `production`, nothing is substituted — your units are used exactly as configured.
-
-The one case substitution cannot cover is a **debug build declaring `production`**: that would send real requests from a build that should never generate traffic. It fails closed with `production_in_dev_build`.
-
-> Invalid traffic from non-production builds can get an AdMob account suspended. **Never click a production ad to verify anything.**
-
----
-
-## Initialize — consent comes first
-
-The package will not initialize anything request-capable until your privacy gate permits it. This is enforced, not documented: with the gate withheld, **zero** provider calls occur.
-
-```tsx
-import { AdsProvider } from '@chipmobilesdk/rn-ads';
-
-await ads.initialize({
-  canRequestAds: true,        // your consent decision — the package renders no consent UI
-  consentUndetermined: false, // true means "not asked yet", distinct from "refused"
-  childDirected: false,
-  underAgeOfConsent: false,
-  maxAdContentRating: 'G',
-  personalizedAds: true,
-});
-
-<AdsProvider instance={ads}>{children}</AdsProvider>
-```
-
-**Ordering matters.** `childDirected`, `underAgeOfConsent`, and `maxAdContentRating` only take effect if they reach the provider *before* it initializes. Change one afterwards and `updatePrivacy` returns `requires_reinitialization` rather than pretending it applied.
-
-Resolving consent after being blocked is the normal path and creates **no** duplicate initialization:
-
-```ts
-await ads.initialize({ canRequestAds: false });   // → { status: 'blocked', reason: 'consent_required' }
-await ads.updatePrivacy({ canRequestAds: true }); // → { status: 'applied' }, one native init total
-```
-
-The package logs no personal data, no consent payload, and no advertising identifier.
-
----
-
-## Banner
-
-You place it. It sizes itself to your container and re-adapts on rotation.
-
-```tsx
-import { AdsBanner, usePlacementState } from '@chipmobilesdk/rn-ads';
-
-function Footer() {
-  const state = usePlacementState('home_footer');
-  const reserve = state === 'loading' || state === 'ready';
-
-  return reserve ? (
-    <View style={styles.slot}>
-      {state === 'loading' ? <YourThemedPlaceholder /> : null}
-      <AdsBanner placementKey="home_footer" />
-    </View>
-  ) : null; // your decision to reclaim the space
-}
-```
-
-The component **ships no placeholder** — that is yours, so it matches your theme. When ads are disabled or unavailable it renders `null`, not an empty view, so it leaves the accessibility tree entirely rather than taking screen-reader focus ahead of your content.
-
-## Interstitial and rewarded
-
-Load ahead of time; show only when *you* decide.
-
-```ts
-await ads.load('level_break');
-const result = await ads.show('level_break');
-
-switch (result.status) {
-  case 'shown':        break;
-  case 'not_ready':    break; // no UI opened, nothing crashed
-  case 'busy':         break; // another full-screen ad is up — never queued
-  case 'consumed':     break; // load a fresh one first
-  case 'app_inactive': break; // backgrounded
-  case 'blocked':      break; // result.reason
-  case 'disabled':     break;
-  case 'unavailable':  break; // result.reason
-  case 'timeout':      break;
-  case 'failed':       break; // result.error
-}
-```
-
-Rewards are reported **only** when the provider confirms them:
-
-```ts
-ads.subscribeEvents(event => {
-  if (event.type === 'reward_earned') {
-    grant(event.reward.type, event.reward.amount); // your grant, not the package's
-  }
-  if (event.type === 'dismissed' && event.rewardEarned === false) {
-    // closed early — no reward, and none inferred
-  }
-});
-```
-
-`reward_earned` and `dismissed` may arrive from the provider in either order; the outcome is identical, and a duplicate confirmation is collapsed into one event. **The package grants nothing** — validating and delivering the benefit is yours.
-
----
-
-## State, events, and errors
-
-**Initialization status**: `not_started` · `blocked` · `initializing` · `ready` · `disabled` · `unavailable` · `failed`
-
-**Placement state**: `idle` · `loading` · `ready` · `showing` · `consumed` · `failed` · `unavailable`
-
-**Events** carry the placement key, format, timestamp, and a `correlationId` tying one load/show cycle together — enough to reconstruct an ad's whole life from the stream alone. They carry no provider object, no advertising identifier, and no consent payload.
-
-`initialization` · `load_started` · `loaded` · `load_failed` · `display_started` · `impression` · `click` · `display_failed` · `dismissed` · `reward_earned` · `disabled` · `unavailable` · `config_warning` · `internal_error`
-
-> **One honest asymmetry.** `impression` carries `source: 'provider' | 'derived'`. Banners get a real provider impression callback. Full-screen formats have none in the provider's event enum, so theirs is derived from the ad opening. If you reconcile these events against AdMob revenue reporting, you need to know which is which.
-
-**Ordering and exactly-once** are documented and tested. Within one `correlationId`, `loaded` / `display_started` / `impression` / `dismissed` / `reward_earned` occur at most once; `click` may repeat. After `dispose()`, zero events are emitted — a late provider callback is dropped.
-
-**Errors** carry a stable `code`, a log-safe `message`, the `operation`, a `retryable` flag, and a redacted `cause`. Codes are public API; renaming one is a breaking change.
-
-Retryable: `no_fill` `network_error` `load_timeout` `show_timeout` `ad_expired` `not_ready` `busy` `consumed` `app_inactive` `provider_error`
-Not retryable: `invalid_config` `duplicate_placement_key` `missing_ad_unit_id` `format_mismatch` `placement_not_found` `production_in_dev_build` `timeout_out_of_bounds` `unsupported_platform` `provider_missing` `disabled` `consent_required` `consent_undetermined` `requires_reinitialization` `internal_error`
-
-Attach any logger or analytics you already use. The package depends on none:
-
-```ts
-const unsubscribe = ads.subscribeEvents(event => yourLogger.track(event.type, event));
-```
-
-A listener that throws is caught and reported once; it cannot break the state machine or starve other listeners.
-
-### Timeouts and cleanup
-
-| | Default | Configurable range |
-|---|---|---|
-| Load timeout | 30 000 ms | 5 000 – 120 000 |
-| Show timeout | 10 000 ms | 5 000 – 30 000 |
-| Loaded-ad validity | 3 600 000 ms | 60 000 – 3 600 000 |
-| App-open validity | 1 800 000 ms | 60 000 – 3 600 000 |
-| Undecided warning | 10 000 ms | 1 000 – 120 000 |
-
-Out-of-band values are a configuration error, not silently clamped. A loaded full-screen ad older than its validity window stops reporting `ready` and requires a reload — so you never render a button for an ad that will fail on tap.
-
-`dispose()` cancels every timer and subscription and releases every handle — including a consent flow in progress, a pending retry, and the undecided-state warning. It is idempotent, and so is every `Unsubscribe`.
-
----
-
-## Retry
-
-**Off by default.** Upgrading from `0.1.0` without configuring `retry` sends exactly the requests it always did.
-
-```ts
-createAds({
-  // ...
-  retry: { maxRetries: 2, initialDelayMs: 2_000, maxDelayMs: 30_000 },
-  placements: [
-    { key: 'home_footer', format: 'banner', androidAdUnitId: '...' },
-    // Off for this placement only: a rewarded retry happens with a user
-    // waiting on the other side of it.
-    { key: 'bonus', format: 'rewarded', androidAdUnitId: '...', retry: false },
-  ],
-});
-```
-
-| | Default | Range |
-|---|---|---|
-| `maxRetries` (attempts after the first) | 2 | 1 – 5 |
-| `initialDelayMs` | 2 000 | 500 – 30 000 |
-| `maxDelayMs` | 30 000 | 1 000 – 60 000 |
-
-Backoff is exponential with a fixed x2 multiplier and no jitter — a single device has no fleet to desynchronize, and determinism makes the attempt count exactly assertable.
-
-**Only `retryable` errors are retried.** Configuration errors, consent errors, an unsupported platform, and a disabled or undecided instance never are: another attempt cannot change any of them, so retrying would spend a billable request on a certainty.
-
-A per-placement `retry` **replaces** the instance-wide policy rather than merging into it, so the effective policy for a placement is readable from the configuration without simulating a merge. Both are held to the same bounds, so an override can narrow behavior but never exceed a ceiling. Out-of-range values throw at construction — you find out when you build the instance, not on the first failed load in production.
-
-Disabling ads, moving to `undecided`, losing consent, or `dispose()` cancels **every** pending retry across every placement immediately.
-
-### Reconciling retries against a bill
-
-Each attempt emits a `retry_scheduled` event carrying the **same `correlationId`** as the load cycle that triggered it:
-
-```ts
-ads.subscribeEvents(event => {
-  if (event.type === 'retry_scheduled') {
-    analytics.track('ad_retry', {
-      placement: event.placementKey,
-      attempt: event.attempt,
-      delayMs: event.delayMs,
-      reason: event.error.code,
-      cycle: event.correlationId,
-    });
-  }
-});
-```
-
-Counting `load_started` plus `retry_scheduled` for a placement gives the number of requests that placement actually cost you. You keep the option of ignoring all of this and writing your own retry — enabling the package's is a choice, not a replacement.
-
----
-
-## Turning ads off — three states
-
-`enabled` accepts `true`, `false`, or `'undecided'`.
-
-| State | Requests sent | Init status | Banner reports | When to use it |
-|---|---|---|---|---|
-| `true` | yes | normal | normal | Ads are on |
-| `false` | **zero** | `disabled` | `unavailable` | A settled no |
-| `'undecided'` | **zero** | `undecided` | `undecided` | You do not know yet |
-
-### Why the third state exists
-
-If you sell an ad-removal tier, at cold start you do not yet know whether this user has paid — that answer arrives after a store sync. Both of the other options are wrong: `true` flashes an ad at someone who paid not to see one, and `false` delays ads for every free user and drops you into the re-enable path below.
-
-`undecided` sends nothing, exactly like `disabled`, but reports itself **distinctly** so your banner host can hold the space rather than reclaim it:
-
-```tsx
-<AdsBanner placementKey="home_footer" onStateChange={setState} />
-{state === 'undecided' ? <YourThemedPlaceholder /> : null}
-```
-
-Resolve it exactly once when you know:
-
-```ts
-const result = ads.setEnablement(userOwnsAdRemoval ? 'disabled' : 'enabled');
-```
-
-The package **never resolves it for you** — that would mean guessing at a business decision it is forbidden to know about. If you leave it unresolved past `undecidedWarningMs` you get one `config_warning` (`enablement_undecided_timeout`) and nothing else. One, not a repeating stream: a warning that fires every ten seconds becomes noise that gets filtered.
-
-### Re-enabling
-
-**This changed in `0.2.0`, and the old behavior was a defect.** In `0.1.0`, `setEnabled(true)` after a disable dropped the init status to `not_started`, so every later `load` and `show` was refused — and `setEnabled` returned `void`, so nothing told you. An app whose user's subscription lapsed would turn ads back on and silently show none.
-
-Now the result is typed and always says what happened:
-
-```ts
-const result = ads.setEnabled(true);
-
-switch (result.status) {
-  case 'resumed':
-    // The provider was never un-initialized. Nothing to do — load away.
-    break;
-  case 'requires_initialization':
-    // Never reached ready, privacy changed, or the platform went away.
-    await ads.initialize(privacy);
-    break;
-  default:
-    break;
-}
-```
-
-The package does **not** initialize implicitly on your behalf: that would hide an asynchronous, billable operation behind a setter you may not be awaiting, and a failure would surface with no call site to attribute it to.
-
-If your privacy options have not changed you do not supply them again. They live in memory for the lifetime of the instance and are never persisted.
-
-In every off state — `false` or `'undecided'` — in-flight loads are released deterministically, and an ad **already on screen is not force-closed**: the provider offers no safe way to do so, and yanking a full-screen ad out from under the user would be worse than letting it finish.
-
-### Wiring it to an external decision
-
-The package has no idea what an entitlement is. That is deliberate — it receives a decision, never a reason:
-
-```ts
-const ads = createAds({ enabled: 'undecided', /* ... */ });
-
-// Whatever answers this for you: a billing library, your own backend, a cached
-// receipt. The package neither knows nor stores which.
-entitlements.subscribe(owned => {
-  ads.setEnablement(owned ? 'disabled' : 'enabled');
-});
-```
-
----
-
-## Consent
-
-**Optional.** If you already supply your own gate through `PrivacyOptions.canRequestAds`, nothing here starts on your behalf and your `0.1.0` integration is untouched.
-
-Use it when you ship to a region that requires consent. Before `0.2.0` that meant importing the provider's consent SDK directly — which broke the one promise this package exists to keep — and hand-writing the same order-sensitive orchestration every other such app was also writing.
-
-```ts
-// Nothing here imports the ad provider.
-const info = await ads.consent.requestInfoUpdate();
-
-if (info.state === 'required') {
-  await ads.consent.showFormIfRequired();  // the provider draws the form
-}
-
-// The outcome feeds the privacy gate by itself. No wiring, and no second
-// native initialization.
-await ads.load('level_break');
-```
-
-### Normalized consent states
-
-| State | Meaning | `canRequestAds` | Your next step |
-|---|---|---|---|
-| `undetermined` | Not asked yet. Initial value, and the value after a reset. | `false` | `requestInfoUpdate()` |
-| `not_required` | The provider says this region does not require consent. | `true` | Nothing — ads proceed |
-| `required` | Required and not yet obtained. | `false` | `showFormIfRequired()` |
-| `obtained` | Obtained. | `true` | Nothing — ads proceed |
-| `error` | The flow failed. | **always `false`** | Optionally retry the flow |
-
-Three rules the package will not bend:
-
-- **A failure is never consent.** A provider error, a network failure, a cancellation, and a form dismissed without an answer all produce `error`, and `error` never carries permission. The failure this prevents is invisible in production: a request that should not have happened looks exactly like one that should.
-- **The package does not decide which regions require consent.** `not_required` is the provider's answer forwarded, not this package's judgement.
-- **A consent failure never crashes your app or blocks startup.** It is a normalized error you can act on or ignore.
-
-The package renders **no consent UI**. The form is the provider's. Timing, surrounding copy, and the experience when a user later changes their mind stay yours — as does deciding whether to run the flow at all. A user declining is a normal path, not an error.
-
-### Package flow or your own gate?
-
-| | Package flow | Your own gate |
-|---|---|---|
-| You call | `ads.consent.*` | `initialize({ canRequestAds })` |
-| Form drawn by | the provider | you, or a third-party CMP |
-| Good when | you use the provider's consent messages | you already run a consent platform |
-
-You can do both. They combine as **most-restrictive-wins**: requesting is permitted only when both permit it, and either alone can block. So if you obtained consent but independently blocked ads for a reason of your own, your block survives — the package is forbidden to know your reason and therefore must never overrule it. The reported reason names which input is blocking.
-
-### Testing the flow from outside the region
-
-```ts
-createAds({
-  environment: 'development',
-  consentTesting: { debugGeography: 'eea', resetOnStart: true },
-  // ...
-});
-```
-
-**Both tools are stripped in `production`.** Not checked at each call site — removed at configuration validation, so no code path can forget. The fact that they were ignored is observable, not merely documented: a `config_warning` (`consent_tool_ignored_in_production`) naming each one, and `getIgnoredConsentTools()` on the instance.
-
-### What gets stored on the device
-
-The consent platform persists the user's decision on the device under IAB TCF keys. This package neither reads, logs, nor includes it in any event — but **your Google Play Data safety declaration depends on it**, so review that before shipping the consent flow.
-
----
-
-## App open
-
-A fourth format, declared in the catalog exactly like the other three and using the same placement states, events, and error codes.
-
-```ts
-{ key: 'cold_start', format: 'app_open', androidAdUnitId: 'ca-app-pub-.../...' }
-```
-
-```ts
-await ads.load('cold_start');
-const result = await ads.show('cold_start');  // you decide when
-```
-
-**The package never shows one on its own.** As with interstitial and rewarded, every show is an explicit call you make.
-
-It shares the **same single full-screen lock** as interstitial and rewarded, so two full-screen ads are never open at once, and a refused request is never queued.
-
-### Ad-originated return
-
-This is the reason app-open belongs in the package rather than in your app.
-
-When a user dismisses a full-screen ad — or comes back from a browser an ad opened — your app sees an ordinary return to the foreground and has no way to tell it apart from any other. Showing an app-open there means an ad immediately after an ad. The package can tell, because it holds the lock and sees the clicks, so it refuses:
-
-```ts
-const result = await ads.show('cold_start');
-if (result.status === 'ad_originated_return') {
-  // Distinct from `busy` and `not_ready` on purpose: neither of those would
-  // have told you what actually happened, and both suggest a wrong remedy.
-}
-```
-
-**Three boundaries, which are limits rather than defects:**
-
-1. It cannot survive process death. If the OS kills your app while an ad is on screen, the return is a cold start and nothing links it to the ad.
-2. It depends on `setAppActive` being reported faithfully — an obligation `0.1.0` already imposes for staleness re-evaluation, so not a new one. `AdsProvider` does it for you unless you pass `trackAppState={false}`.
-3. A browser opened by an ad without a preceding click event is undetectable, because the click is the only signal the provider gives.
-
-### Validity window
-
-App-open expires after **30 minutes** by default, configurable from 1 minute to 1 hour via `appOpenValidityMs` — shorter than the hour the other full-screen formats get.
-
-Worth being explicit: Google expires app-open ads after **four hours**, which is *longer* than this package's general window. The shorter window is a product decision, not a provider limit. An app-open ad shows at the most prominent moment your app has, and a creative cached for an hour is stale by then; thirty minutes still spares a returning user the spinner of a cold load.
-
-### Store policy
-
-An app-open ad **must not block the user from entering your app, and must be dismissible.** The package enforces neither — presentation belongs to the provider — and a violation is the publishing app's responsibility. App-open is also the most visible placement a store reviewer will encounter, so reflect it in your review notes.
-
----
-
-## Why an ad did not show
-
-Three independent gates can be closed. When more than one is, the reported reason follows this precedence, **most immovable first**:
-
-| Priority | Gate | Reasons |
-|---|---|---|
-| 1 | Platform availability | `unsupported_platform`, `provider_missing` |
-| 2 | Enablement | `disabled`, `undecided` |
-| 3 | Consent | `consent_required`, `consent_undetermined`, `consent_flow_required`, `consent_flow_error` |
-
-Full table:
-
-| Availability | Enablement | Consent | Reported |
-|---|---|---|---|
-| ok | on | open | *(allowed)* |
-| ok | on | your gate closed | `consent_required` / `consent_undetermined` |
-| ok | on | flow not permitted | `consent_flow_required` |
-| ok | on | flow errored | `consent_flow_error` |
-| ok | `disabled` | any | `disabled` |
-| ok | `undecided` | any | `undecided` |
-| unavailable | any | any | `unsupported_platform` |
-| provider missing | any | any | `provider_missing` |
-
-Exactly one reason is reported — the most useful one for diagnosis, not the first one checked. An unsupported platform makes the other two unfixable, so telling you "consent required" there would send you off to build a flow that will never help.
-
-**Changed in `0.2.0`:** on an unavailable platform with ads also disabled, the reported reason is now `unsupported_platform` where `0.1.0` reported `disabled`. The old outcome depended on which condition arrived last. No request counts change.
-
----
-
-## Testing
-
-The whole suite runs with **no device, no network, and no ad inventory**.
-
-```ts
-import { createFakeAdsEngine } from '@chipmobilesdk/rn-ads/testing';
-
-const engine = createFakeAdsEngine();
-const ads = createAds(config, { engine, isDevBuild: true });
-
-await ads.initialize({ canRequestAds: true });
-await ads.load('level_break');
-
-expect(engine.adUnitIds()).toEqual([/* only official test units */]);
-```
-
-The fake records every call, lets you resolve or reject each load and show, and lets you emit provider callbacks in **any order** — which is how the reward-ordering and late-callback cases are tested.
-
-```
-engine.calls           every call the package made, in order
-engine.adUnitIds()     what actually reached the provider
-engine.liveHandles()   non-empty after dispose means a leak
-engine.emit(id, ev)    you control ordering
-engine.listenerCount() must reach zero after cleanup
-```
-
-On device, verify with Google's official test ads only. `npm run android`, then exercise each `Ads · …` screen in the demo app.
-
----
-
-## Release checklists
-
-### Before you ship
-
-- [ ] `npm run validate:ads` is green (lint, test, typecheck, pack dry-run)
-- [ ] `npm run android` and `npm run build:apk` both succeed
-- [ ] Merged manifest inspected; permissions match the table above and nothing else is new
-- [ ] Zero production ad requests observed from a `development` build — captured from logcat as release evidence
-- [ ] `environment: 'production'` is set only in release builds
-- [ ] No production ad unit, credential, or secret in this package
-
-### AdMob Console (cannot be done in code)
-
-- [ ] Android app registered under the correct package / application ID
-- [ ] A production ad unit created per placement, in the matching format
-- [ ] Account status and payment details verified
-- [ ] `app-ads.txt` published if you use it
-- [ ] Consent/privacy messaging configured if you use it
-- [ ] Content rating (`maxAdContentRating`) reviewed — ad content affects your app's age rating
-- [ ] Policy, traffic, and serving restrictions checked
-- [ ] **No self-clicking, ever**
-
-### Google Play Console
-
-- [ ] App declared as containing ads
-- [ ] **Data safety** updated: the Google Mobile Ads SDK collects the Advertising ID, coarse device and app information, and ad interaction signals on your behalf — this package collects and stores nothing of its own
-- [ ] Privacy policy covers advertising data
-- [ ] Target audience and content completed
-- [ ] Content rating questionnaire reflects ad content
-- [ ] Families requirements met if applicable — see below
-- [ ] Advertising ID declaration matches your target SDK and actual behavior
-- [ ] Regional consent requirements satisfied
-
-> **Children and families.** Ads plus advertising identifiers in an app that may reach children is a high-risk combination. This package supports `childDirected` and `underAgeOfConsent` as enforced pre-initialization inputs and documents the `AD_ID` removal path — but **it does not and cannot determine a user's age.** That determination, and the policy built on it, are yours.
-
----
-
-## Known limitations
-
-- **iOS is not implemented.** Importing and calling the package on iOS is safe and returns `unavailable` / `unsupported_platform`.
-- **Native and rewarded-interstitial ads are deferred.** Each has its own lifecycle, view construction, or presentation policy. They are additive later — a new `AdFormat` member, a factory branch in the engine adapter, and their own official test units. (App-open shipped in `0.2.0`.)
-- **Ad-originated return detection cannot survive process death**, and cannot see a browser an ad opened without a preceding click event. See [App open](#app-open).
-- **Mediation across multiple ad networks is out of scope.**
-- **Full-screen presentation, focus handling, and dismissal affordances are rendered by the provider** and outside this package's control. The package cannot make them accessible; it can only report what happened.
-- **`impression` for full-screen formats is derived**, not provider-reported. See the asymmetry note above.
-- **Bridge versions 16.1.0+ are unusable** under React Native 0.85. See [Compatibility](#compatibility).
-
-## Extending to iOS
-
-Adding iOS contributes exactly three things and changes **nothing** you have already written:
-
-1. **`PlacementDefinition.iosAdUnitId`** — the optional field already exists in v1's type, so existing Android-only catalogs stay valid.
-2. **A second engine adapter** behind the existing `AdsEngine` port. The port names no platform and no provider; that is what makes this additive.
-3. **iOS entries in the private test-ad-unit table.**
-
-Your `createAds`, `initialize`, `load`, `show`, `AdsBanner`, and every subscription keep their current signatures. The exported state, event, and error models do not change.
-
-Still to be done at that time, none of it touching the public contract: CocoaPods linking, the AdMob application ID in `Info.plist`, the SKAdNetwork identifiers Google requires, the privacy manifest, and App Store privacy labels.
-
-**Consent and App Tracking Transparency are two different things with a binding order.** ATT governs access to the device advertising identifier; the consent flow governs whether personalized ads may be requested at all. On iOS the ATT prompt must come first, and only then does the consent outcome mean what it means. The normalized `ConsentState` in `0.2.0` was shaped to express both mechanisms and their ordering **without changing shape** — an iOS adapter contributes a second `ConsentPort` implementation and nothing else. The tri-state enablement flag and the retry policy are entirely platform-neutral and carry no Android assumption.
-
-## Versioning
-
-Semantic versioning. The event catalog, error codes, state names, and result unions are public API. New formats, new platforms, and new optional configuration arrive as additive minor releases; renaming or removing any of the above is a major.
-
-### Migrating `0.1.0` to `0.2.0`
-
-**What you must do: one thing, and it is compile-time only.**
-
-If you have an exhaustive `switch` over any of these unions, add the new cases or a `default`:
-
-| Union | New members |
-|---|---|
-| `AdFormat` | `'app_open'` |
-| `InitStatus` | `'undecided'` |
-| `PlacementState` | `'undecided'` |
-| `PrivacyBlockReason` | `'consent_flow_required'`, `'consent_flow_error'` |
-| `AdsErrorCode` | `'undecided'`, `'ad_originated_return'`, `'consent_flow_required'`, `'consent_flow_failed'`, `'retry_out_of_bounds'` |
-
-There is no runtime equivalent. If you change nothing else you get identical behavior and an identical number of requests — proven by a test in this package, not merely promised.
-
-**What you may ignore, entirely:**
-
-- Consent — nothing starts unless you call `ads.consent.*`.
-- The `'undecided'` enablement state — `enabled: true` and `enabled: false` mean exactly what they meant.
-- App-open — a format you do not have to declare.
-- Retry — **off** unless you supply `retry`.
-
-**One behavior change requiring no action:** on an unavailable platform with ads also disabled, the reported reason is now `unsupported_platform` rather than `disabled`. The `0.1.0` outcome depended on which condition arrived last. Request counts are unchanged.
-
-**Worth adopting if it applies to you:** if you sell an ad-removal tier, `enabled: 'undecided'` and the typed `setEnabled` result together close a real defect — see [Turning ads off](#turning-ads-off--three-states).
+# @chipmobilesdk/rn-ads
+
+Reusable advertising capability for ChipMobileSdk-family React Native apps.
+
+The package owns **capability**: a safe, consistent, provider-neutral way to request and present ads. Your app owns **policy**: where ads appear, when, how often, to whom, under what consent, and whether they appear at all. There is no placement rule, no frequency cap, and no screen name in this package.
+
+**You never import the Google Mobile Ads SDK.** You name a placement key you chose, and the package does the rest.
+
+---
+
+## Scope
+
+| | 0.3.0 |
+|---|---|
+| **Platform** | Android only. iOS returns `unavailable` / `unsupported_platform` and never breaks a build. |
+| **Provider** | Google AdMob, via `react-native-google-mobile-ads` |
+| **Formats** | Anchored adaptive banner, interstitial, rewarded, app-open |
+| **Consent** | Optional orchestration of the provider's consent flow — you still import nothing of theirs |
+| **Account safety** | Non-production builds cannot reach a production ad unit; each placement has a request floor — see [Request throttling](#request-throttling) |
+| **Deferred** | Native, rewarded-interstitial, mediation, iOS — see [Known limitations](#known-limitations) |
+
+## Compatibility
+
+| | Supported |
+|---|---|
+| React | `>=19` (verified against 19.2.3) |
+| React Native | `>=0.85`, New Architecture (verified against 0.85.3) |
+| Node | `>=22.11.0` |
+| Android | `minSdk 24`, `compileSdk 36`, `targetSdk 36`, Kotlin 2.1.x |
+| Provider bridge | `react-native-google-mobile-ads` **`>=16.0.3 <16.1.0`** |
+| Google Mobile Ads Android SDK | 24.9.0 (transitive) |
+| Google UMP (consent) | 4.0.0 (transitive) |
+
+> **`0.2.0` required no bridge bump.** The pinned `16.0.3` already exposes everything the consent flow and the app-open format need — verified against the installed type declarations rather than assumed from documentation. The Kotlin constraint below is therefore untouched by this release.
+
+> **Why the bridge range is closed at the top.** Bridge 16.1.0+ moves to Google Mobile Ads 25.x, which is compiled with Kotlin 2.3.0 metadata. React Native 0.85.3 pins the Kotlin **compiler** at 2.1.x, and the build fails with `Module was compiled with an incompatible version of Kotlin`. Raising the root `ext.kotlinVersion` does not fix it — that moves only `kotlin-stdlib`, not the compiler. An open caret would let a routine `npm install` walk straight back into a build failure, so the range refuses rather than drifts. Revisit when React Native ships a Kotlin 2.3 compiler.
+
+---
+
+## Install
+
+```sh
+npm install @chipmobilesdk/rn-ads react-native-google-mobile-ads@16.0.3
+```
+
+### Required Android configuration
+
+Add your AdMob **application ID** to the app's `app.json`. The bridge's Gradle script reads this key and merges it into `AndroidManifest.xml`; without it the native SDK crashes on startup.
+
+```jsonc
+{
+  "react-native-google-mobile-ads": {
+    // Google's public test application ID. Replace with your own for release.
+    "android_app_id": "ca-app-pub-3940256099942544~3347511713"
+  }
+}
+```
+
+**The shared package carries no application ID and no ad unit ID.** Both are per-app configuration.
+
+### Permissions merged into your manifest
+
+Contributed by the provider, not requested by this package:
+
+Verified against a real merged manifest, not a list from documentation:
+
+| Permission | Source |
+|---|---|
+| `android.permission.INTERNET` | bridge manifest |
+| `android.permission.ACCESS_NETWORK_STATE` | bridge manifest |
+| `android.permission.WAKE_LOCK` | bridge manifest |
+| `com.google.android.gms.permission.AD_ID` | `play-services-ads-api` |
+| `android.permission.ACCESS_ADSERVICES_AD_ID` | `play-services-ads-api` |
+| `android.permission.ACCESS_ADSERVICES_ATTRIBUTION` | `play-services-ads-api` |
+| `android.permission.ACCESS_ADSERVICES_TOPICS` | `play-services-ads-api` |
+
+**Re-verified for `0.2.0`.** Adding the app-open format and activating the consent module contributed **no new permission** — both live in the already-pinned bridge, so the merged result is byte-identical to `0.1.0`'s.
+
+The last three are **Android Privacy Sandbox** permissions covering the Privacy Sandbox ad ID, attribution reporting, and the Topics API. They matter for your Data safety declaration and they are easy to miss, because they appear only in the merged result — no library README lists them.
+
+Verify the actual merged result before release — read the file, don't trust this table:
+
+```sh
+cd android && ./gradlew :app:assembleDebug
+# then inspect android/app/build/intermediates/merged_manifests/**/AndroidManifest.xml
+```
+
+**To remove advertising identifier access** (required for child-directed apps under Play Families policy).
+
+Removing `AD_ID` alone is **not enough** — verified by rebuild, the three Privacy Sandbox permissions survive it and must be removed explicitly:
+
+```xml
+<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />
+<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" tools:node="remove" />
+<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" tools:node="remove" />
+<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" tools:node="remove" />
+```
+
+Your `<manifest>` tag needs `xmlns:tools="http://schemas.android.com/tools"`. Rebuild and re-inspect the merged manifest to confirm — do not assume.
+
+---
+
+## Configure
+
+Placement keys are **yours**. Provider ad unit IDs appear here in configuration and nowhere else in your code.
+
+```ts
+import { createAds } from '@chipmobilesdk/rn-ads';
+
+const ads = createAds({
+  enabled: true,                 // your feature flag; false makes everything a safe no-op
+  environment: 'development',    // 'development' | 'test' | 'production'
+  placements: [
+    { key: 'home_footer',       format: 'banner',       androidAdUnitId: 'ca-app-pub-…/…' },
+    { key: 'level_break',       format: 'interstitial', androidAdUnitId: 'ca-app-pub-…/…' },
+    { key: 'completion_reward', format: 'rewarded',     androidAdUnitId: 'ca-app-pub-…/…' },
+  ],
+});
+```
+
+`createAds` **throws** on a malformed catalog — duplicate key, missing ad unit, unknown format, out-of-band timeout — naming the offending placement. Every other failure in the package is a typed result, never a throw.
+
+Reading configuration requires no dotenv library, no remote-config service, and no feature-flag system. Supply the values however you like.
+
+### How production traffic is made impossible
+
+In `development` and `test`, any ad unit that is not one of Google's official test units is **replaced** with one, and the substitution is reported — as a `config_warning` event naming every affected placement, and in observable state via `ads.getSubstitutedPlacements()`.
+
+```
+environment: development
+  home_footer -> ca-app-pub-REAL…/1234567890
+
+  ⚠ config_warning: test_ad_unit_substituted
+      placementKeys: ['home_footer']
+  → request sent with ca-app-pub-3940256099942544/9214589741
+  → your app keeps working
+```
+
+In `production`, nothing is substituted — your units are used exactly as configured.
+
+The one case substitution cannot cover is a **debug build declaring `production`**: that would send real requests from a build that should never generate traffic. It fails closed with `production_in_dev_build`.
+
+> Invalid traffic from non-production builds can get an AdMob account suspended. **Never click a production ad to verify anything.**
+
+---
+
+## Initialize — consent comes first
+
+The package will not initialize anything request-capable until your privacy gate permits it. This is enforced, not documented: with the gate withheld, **zero** provider calls occur.
+
+```tsx
+import { AdsProvider } from '@chipmobilesdk/rn-ads';
+
+await ads.initialize({
+  canRequestAds: true,        // your consent decision — the package renders no consent UI
+  consentUndetermined: false, // true means "not asked yet", distinct from "refused"
+  childDirected: false,
+  underAgeOfConsent: false,
+  maxAdContentRating: 'G',
+  personalizedAds: true,
+});
+
+<AdsProvider instance={ads}>{children}</AdsProvider>
+```
+
+**Ordering matters.** `childDirected`, `underAgeOfConsent`, and `maxAdContentRating` only take effect if they reach the provider *before* it initializes. Change one afterwards and `updatePrivacy` returns `requires_reinitialization` rather than pretending it applied.
+
+Resolving consent after being blocked is the normal path and creates **no** duplicate initialization:
+
+```ts
+await ads.initialize({ canRequestAds: false });   // → { status: 'blocked', reason: 'consent_required' }
+await ads.updatePrivacy({ canRequestAds: true }); // → { status: 'applied' }, one native init total
+```
+
+The package logs no personal data, no consent payload, and no advertising identifier.
+
+---
+
+## Banner
+
+You place it. It sizes itself to your container and re-adapts on rotation.
+
+```tsx
+import { AdsBanner, usePlacementState } from '@chipmobilesdk/rn-ads';
+
+function Footer() {
+  const state = usePlacementState('home_footer');
+  const reserve = state === 'loading' || state === 'ready';
+
+  return reserve ? (
+    <View style={styles.slot}>
+      {state === 'loading' ? <YourThemedPlaceholder /> : null}
+      <AdsBanner placementKey="home_footer" />
+    </View>
+  ) : null; // your decision to reclaim the space
+}
+```
+
+The component **ships no placeholder** — that is yours, so it matches your theme. When ads are disabled or unavailable it renders `null`, not an empty view, so it leaves the accessibility tree entirely rather than taking screen-reader focus ahead of your content.
+
+## Interstitial and rewarded
+
+Load ahead of time; show only when *you* decide.
+
+```ts
+await ads.load('level_break');
+const result = await ads.show('level_break');
+
+switch (result.status) {
+  case 'shown':        break;
+  case 'not_ready':    break; // no UI opened, nothing crashed
+  case 'busy':         break; // another full-screen ad is up — never queued
+  case 'consumed':     break; // load a fresh one first
+  case 'app_inactive': break; // backgrounded
+  case 'blocked':      break; // result.reason
+  case 'disabled':     break;
+  case 'unavailable':  break; // result.reason
+  case 'timeout':      break;
+  case 'failed':       break; // result.error
+}
+```
+
+Rewards are reported **only** when the provider confirms them:
+
+```ts
+ads.subscribeEvents(event => {
+  if (event.type === 'reward_earned') {
+    grant(event.reward.type, event.reward.amount); // your grant, not the package's
+  }
+  if (event.type === 'dismissed' && event.rewardEarned === false) {
+    // closed early — no reward, and none inferred
+  }
+});
+```
+
+`reward_earned` and `dismissed` may arrive from the provider in either order; the outcome is identical, and a duplicate confirmation is collapsed into one event. **The package grants nothing** — validating and delivering the benefit is yours.
+
+---
+
+## State, events, and errors
+
+**Initialization status**: `not_started` · `blocked` · `initializing` · `ready` · `disabled` · `unavailable` · `failed`
+
+**Placement state**: `idle` · `loading` · `ready` · `showing` · `consumed` · `failed` · `unavailable`
+
+**Events** carry the placement key, format, timestamp, and a `correlationId` tying one load/show cycle together — enough to reconstruct an ad's whole life from the stream alone. They carry no provider object, no advertising identifier, and no consent payload.
+
+`initialization` · `load_started` · `loaded` · `load_failed` · `display_started` · `impression` · `click` · `display_failed` · `dismissed` · `reward_earned` · `disabled` · `unavailable` · `config_warning` · `internal_error`
+
+> **One honest asymmetry.** `impression` carries `source: 'provider' | 'derived'`. Banners get a real provider impression callback. Full-screen formats have none in the provider's event enum, so theirs is derived from the ad opening. If you reconcile these events against AdMob revenue reporting, you need to know which is which.
+
+**Ordering and exactly-once** are documented and tested. Within one `correlationId`, `loaded` / `display_started` / `impression` / `dismissed` / `reward_earned` occur at most once; `click` may repeat. After `dispose()`, zero events are emitted — a late provider callback is dropped.
+
+**Errors** carry a stable `code`, a log-safe `message`, the `operation`, a `retryable` flag, and a redacted `cause`. Codes are public API; renaming one is a breaking change.
+
+Retryable: `no_fill` `network_error` `load_timeout` `show_timeout` `ad_expired` `not_ready` `busy` `consumed` `app_inactive` `provider_error`
+Not retryable: `invalid_config` `duplicate_placement_key` `missing_ad_unit_id` `format_mismatch` `placement_not_found` `production_in_dev_build` `timeout_out_of_bounds` `unsupported_platform` `provider_missing` `disabled` `consent_required` `consent_undetermined` `requires_reinitialization` `internal_error`
+
+Attach any logger or analytics you already use. The package depends on none:
+
+```ts
+const unsubscribe = ads.subscribeEvents(event => yourLogger.track(event.type, event));
+```
+
+A listener that throws is caught and reported once; it cannot break the state machine or starve other listeners.
+
+### Timeouts and cleanup
+
+| | Default | Configurable range |
+|---|---|---|
+| Load timeout | 30 000 ms | 5 000 – 120 000 |
+| Show timeout | 10 000 ms | 5 000 – 30 000 |
+| Loaded-ad validity | 3 600 000 ms | 60 000 – 3 600 000 |
+| App-open validity | 1 800 000 ms | 60 000 – 3 600 000 |
+| Undecided warning | 10 000 ms | 1 000 – 120 000 |
+
+Out-of-band values are a configuration error, not silently clamped. A loaded full-screen ad older than its validity window stops reporting `ready` and requires a reload — so you never render a button for an ad that will fail on tap.
+
+`dispose()` cancels every timer and subscription and releases every handle — including a consent flow in progress, a pending retry, and the undecided-state warning. It is idempotent, and so is every `Unsubscribe`.
+
+---
+
+## Retry
+
+**Off by default.** Upgrading from `0.1.0` without configuring `retry` sends exactly the requests it always did.
+
+```ts
+createAds({
+  // ...
+  retry: { maxRetries: 2, initialDelayMs: 2_000, maxDelayMs: 30_000 },
+  placements: [
+    { key: 'home_footer', format: 'banner', androidAdUnitId: '...' },
+    // Off for this placement only: a rewarded retry happens with a user
+    // waiting on the other side of it.
+    { key: 'bonus', format: 'rewarded', androidAdUnitId: '...', retry: false },
+  ],
+});
+```
+
+| | Default | Range |
+|---|---|---|
+| `maxRetries` (attempts after the first) | 2 | 1 – 5 |
+| `initialDelayMs` | 2 000 | 500 – 30 000 |
+| `maxDelayMs` | 30 000 | 1 000 – 60 000 |
+
+Backoff is exponential with a fixed x2 multiplier and no jitter — a single device has no fleet to desynchronize, and determinism makes the attempt count exactly assertable.
+
+**Only `retryable` errors are retried.** Configuration errors, consent errors, an unsupported platform, and a disabled or undecided instance never are: another attempt cannot change any of them, so retrying would spend a billable request on a certainty.
+
+A per-placement `retry` **replaces** the instance-wide policy rather than merging into it, so the effective policy for a placement is readable from the configuration without simulating a merge. Both are held to the same bounds, so an override can narrow behavior but never exceed a ceiling. Out-of-range values throw at construction — you find out when you build the instance, not on the first failed load in production.
+
+Disabling ads, moving to `undecided`, losing consent, or `dispose()` cancels **every** pending retry across every placement immediately.
+
+### Reconciling retries against a bill
+
+Each attempt emits a `retry_scheduled` event carrying the **same `correlationId`** as the load cycle that triggered it:
+
+```ts
+ads.subscribeEvents(event => {
+  if (event.type === 'retry_scheduled') {
+    analytics.track('ad_retry', {
+      placement: event.placementKey,
+      attempt: event.attempt,
+      delayMs: event.delayMs,
+      reason: event.error.code,
+      cycle: event.correlationId,
+    });
+  }
+});
+```
+
+Counting `load_started` plus `retry_scheduled` for a placement gives the number of requests that placement actually cost you. You keep the option of ignoring all of this and writing your own retry — enabling the package's is a choice, not a replacement.
+
+---
+
+## Request throttling
+
+**New in 0.3.0.** Each placement has a minimum interval between provider *requests*.
+
+### The problem it solves
+
+A banner mounted inside a view the user navigates between — a day in a calendar, a tab, a row that scrolls in and out of a list — is unmounted and remounted by React on every navigation. **Each remount is a billable request.** A user swiping quickly through ten days produces ten requests in a few seconds, and nothing about that is you doing something wrong.
+
+Ad networks read that pattern as invalid traffic. The penalty is account-level and shipping a fix does not recover it, which is why this is enforced by the package rather than left as advice.
+
+Full-screen formats do not have the problem: they are loaded by an explicit call, not mounted by a renderer. That asymmetry is why the defaults differ.
+
+### Defaults
+
+| Format | Default floor | Why |
+|---|---|---|
+| `banner` | **60 000 ms** | AdMob's own documented floor for banner auto-refresh. Asking more often than that is, by the provider's own standard, more often than it considers reasonable. |
+| `interstitial`, `rewarded`, `app_open` | **0** (off) | `load` → `show` → `load` is the healthy cycle. An app that legitimately sells three things in two minutes loads three times, and a default floor would break correct apps to solve a problem these formats do not have. |
+
+Override per placement:
+
+```ts
+placements: [
+  {
+    key: 'timeline_row',
+    format: 'banner',
+    androidAdUnitId: 'ca-app-pub-…/…',
+    minRequestIntervalMs: 30_000, // lower the floor knowingly
+  },
+  {
+    key: 'after_save',
+    format: 'interstitial',
+    androidAdUnitId: 'ca-app-pub-…/…',
+    minRequestIntervalMs: 20_000, // add a floor where there is none by default
+  },
+]
+```
+
+Bounds are `0`–`600 000` ms, and an out-of-range value throws `AdsConfigError` at `createAds` — naming the placement — rather than refusing every request later in production.
+
+### What a refusal looks like
+
+```ts
+const result = await ads.load('after_save');
+if (result.status === 'throttled') {
+  // Nothing was requested. Nothing is wrong.
+  console.log(`asked too recently; retry in ${result.retryAfterMs}ms`);
+}
+```
+
+- The placement reports `'throttled'` — **not** `'failed'`, and **not** a no-fill. No-fill means the network had nothing to give; this means we did not ask. An app that conflates them will misdiagnose the first time a placement goes quiet.
+- A `request_throttled` event carries `retryAfterMs` and the `minRequestIntervalMs` that refused it, so the cause is readable from your logs alone.
+- No `load_started` is emitted. A refused request is not a cycle, and the event stream must not claim a billable request that never happened.
+
+### Two exemptions, both deliberate
+
+**Rotation is not charged.** A width re-adaptation inside one mount — the device rotated, the container resized — is the same banner the placement already legitimately requested. Refusing it would leave a rotated screen with no banner for up to a minute, which this was never meant to cost. The slot is charged once per *mount*, not per request.
+
+**A concurrent duplicate load is not charged.** Two callers arriving for one cycle already join the in-flight request; charging the second would turn an existing guarantee into a refusal.
+
+### The better fix is architectural
+
+> Keep the banner **outside** the subtree that remounts and the throttle never fires. A banner pinned above or below a swipeable area stays mounted across navigation, keeps its ad, and costs one request.
+>
+> This throttle is a safety net for when that is not possible — a banner genuinely inside a list, for instance. It is not a licence to ignore the placement problem, and reaching for `minRequestIntervalMs: 0` to silence a `throttled` state puts your ad account back where it was.
+
+### This is not a frequency cap
+
+It limits how often a placement may **ask** for an ad. It says nothing about how often you may **show** one, and the package deliberately ships no pacing mechanism at all.
+
+Pacing is a product decision with no correct default: one app counts items created, another counts screens opened, another counts minutes elapsed. Shipping one here would make the package own policy that belongs to you. If you want "an interstitial every third save", count the saves in your app and call `show` when your rule says so.
+
+---
+
+## Turning ads off — three states
+
+`enabled` accepts `true`, `false`, or `'undecided'`.
+
+| State | Requests sent | Init status | Banner reports | When to use it |
+|---|---|---|---|---|
+| `true` | yes | normal | normal | Ads are on |
+| `false` | **zero** | `disabled` | `unavailable` | A settled no |
+| `'undecided'` | **zero** | `undecided` | `undecided` | You do not know yet |
+
+### Why the third state exists
+
+If you sell an ad-removal tier, at cold start you do not yet know whether this user has paid — that answer arrives after a store sync. Both of the other options are wrong: `true` flashes an ad at someone who paid not to see one, and `false` delays ads for every free user and drops you into the re-enable path below.
+
+`undecided` sends nothing, exactly like `disabled`, but reports itself **distinctly** so your banner host can hold the space rather than reclaim it:
+
+```tsx
+<AdsBanner placementKey="home_footer" onStateChange={setState} />
+{state === 'undecided' ? <YourThemedPlaceholder /> : null}
+```
+
+Resolve it exactly once when you know:
+
+```ts
+const result = ads.setEnablement(userOwnsAdRemoval ? 'disabled' : 'enabled');
+```
+
+The package **never resolves it for you** — that would mean guessing at a business decision it is forbidden to know about. If you leave it unresolved past `undecidedWarningMs` you get one `config_warning` (`enablement_undecided_timeout`) and nothing else. One, not a repeating stream: a warning that fires every ten seconds becomes noise that gets filtered.
+
+### Re-enabling
+
+**This changed in `0.2.0`, and the old behavior was a defect.** In `0.1.0`, `setEnabled(true)` after a disable dropped the init status to `not_started`, so every later `load` and `show` was refused — and `setEnabled` returned `void`, so nothing told you. An app whose user's subscription lapsed would turn ads back on and silently show none.
+
+Now the result is typed and always says what happened:
+
+```ts
+const result = ads.setEnabled(true);
+
+switch (result.status) {
+  case 'resumed':
+    // The provider was never un-initialized. Nothing to do — load away.
+    break;
+  case 'requires_initialization':
+    // Never reached ready, privacy changed, or the platform went away.
+    await ads.initialize(privacy);
+    break;
+  default:
+    break;
+}
+```
+
+The package does **not** initialize implicitly on your behalf: that would hide an asynchronous, billable operation behind a setter you may not be awaiting, and a failure would surface with no call site to attribute it to.
+
+If your privacy options have not changed you do not supply them again. They live in memory for the lifetime of the instance and are never persisted.
+
+In every off state — `false` or `'undecided'` — in-flight loads are released deterministically, and an ad **already on screen is not force-closed**: the provider offers no safe way to do so, and yanking a full-screen ad out from under the user would be worse than letting it finish.
+
+### Wiring it to an external decision
+
+The package has no idea what an entitlement is. That is deliberate — it receives a decision, never a reason:
+
+```ts
+const ads = createAds({ enabled: 'undecided', /* ... */ });
+
+// Whatever answers this for you: a billing library, your own backend, a cached
+// receipt. The package neither knows nor stores which.
+entitlements.subscribe(owned => {
+  ads.setEnablement(owned ? 'disabled' : 'enabled');
+});
+```
+
+---
+
+## Consent
+
+**Optional.** If you already supply your own gate through `PrivacyOptions.canRequestAds`, nothing here starts on your behalf and your `0.1.0` integration is untouched.
+
+Use it when you ship to a region that requires consent. Before `0.2.0` that meant importing the provider's consent SDK directly — which broke the one promise this package exists to keep — and hand-writing the same order-sensitive orchestration every other such app was also writing.
+
+```ts
+// Nothing here imports the ad provider.
+const info = await ads.consent.requestInfoUpdate();
+
+if (info.state === 'required') {
+  await ads.consent.showFormIfRequired();  // the provider draws the form
+}
+
+// The outcome feeds the privacy gate by itself. No wiring, and no second
+// native initialization.
+await ads.load('level_break');
+```
+
+### Normalized consent states
+
+| State | Meaning | `canRequestAds` | Your next step |
+|---|---|---|---|
+| `undetermined` | Not asked yet. Initial value, and the value after a reset. | `false` | `requestInfoUpdate()` |
+| `not_required` | The provider says this region does not require consent. | `true` | Nothing — ads proceed |
+| `required` | Required and not yet obtained. | `false` | `showFormIfRequired()` |
+| `obtained` | Obtained. | `true` | Nothing — ads proceed |
+| `error` | The flow failed. | **always `false`** | Optionally retry the flow |
+
+Three rules the package will not bend:
+
+- **A failure is never consent.** A provider error, a network failure, a cancellation, and a form dismissed without an answer all produce `error`, and `error` never carries permission. The failure this prevents is invisible in production: a request that should not have happened looks exactly like one that should.
+- **The package does not decide which regions require consent.** `not_required` is the provider's answer forwarded, not this package's judgement.
+- **A consent failure never crashes your app or blocks startup.** It is a normalized error you can act on or ignore.
+
+The package renders **no consent UI**. The form is the provider's. Timing, surrounding copy, and the experience when a user later changes their mind stay yours — as does deciding whether to run the flow at all. A user declining is a normal path, not an error.
+
+### Package flow or your own gate?
+
+| | Package flow | Your own gate |
+|---|---|---|
+| You call | `ads.consent.*` | `initialize({ canRequestAds })` |
+| Form drawn by | the provider | you, or a third-party CMP |
+| Good when | you use the provider's consent messages | you already run a consent platform |
+
+You can do both. They combine as **most-restrictive-wins**: requesting is permitted only when both permit it, and either alone can block. So if you obtained consent but independently blocked ads for a reason of your own, your block survives — the package is forbidden to know your reason and therefore must never overrule it. The reported reason names which input is blocking.
+
+### Testing the flow from outside the region
+
+```ts
+createAds({
+  environment: 'development',
+  consentTesting: { debugGeography: 'eea', resetOnStart: true },
+  // ...
+});
+```
+
+**Both tools are stripped in `production`.** Not checked at each call site — removed at configuration validation, so no code path can forget. The fact that they were ignored is observable, not merely documented: a `config_warning` (`consent_tool_ignored_in_production`) naming each one, and `getIgnoredConsentTools()` on the instance.
+
+### What gets stored on the device
+
+The consent platform persists the user's decision on the device under IAB TCF keys. This package neither reads, logs, nor includes it in any event — but **your Google Play Data safety declaration depends on it**, so review that before shipping the consent flow.
+
+---
+
+## App open
+
+A fourth format, declared in the catalog exactly like the other three and using the same placement states, events, and error codes.
+
+```ts
+{ key: 'cold_start', format: 'app_open', androidAdUnitId: 'ca-app-pub-.../...' }
+```
+
+```ts
+await ads.load('cold_start');
+const result = await ads.show('cold_start');  // you decide when
+```
+
+**The package never shows one on its own.** As with interstitial and rewarded, every show is an explicit call you make.
+
+It shares the **same single full-screen lock** as interstitial and rewarded, so two full-screen ads are never open at once, and a refused request is never queued.
+
+### Ad-originated return
+
+This is the reason app-open belongs in the package rather than in your app.
+
+When a user dismisses a full-screen ad — or comes back from a browser an ad opened — your app sees an ordinary return to the foreground and has no way to tell it apart from any other. Showing an app-open there means an ad immediately after an ad. The package can tell, because it holds the lock and sees the clicks, so it refuses:
+
+```ts
+const result = await ads.show('cold_start');
+if (result.status === 'ad_originated_return') {
+  // Distinct from `busy` and `not_ready` on purpose: neither of those would
+  // have told you what actually happened, and both suggest a wrong remedy.
+}
+```
+
+**Three boundaries, which are limits rather than defects:**
+
+1. It cannot survive process death. If the OS kills your app while an ad is on screen, the return is a cold start and nothing links it to the ad.
+2. It depends on `setAppActive` being reported faithfully — an obligation `0.1.0` already imposes for staleness re-evaluation, so not a new one. `AdsProvider` does it for you unless you pass `trackAppState={false}`.
+3. A browser opened by an ad without a preceding click event is undetectable, because the click is the only signal the provider gives.
+
+### Validity window
+
+App-open expires after **30 minutes** by default, configurable from 1 minute to 1 hour via `appOpenValidityMs` — shorter than the hour the other full-screen formats get.
+
+Worth being explicit: Google expires app-open ads after **four hours**, which is *longer* than this package's general window. The shorter window is a product decision, not a provider limit. An app-open ad shows at the most prominent moment your app has, and a creative cached for an hour is stale by then; thirty minutes still spares a returning user the spinner of a cold load.
+
+### Store policy
+
+An app-open ad **must not block the user from entering your app, and must be dismissible.** The package enforces neither — presentation belongs to the provider — and a violation is the publishing app's responsibility. App-open is also the most visible placement a store reviewer will encounter, so reflect it in your review notes.
+
+---
+
+## Why an ad did not show
+
+Three independent gates can be closed. When more than one is, the reported reason follows this precedence, **most immovable first**:
+
+| Priority | Gate | Reasons |
+|---|---|---|
+| 1 | Platform availability | `unsupported_platform`, `provider_missing` |
+| 2 | Enablement | `disabled`, `undecided` |
+| 3 | Consent | `consent_required`, `consent_undetermined`, `consent_flow_required`, `consent_flow_error` |
+
+Full table:
+
+| Availability | Enablement | Consent | Reported |
+|---|---|---|---|
+| ok | on | open | *(allowed)* |
+| ok | on | your gate closed | `consent_required` / `consent_undetermined` |
+| ok | on | flow not permitted | `consent_flow_required` |
+| ok | on | flow errored | `consent_flow_error` |
+| ok | `disabled` | any | `disabled` |
+| ok | `undecided` | any | `undecided` |
+| unavailable | any | any | `unsupported_platform` |
+| provider missing | any | any | `provider_missing` |
+
+Exactly one reason is reported — the most useful one for diagnosis, not the first one checked. An unsupported platform makes the other two unfixable, so telling you "consent required" there would send you off to build a flow that will never help.
+
+**A fourth reason, outside the gates: `throttled`.** The gates above all mean "you may not ask". Throttling means "you may, but not yet" — the placement asked too recently (see [Request throttling](#request-throttling)). It is checked after the gates, because a closed gate is the more useful thing to report, and it carries `retryAfterMs` where a gate carries a reason.
+
+| Symptom | Likely cause |
+|---|---|
+| Placement sits at `throttled` after a navigation | A banner inside a remounting subtree, hitting the 60s floor |
+| Placement sits at `undecided` forever | Enablement never resolved from `'undecided'` |
+| Placement sits at `idle`, banner never appears | `AdsBanner` gated on its own state, or a zero-width container |
+| `load` returns `blocked` | Consent gate closed |
+
+**Changed in `0.2.0`:** on an unavailable platform with ads also disabled, the reported reason is now `unsupported_platform` where `0.1.0` reported `disabled`. The old outcome depended on which condition arrived last. No request counts change.
+
+---
+
+## Testing
+
+The whole suite runs with **no device, no network, and no ad inventory**.
+
+```ts
+import { createFakeAdsEngine } from '@chipmobilesdk/rn-ads/testing';
+
+const engine = createFakeAdsEngine();
+const ads = createAds(config, { engine, isDevBuild: true });
+
+await ads.initialize({ canRequestAds: true });
+await ads.load('level_break');
+
+expect(engine.adUnitIds()).toEqual([/* only official test units */]);
+```
+
+The fake records every call, lets you resolve or reject each load and show, and lets you emit provider callbacks in **any order** — which is how the reward-ordering and late-callback cases are tested.
+
+```
+engine.calls           every call the package made, in order
+engine.adUnitIds()     what actually reached the provider
+engine.liveHandles()   non-empty after dispose means a leak
+engine.emit(id, ev)    you control ordering
+engine.listenerCount() must reach zero after cleanup
+```
+
+On device, verify with Google's official test ads only. `npm run android`, then exercise each `Ads · …` screen in the demo app.
+
+---
+
+## Release checklists
+
+### Before you ship
+
+- [ ] `npm run validate:ads` is green (lint, test, typecheck, pack dry-run)
+- [ ] `npm run android` and `npm run build:apk` both succeed
+- [ ] Merged manifest inspected; permissions match the table above and nothing else is new
+- [ ] Zero production ad requests observed from a `development` build — captured from logcat as release evidence
+- [ ] `environment: 'production'` is set only in release builds
+- [ ] No production ad unit, credential, or secret in this package
+
+### AdMob Console (cannot be done in code)
+
+- [ ] Android app registered under the correct package / application ID
+- [ ] A production ad unit created per placement, in the matching format
+- [ ] Account status and payment details verified
+- [ ] `app-ads.txt` published if you use it
+- [ ] Consent/privacy messaging configured if you use it
+- [ ] Content rating (`maxAdContentRating`) reviewed — ad content affects your app's age rating
+- [ ] Policy, traffic, and serving restrictions checked
+- [ ] **No self-clicking, ever**
+
+### Google Play Console
+
+- [ ] App declared as containing ads
+- [ ] **Data safety** updated: the Google Mobile Ads SDK collects the Advertising ID, coarse device and app information, and ad interaction signals on your behalf — this package collects and stores nothing of its own
+- [ ] Privacy policy covers advertising data
+- [ ] Target audience and content completed
+- [ ] Content rating questionnaire reflects ad content
+- [ ] Families requirements met if applicable — see below
+- [ ] Advertising ID declaration matches your target SDK and actual behavior
+- [ ] Regional consent requirements satisfied
+
+> **Children and families.** Ads plus advertising identifiers in an app that may reach children is a high-risk combination. This package supports `childDirected` and `underAgeOfConsent` as enforced pre-initialization inputs and documents the `AD_ID` removal path — but **it does not and cannot determine a user's age.** That determination, and the policy built on it, are yours.
+
+---
+
+## Known limitations
+
+- **iOS is not implemented.** Importing and calling the package on iOS is safe and returns `unavailable` / `unsupported_platform`.
+- **Native and rewarded-interstitial ads are deferred.** Each has its own lifecycle, view construction, or presentation policy. They are additive later — a new `AdFormat` member, a factory branch in the engine adapter, and their own official test units. (App-open shipped in `0.2.0`.)
+- **Ad-originated return detection cannot survive process death**, and cannot see a browser an ad opened without a preceding click event. See [App open](#app-open).
+- **Mediation across multiple ad networks is out of scope.**
+- **Full-screen presentation, focus handling, and dismissal affordances are rendered by the provider** and outside this package's control. The package cannot make them accessible; it can only report what happened.
+- **`impression` for full-screen formats is derived**, not provider-reported. See the asymmetry note above.
+- **Bridge versions 16.1.0+ are unusable** under React Native 0.85. See [Compatibility](#compatibility).
+
+## Extending to iOS
+
+Adding iOS contributes exactly three things and changes **nothing** you have already written:
+
+1. **`PlacementDefinition.iosAdUnitId`** — the optional field already exists in v1's type, so existing Android-only catalogs stay valid.
+2. **A second engine adapter** behind the existing `AdsEngine` port. The port names no platform and no provider; that is what makes this additive.
+3. **iOS entries in the private test-ad-unit table.**
+
+Your `createAds`, `initialize`, `load`, `show`, `AdsBanner`, and every subscription keep their current signatures. The exported state, event, and error models do not change.
+
+Still to be done at that time, none of it touching the public contract: CocoaPods linking, the AdMob application ID in `Info.plist`, the SKAdNetwork identifiers Google requires, the privacy manifest, and App Store privacy labels.
+
+**Consent and App Tracking Transparency are two different things with a binding order.** ATT governs access to the device advertising identifier; the consent flow governs whether personalized ads may be requested at all. On iOS the ATT prompt must come first, and only then does the consent outcome mean what it means. The normalized `ConsentState` in `0.2.0` was shaped to express both mechanisms and their ordering **without changing shape** — an iOS adapter contributes a second `ConsentPort` implementation and nothing else. The tri-state enablement flag and the retry policy are entirely platform-neutral and carry no Android assumption.
+
+## Versioning
+
+Semantic versioning. The event catalog, error codes, state names, and result unions are public API. New formats, new platforms, and new optional configuration arrive as additive minor releases; renaming or removing any of the above is a major.
+
+### Migrating `0.2.x` to `0.3.0`
+
+**One compile-time change.** If you have an exhaustive `switch` over any of these, add the new case or a `default`:
+
+| Union | New member |
+|---|---|
+| `PlacementState` | `'throttled'` |
+| `LoadResult` | `{ status: 'throttled', retryAfterMs }` |
+| `AdEventType` | `'request_throttled'` |
+
+**One behaviour change, and it is the point of the release.** Banner placements now have a 60s floor between requests ([Request throttling](#request-throttling)). A banner inside a list row, a tab, or a view the user swipes between will report `'throttled'` after a quick navigation where `0.2.x` silently issued another request — the silent request being the defect this fixes.
+
+Full-screen formats are unchanged: their default floor is `0`, so request counts for `interstitial`, `rewarded` and `app_open` are identical to `0.2.x` unless you configure a floor.
+
+**What has not changed:** no frequency cap was added, and none is planned. Pacing stays entirely yours.
+
+### Migrating `0.1.0` to `0.2.0`
+
+**What you must do: one thing, and it is compile-time only.**
+
+If you have an exhaustive `switch` over any of these unions, add the new cases or a `default`:
+
+| Union | New members |
+|---|---|
+| `AdFormat` | `'app_open'` |
+| `InitStatus` | `'undecided'` |
+| `PlacementState` | `'undecided'` |
+| `PrivacyBlockReason` | `'consent_flow_required'`, `'consent_flow_error'` |
+| `AdsErrorCode` | `'undecided'`, `'ad_originated_return'`, `'consent_flow_required'`, `'consent_flow_failed'`, `'retry_out_of_bounds'` |
+
+There is no runtime equivalent. If you change nothing else you get identical behavior and an identical number of requests — proven by a test in this package, not merely promised.
+
+**What you may ignore, entirely:**
+
+- Consent — nothing starts unless you call `ads.consent.*`.
+- The `'undecided'` enablement state — `enabled: true` and `enabled: false` mean exactly what they meant.
+- App-open — a format you do not have to declare.
+- Retry — **off** unless you supply `retry`.
+
+**One behavior change requiring no action:** on an unavailable platform with ads also disabled, the reported reason is now `unsupported_platform` rather than `disabled`. The `0.1.0` outcome depended on which condition arrived last. Request counts are unchanged.
+
+**Worth adopting if it applies to you:** if you sell an ad-removal tier, `enabled: 'undecided'` and the typed `setEnabled` result together close a real defect — see [Turning ads off](#turning-ads-off--three-states).