@chipmobilesdk/rn-ads 0.4.0 → 0.5.0

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

@@ -1,274 +1,274 @@
----
-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 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.4.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-ads
-
-Adaptive banner, interstitial, rewarded and app-open ads on Android via Google AdMob,
-behind a contract that names no provider. The app names a placement key; the package owns
-the request. Consuming code never imports the Google Mobile Ads SDK — including for
-consent.
-
-## Use this when
-
-- 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
-- Debugging an ad that never loads, or a `blocked` / `undecided` / `unavailable` /
-  `ad_originated_return` / `provider_error`
-- Answering a Data safety / App Privacy question about advertising
-
-## Do not use this for
-
-- **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 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.
-- **Anything about payments** — the undecided state exists *because* apps sell ad removal,
-  but the package receives a decision and never a reason, receipt or entitlement.
-- iOS — not implemented; every call returns `unavailable` / `unsupported_platform`.
-
-## Nothing loads until consent and initialization complete
-
-This is enforced, and it is the answer to almost every "the ad never appears". With the
-gate withheld, **zero** provider calls occur — not even configuration. `childDirected`,
-`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:
-**platform availability → enablement → consent**, most immovable first. So
-`unsupported_platform` on a disabled instance is reported as `unsupported_platform` —
-turning ads on would not have helped. Full table in `## Why an ad did not show`.
-
-## Never gate `<AdsBanner>` on its own placement state
-
-`AdsBanner` is what measures the container and starts the load, so it must be mounted
-unconditionally. Rendering it only when the state is `loading`/`ready` deadlocks at
-`idle` and no ad ever appears. Use the state for the *surrounding* placeholder and to
-decide whether to hold or reclaim space — never to decide whether to mount the host. It
-renders `null` on its own when there is nothing to show.
-
-## `undecided` is not `disabled`, and that is the whole point
-
-`enabled` takes `true`, `false` or `'undecided'`. All three send zero requests except
-`true`. `'undecided'` reports itself distinctly — in `getStatus()` and in the banner's
-placement state — so an app that has not yet heard back from the store can **hold** the
-banner's space instead of reclaiming it, and a paying user never sees an ad flash in and
-out. `disabled` means a settled no; reclaim the space.
-
-The package never resolves it for you. Leave it unresolved past `undecidedWarningMs`
-(default 10s) and you get exactly one `config_warning`, never a stream.
-
-## `setEnabled` returns a result — read it
-
-In 0.1.0 it returned `void` and re-enabling after a disable silently dropped the init
-status, so every later `load` and `show` was refused with nothing to say so. That was a
-defect and it is fixed. The result now says which happened:
-
-- `resumed` — the provider was never un-initialized; load away, zero provider calls made.
-- `requires_initialization` — call `initialize()` yourself. The package will **not** do it
-  implicitly, because that would hide an async, billable operation behind a setter.
-
-Existing `ads.setEnabled(false);` call sites still compile untouched.
-
-## 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` 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
-  ad to verify anything.
-- **Consent tools going quiet in production.** `consentTesting.debugGeography` and
-  `resetOnStart` are stripped at config validation in `production` and listed by
-  `getIgnoredConsentTools()`. Working as designed.
-- **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
-
-No `retry` in config means the request count is byte-identical to 0.1.0 — a test in the
-package proves it. When enabled it is bounded (default 2 retries, 2s then 4s, no jitter),
-retries only errors already flagged `retryable`, and cancels everything on disable,
-undecided, consent loss or `dispose()`. Every attempt emits `retry_scheduled` carrying the
-load cycle's `correlationId`, because every attempt is a billable request.
-Per-placement `retry: false` turns it off for one placement.
-
-## App-open: the one rule you cannot implement yourself
-
-App-open shares the single full-screen lock with interstitial and rewarded, and expires on
-its own shorter window (30 min default, vs 60). The part worth knowing: a show requested
-on a return **from an ad** — or from a browser an ad opened — is refused with
-`ad_originated_return`, distinct from `busy` and `not_ready`. Your app cannot tell that
-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.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`,
-`useAds` · `AdsBanner` · `usePlacementState`, `useAdsStatus`, `useAdsEvents` · `AdsError`,
-`AdsConfigError`, `isAdsError`, `isFullScreenFormat` · `DEFAULT_LOAD_TIMEOUT_MS`,
-`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`, `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`,
-`consent`, `getStatus`, `subscribeStatus`, `load`, `show`, `getPlacementState`,
-`subscribePlacement`, `subscribeEvents`, `getSubstitutedPlacements`,
-`getIgnoredConsentTools`, `dispose`.
-
-Consent namespace (`ads.consent.*`, opt-in — untouched, nothing starts):
-`requestInfoUpdate`, `showFormIfRequired`, `showPrivacyOptionsForm`, `getState`,
-`subscribe`, `reset`.
-
-Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdFormat`,
-`FullScreenFormat`, `Environment`, `Enablement`, `EnablementResult`, `ConsentApi`,
-`ConsentState`, `ConsentSnapshot`, `ConsentTestingOptions`, `PrivacyOptionsRequirement`,
-`PrivacyOptionsFormResult`, `RetryPolicy`, `InitStatus`,
-`PlacementState`, `InitResult`, `LoadResult`, `ShowResult`, `PrivacyUpdateResult`,
-`Reward`, `AdEvent`, `AdEventType`, `AdEventListener`, `ConfigWarning`, `ImpressionSource`,
-`AdsErrorCode`, `AdsOperation`, `TimeoutConfig`, `AdContentRating`, `PrivacyBlockReason`,
-`UnavailableReason`, `Unsubscribe`, `AdsBannerProps`, `AdsProviderProps`.
-
-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
-`switch` over any of them needs 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'` |
-
-Everything else is opt-in: consent, `'undecided'`, app-open and retry are all off or absent
-until configured. One behavior change needs no action — on an unavailable platform with
-ads also disabled, the reason is now `unsupported_platform` where 0.1.0 said `disabled`.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
-
-| Need | Section |
-|---|---|
-| 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` |
-| Permissions, Data safety, families | `## Install`, `## Release checklists` |
-| Build failure after a bridge upgrade | `## Compatibility` |
-| Migration detail | `## Versioning` |
-| What is deferred | `## Known limitations`, `## Extending to iOS` |
+---
+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 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.4.0"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-ads
+
+Adaptive banner, interstitial, rewarded and app-open ads on Android via Google AdMob,
+behind a contract that names no provider. The app names a placement key; the package owns
+the request. Consuming code never imports the Google Mobile Ads SDK — including for
+consent.
+
+## Use this when
+
+- 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
+- Debugging an ad that never loads, or a `blocked` / `undecided` / `unavailable` /
+  `ad_originated_return` / `provider_error`
+- Answering a Data safety / App Privacy question about advertising
+
+## Do not use this for
+
+- **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 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.
+- **Anything about payments** — the undecided state exists *because* apps sell ad removal,
+  but the package receives a decision and never a reason, receipt or entitlement.
+- iOS — not implemented; every call returns `unavailable` / `unsupported_platform`.
+
+## Nothing loads until consent and initialization complete
+
+This is enforced, and it is the answer to almost every "the ad never appears". With the
+gate withheld, **zero** provider calls occur — not even configuration. `childDirected`,
+`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:
+**platform availability → enablement → consent**, most immovable first. So
+`unsupported_platform` on a disabled instance is reported as `unsupported_platform` —
+turning ads on would not have helped. Full table in `## Why an ad did not show`.
+
+## Never gate `<AdsBanner>` on its own placement state
+
+`AdsBanner` is what measures the container and starts the load, so it must be mounted
+unconditionally. Rendering it only when the state is `loading`/`ready` deadlocks at
+`idle` and no ad ever appears. Use the state for the *surrounding* placeholder and to
+decide whether to hold or reclaim space — never to decide whether to mount the host. It
+renders `null` on its own when there is nothing to show.
+
+## `undecided` is not `disabled`, and that is the whole point
+
+`enabled` takes `true`, `false` or `'undecided'`. All three send zero requests except
+`true`. `'undecided'` reports itself distinctly — in `getStatus()` and in the banner's
+placement state — so an app that has not yet heard back from the store can **hold** the
+banner's space instead of reclaiming it, and a paying user never sees an ad flash in and
+out. `disabled` means a settled no; reclaim the space.
+
+The package never resolves it for you. Leave it unresolved past `undecidedWarningMs`
+(default 10s) and you get exactly one `config_warning`, never a stream.
+
+## `setEnabled` returns a result — read it
+
+In 0.1.0 it returned `void` and re-enabling after a disable silently dropped the init
+status, so every later `load` and `show` was refused with nothing to say so. That was a
+defect and it is fixed. The result now says which happened:
+
+- `resumed` — the provider was never un-initialized; load away, zero provider calls made.
+- `requires_initialization` — call `initialize()` yourself. The package will **not** do it
+  implicitly, because that would hide an async, billable operation behind a setter.
+
+Existing `ads.setEnabled(false);` call sites still compile untouched.
+
+## 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` 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
+  ad to verify anything.
+- **Consent tools going quiet in production.** `consentTesting.debugGeography` and
+  `resetOnStart` are stripped at config validation in `production` and listed by
+  `getIgnoredConsentTools()`. Working as designed.
+- **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
+
+No `retry` in config means the request count is byte-identical to 0.1.0 — a test in the
+package proves it. When enabled it is bounded (default 2 retries, 2s then 4s, no jitter),
+retries only errors already flagged `retryable`, and cancels everything on disable,
+undecided, consent loss or `dispose()`. Every attempt emits `retry_scheduled` carrying the
+load cycle's `correlationId`, because every attempt is a billable request.
+Per-placement `retry: false` turns it off for one placement.
+
+## App-open: the one rule you cannot implement yourself
+
+App-open shares the single full-screen lock with interstitial and rewarded, and expires on
+its own shorter window (30 min default, vs 60). The part worth knowing: a show requested
+on a return **from an ad** — or from a browser an ad opened — is refused with
+`ad_originated_return`, distinct from `busy` and `not_ready`. Your app cannot tell that
+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.5.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`,
+`useAds` · `AdsBanner` · `usePlacementState`, `useAdsStatus`, `useAdsEvents` · `AdsError`,
+`AdsConfigError`, `isAdsError`, `isFullScreenFormat` · `DEFAULT_LOAD_TIMEOUT_MS`,
+`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`, `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`,
+`consent`, `getStatus`, `subscribeStatus`, `load`, `show`, `getPlacementState`,
+`subscribePlacement`, `subscribeEvents`, `getSubstitutedPlacements`,
+`getIgnoredConsentTools`, `dispose`.
+
+Consent namespace (`ads.consent.*`, opt-in — untouched, nothing starts):
+`requestInfoUpdate`, `showFormIfRequired`, `showPrivacyOptionsForm`, `getState`,
+`subscribe`, `reset`.
+
+Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdFormat`,
+`FullScreenFormat`, `Environment`, `Enablement`, `EnablementResult`, `ConsentApi`,
+`ConsentState`, `ConsentSnapshot`, `ConsentTestingOptions`, `PrivacyOptionsRequirement`,
+`PrivacyOptionsFormResult`, `RetryPolicy`, `InitStatus`,
+`PlacementState`, `InitResult`, `LoadResult`, `ShowResult`, `PrivacyUpdateResult`,
+`Reward`, `AdEvent`, `AdEventType`, `AdEventListener`, `ConfigWarning`, `ImpressionSource`,
+`AdsErrorCode`, `AdsOperation`, `TimeoutConfig`, `AdContentRating`, `PrivacyBlockReason`,
+`UnavailableReason`, `Unsubscribe`, `AdsBannerProps`, `AdsProviderProps`.
+
+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
+`switch` over any of them needs 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'` |
+
+Everything else is opt-in: consent, `'undecided'`, app-open and retry are all off or absent
+until configured. One behavior change needs no action — on an unavailable platform with
+ads also disabled, the reason is now `unsupported_platform` where 0.1.0 said `disabled`.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
+
+| Need | Section |
+|---|---|
+| 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` |
+| Permissions, Data safety, families | `## Install`, `## Release checklists` |
+| Build failure after a bridge upgrade | `## Compatibility` |
+| Migration detail | `## Versioning` |
+| What is deferred | `## Known limitations`, `## Extending to iOS` |