@maccesar/titools 5.1.1 → 5.2.1

package/skills/ti-admob-unified/references/dependencies.md

@@ -0,0 +1,91 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at release source commit `034843299b2984253988e0ffccb9f6a1c91682c9` (copied 2026-10-24). Relative links rebased for this skill.
+
+# Dependency inventory
+
+The core and five optional complements use the published SDK and adapter pairs verified on October 23, 2026. Each module has its own iOS Podfile, lockfile and framework checksum inventory. Android pins live in each module's `android/build.gradle`.
+
+The latest published Google adapters determine the network SDK versions. Meta iOS SDK `6.22.1` and InMobi Android SDK `11.5.1` are available independently, but their current Google adapters pin `6.22.0` and `11.5.0` respectively; those tested pairs are retained. Do not replace a network SDK independently of its adapter. InMobi Android adapter `11.5.0.1` is available as an AAR and POM in Google's Maven repository, although its documentation heading still says "In progress".
+
+Google currently lists GMA iOS `13.x` and Android `25.x` as supported. Check both the [iOS sunset schedule](https://developers.google.com/admob/ios/deprecation) and [Android sunset schedule](https://developers.google.com/admob/android/deprecation), plus SDK/provider advisories, before distributing an app update. A supported major version and a store-specific SDK warning are separate checks; review any warning against the final app's resolved dependencies.
+
+## iOS vendored XCFrameworks: `ti.admob.unified`
+
+| Component               | Framework                           |  Version |
+| ----------------------- | ----------------------------------- | -------: |
+| Google Mobile Ads       | `GoogleMobileAds.xcframework`       | `13.11.0` |
+| User Messaging Platform | `UserMessagingPlatform.xcframework` |  `3.1.0` |
+
+## iOS per-network complements
+
+The eleven frameworks are stored without duplication under `mediation/<network>/ios/platform/`: AppLovin (2), Meta (2), InMobi (2), Unity (3), Liftoff (2). Unity Ads 4.21.0 no longer requires IronSourceAdQualitySDK. No ironSource advertising adapter or SDK is distributed.
+
+| Component                 | Framework                            |      Version |
+| ------------------------- | ------------------------------------ | -----------: |
+| AppLovin adapter          | `AppLovinAdapter.xcframework`        |   `13.6.4.0` |
+| AppLovin SDK              | `AppLovinSDK.xcframework`            |     `13.6.4` |
+| Meta adapter              | `MetaAdapter.xcframework`            | `6.22.0.0` |
+| Meta Audience Network SDK | `FBAudienceNetwork.xcframework`      |     `6.22.0` |
+| InMobi adapter            | `InMobiAdapter.xcframework`          |   `11.5.0.0` |
+| InMobi SDK                | `InMobiSDK.xcframework`              |     `11.5.0` |
+| Unity adapter             | `UnityAdapter.xcframework`           |   `4.21.0.0` |
+| Unity Ads SDK             | `UnityAds.xcframework`               |     `4.21.0` |
+| Unity support library     | `UnityCoherenceLib.xcframework`      |      `0.2.0` |
+| Liftoff Monetize adapter  | `LiftoffMonetizeAdapter.xcframework` |    `7.7.8.0` |
+| Vungle Ads SDK            | `VungleAdsSDK.xcframework`           |      `7.7.8` |
+
+The version column is the pinned CocoaPods version; lockfiles record the resolved adapter and SDK pair. Meta now uses SDK 6.22.0 on both platforms. Liftoff uses SDK 7.7.8 on iOS and 7.7.9 on Android. The version contract test records this difference and checks the networks whose versions match.
+
+The official CocoaPods specifications resolve the adapter and matching network SDK pairs. Each module has its own `ios/install_frameworks.sh`: it downloads that module's exact Podfile versions, stages its framework set, verifies its tree hashes, and restores the previous platform directory if validation fails. Run `ios/install_frameworks.sh` for the two core frameworks and `mediation/<network>/ios/install_frameworks.sh` for one complement. Complement installers use `pod install --deployment` to preserve the locked resolution.
+
+The tree checksum is calculated from the sorted list of relative file paths and the SHA-256 of every file in the XCFramework:
+
+```sh
+find . -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum -a 256 |
+  shasum -a 256
+```
+
+## Android Maven dependencies: `ti.admob.unified`
+
+Declared in `android/build.gradle`.
+
+| Coordinate                                       | Version |
+| ------------------------------------------------ | ------: |
+| `com.google.android.gms:play-services-ads`       |  25.5.0 |
+| `com.google.android.ump:user-messaging-platform` |   4.0.0 |
+| `com.google.guava:guava` | 33.7.2-android |
+
+## Android per-network complements
+
+Declared separately in `mediation/<network>/android/build.gradle`; `meta` uses the `facebook` coordinate and `liftoff` uses `vungle`.
+
+| Coordinate                          |  Version |
+| ----------------------------------- | -------: |
+| `com.google.ads.mediation:facebook` | 6.22.0.1 |
+| `com.google.ads.mediation:inmobi`   | 11.5.0.1 |
+| `com.google.ads.mediation:unity`    | 4.21.0.0 |
+| `com.google.ads.mediation:applovin` | 13.6.4.2 |
+| `com.google.ads.mediation:vungle`   | 7.7.9.0 |
+
+Each complement declares its adapter coordinate. Unity also explicitly declares `com.unity3d.ads:unity-ads:4.21.0`: Google's adapter POM does not bring the Unity SDK transitively. Both entries must reach the packaged POM and consumer graph. See Google's [Unity Android integration guide](https://developers.google.com/admob/android/mediation/unity).
+
+InMobi, Liftoff and Unity also pin `com.squareup.okhttp3:okhttp:5.4.0` and `com.squareup.okio:okio:3.18.2`. OkHttp 5.4.0 requires compile SDK 36, provided by the declared minimum Titanium 13.4.1.GA. OkHttp 5.5.x requires compile SDK 37 and remains incompatible with this stable Titanium toolchain. Okio fixes base64 compatibility with callers compiled against pre-3.18 releases. These utility dependencies add no ad networks. The core pins Guava `33.7.2-android` for its deserialization allocation fix. Unity Ads 4.21.0 requests OkHttp 3.12.13 and Okio 1.15.0 without these overrides; both matched advisories during the isolated-consumer scan. Generated POMs propagate the reviewed versions into consumer applications.
+
+## Update policy
+
+All six modules remain at version `1.0.0`. Dependency updates require rebuilding both platform ZIPs for every discovered module, validating checksums, checking isolated consumer combinations and testing on available devices. Verify third-party delivery separately with configured accounts and Ad Inspector.
+
+## Transitive security review
+
+The October 23 refresh updates the direct utility overrides as well as the ad SDKs:
+
+| Dependency | Previous pin | Current pin | Modules |
+| --- | --- | --- | --- |
+| Guava | `33.7.1-android` | `33.7.2-android` | Core |
+| OkHttp | `4.12.0` | `5.4.0` | InMobi, Liftoff, Unity |
+| Okio | Transitive, including `3.6.0` / `3.7.0` | `3.18.2` | InMobi, Liftoff, Unity |
+
+Guava's [33.7.2 release](https://github.com/google/guava/releases/tag/v33.7.2) documents the allocation fix. OkHttp's [changelog](https://lysine.dev/okhttp/changelogs/changelog/) documents later releases, but 5.4.0 is the latest compatible pin because of the Android AAR compile-SDK requirements above. The 5.5.1 certificate-blocklist change is not included in this compatible pin; runtime OS support and compile-SDK requirements are separate constraints. The [Okio changelog](https://lysine.dev/okio/changelog/) describes the 3.18.2 compatibility correction.
+
+The October 23 [OSV querybatch](https://google.github.io/osv.dev/api/) scan covered 151 distinct resolved Maven name/version pairs across eight configurations: core, each complement, AppLovin + Unity, and all networks. No matches remained after the Unity utility overrides. The earlier September scan describes the old matrix. Dependency scanning and successful linking do not establish provider ad delivery.
+
+Unity `4.21.0.0` includes the adapter consent-forwarding update. Provider-side verification is described in the [mediation guide](mediation.md#unity-consent-with-the-pinned-adapter).

package/skills/ti-admob-unified/references/fullscreen.md

@@ -0,0 +1,238 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at release source commit `034843299b2984253988e0ffccb9f6a1c91682c9` (copied 2026-10-24). Relative links rebased for this skill.
+
+# Fullscreen ads
+
+Interstitial, rewarded, rewarded interstitial and app open proxies share one public lifecycle and event contract on iOS and Android.
+
+## When to show a fullscreen ad
+
+A fullscreen ad interrupts the current screen, so choose its presentation point before requesting it.
+
+Load early, show later: `load()` is a network request and can take seconds. Start it before the intended break, for example when a level opens, an article starts or a form appears. Call `show()` when the application reaches that break. Do not present unconditionally from the `loaded` listener: that lets network timing determine when the user is interrupted. A screen may instead keep an explicit Show request pending during loading, provided it cancels that request when the user leaves or the app loses the foreground.
+
+Show fullscreen ads at a natural break, such as between levels or after a task or flow ends. Avoid interrupting work in progress.
+
+Google's guidance includes these restrictions:
+
+- Do not show an interstitial as the app opens. That moment belongs to the App Open format, documented below.
+- Do not show one on the way out, when the user is already leaving.
+- Do not interrupt an action in progress, or place the ad where a button or a control the user was about to touch used to be.
+- Use `createRewarded()` or the dedicated `createRewardedInterstitial()` format for rewards. Ordinary interstitials must not offer rewards.
+- Avoid consecutive interstitials and excessive frequency. Configure the ad unit's frequency cap in the AdMob console; it is not a JavaScript setting.
+
+See the full restrictions in Google's [Android interstitial guide](https://developers.google.com/admob/android/interstitial) and [iOS interstitial guide](https://developers.google.com/admob/ios/interstitial).
+
+## Privacy gate
+
+Fullscreen proxies do not call UMP and do not enforce ad eligibility:
+
+```js
+if (!Admob.canRequestAds()) {
+  return
+}
+```
+
+Create and load fullscreen ads only after `module_initialized` succeeds.
+
+## Interstitial
+
+Load the ad ahead of its presentation point:
+
+```js
+const interstitial = Admob.createInterstitial({
+  adUnitId: Admob.TEST_INTERSTITIAL,
+  autoReload: false
+})
+
+interstitial.addEventListener(Admob.AD_LOADED, () => {
+  Ti.API.info('Interstitial is ready for the next break')
+})
+
+interstitial.addEventListener(Admob.AD_FAILED_TO_LOAD, event => {
+  Ti.API.warn(`Interstitial failed: ${event.error} (${event.code})`)
+})
+
+interstitial.load()
+```
+
+Then present it when the application reaches the break it chose:
+
+```js
+function onLevelCompleted() {
+  if (interstitial && interstitial.isLoaded()) {
+    interstitial.show()
+  }
+
+  goToNextLevel()
+}
+```
+
+If the ad is not ready, let the application continue and try at the next break.
+
+The executable [example app](../assets/example/app.js) loads automatically after initialization. Each format has one button that reports its state and enables Show when ready. One Show or Retry tap is enough: if an ad needs loading or replacement after a size change, the example waits and presents when it arrives. The rewarded interstitial card explains the reward and AdMob’s introduction requirements, links to the official policy and opens a Watch test ad/Skip introduction after Show. Watch permits presentation; Skip cancels it. Watch also remains valid through a required size replacement, so loading does not require another Show tap. Closing an ad preloads another without presenting it. Leaving the foreground, closing the window, changing privacy eligibility or requesting a different fullscreen cancels the pending presentation.
+
+## Rewarded
+
+Reward the user only from the `rewarded` event:
+
+```js
+const rewarded = Admob.createRewarded({
+  adUnitId: Admob.TEST_REWARDED,
+  autoReload: false
+})
+
+rewarded.addEventListener(Admob.AD_REWARDED, event => {
+  grantReward(event.rewardAmount, event.rewardType)
+})
+
+rewarded.addEventListener(Admob.AD_FAILED_TO_SHOW, event => {
+  Ti.API.warn(`Rewarded ad could not show: ${event.error}`)
+})
+
+rewarded.load()
+```
+
+Present it only after the user accepts a clear reward offer, using `isLoaded()` before `show()`. Closing a rewarded ad is not proof that the reward was earned. Keep the reward handler alive until the SDK delivers the result; mediated callback ordering may differ. Version `1.0.0` exposes client-side rewards only; it has no server-side verification configuration.
+
+The application must coordinate fullscreen proxies so only one presentation is active at a time. Keep it separate from UMP, ATT and Ad Inspector.
+
+## Rewarded interstitial
+
+`createRewardedInterstitial()` shares Rewarded's configuration, methods and reward event. Before presentation, explain the reward and offer a way to skip. The proxy does not show that introduction itself. See [Rewarded interstitial ads](rewarded-interstitial.md) for the complete flow.
+
+## App open
+
+Use an app open ad when the application enters the foreground, either at a cold start or when returning from the background. Load it beforehand and present it during the application's own loading state, before the user starts using the next screen:
+
+```js
+const appOpen = Admob.createAppOpen({
+  adUnitId: Admob.TEST_APP_OPEN,
+  autoReload: false
+})
+
+appOpen.addEventListener(Admob.AD_LOADED, () => {
+  Ti.API.info('App open ad is ready for the next foreground')
+})
+
+appOpen.load()
+```
+
+```js
+function onForegroundLoadingScreen() {
+  if (appOpen.isLoaded()) {
+    appOpen.show()
+  } else {
+    appOpen.load()
+  }
+}
+```
+
+Call this only while your loading screen is visible and no consent form, other fullscreen ad or external flow is active. Do not wire an unconditional show to every activity resume: closing an ad or returning from its click can also resume the host. If loading finishes before the ad is ready, continue into the app and save the ad for a later opportunity. Remove any application lifecycle listener when its owner is disposed.
+
+### The four hour window
+
+Google documents a four-hour validity window and its sample checks the time since the ad loaded. Both module proxies record successful load completion and check that age, with no timer and no extra event. See Google's [Android](https://developers.google.com/admob/android/app-open#consider_ad_expiration) and [iOS](https://developers.google.com/admob/ios/app-open) guides:
+
+- The load time is recorded when the ad arrives.
+- `isLoaded()` returns `false` once four hours have passed.
+- `show()` on an expired ad clears the native reference and emits `failed_to_show` with code `1` and the message `App open ad expired after four hours`.
+- `load()` discards an expired ad before requesting a new one, so a reload after expiry is not swallowed by the duplicate-load guard.
+
+`autoReload` reloads only after `closed`. The application decides when to replace an expired ad. Expiry checks subtract the stored time when called; they do not poll in the background.
+
+## Creation properties
+
+All four factories accept:
+
+| Property       | Type     | Default | Notes                                                              |
+| -------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `adUnitId`     | String   | `""`    | Required before `load()`.                                          |
+| `autoReload`   | Boolean  | `false` | Loads a fresh ad after a successful close, and after nothing else. |
+| `keywords`     | String[] | None    | Request keywords, applied as targeting on both platforms.          |
+| `requestAgent` | String   | None    | Identifies what issued the request, on both platforms.             |
+| `extras`       | Object   | None    | Forwarded through Google ad-network extras on both platforms.      |
+
+Do not use `extras` to bypass UMP or synthesize personalization state.
+
+Both platforms preserve primitive values in `extras`. Use the types required by the receiving adapter; for example, pass `{ npa: '1' }` when it expects a string.
+
+Pass initial configuration to the factory. Later assignments to `adUnitId`, `keywords`, `requestAgent` and `extras` affect the next request on both platforms; an already loaded ad keeps its original request configuration. `autoReload` is a live close policy: both native ports read its current value when the shown ad closes, so changing it while an ad is loaded or presented changes whether that close starts another load. It does not present another ad or retry a load/show failure.
+
+## Shared methods
+
+| Method       | Description                                                                                                     |
+| ------------ | --------------------------------------------------------------------------------------------------------------- |
+| `load()`     | Starts one request. Calls while loading, loaded, or showing are ignored. App open discards an expired ad first. |
+| `show()`     | Presents the loaded ad or emits `failed_to_show`.                                                               |
+| `isLoaded()` | Returns `true` only while an unused ad is ready. For app open, an ad older than four hours is not ready.        |
+| `destroy()`  | Terminal, idempotent cleanup; emits `destroyed` once.                                                           |
+
+Google fullscreen ads are single-use. Once presentation starts, `isLoaded()` is `false`. Native dismissal or presentation-failure callbacks discard the consumed reference. A local precondition failure, such as a missing host before presentation, can retain the unused ad; recheck readiness after correcting the condition. Call `load()` again before the next `show()`.
+
+Late native callbacks are ignored after `destroy()`. A dismissed or failed-to-show ad reference is cleared before the terminal event is emitted.
+
+On both platforms, `load()` after `destroy()` logs a warning without emitting an event. Banners emit `failed_to_load` in this case, so a handler must account for the proxy type.
+
+On Android, `load()` and `show()` need a current activity, and without one they emit `failed_to_load` or `failed_to_show` with the message `No current activity available` and code `-1`. It happens when the application calls in with no activity in the foreground. Code `-1` is the module's own, outside Google's error-code range.
+
+## Keeping the next ad ready
+
+For repeated presentations in one session, load the next ad after the previous one closes so it can be ready at the next break:
+
+```js
+interstitial.addEventListener(Admob.AD_CLOSED, () => {
+  interstitial.load()
+})
+```
+
+`autoReload: true` reloads after `closed` only. The application handles retries after `failed_to_load` and `failed_to_show`. Use backoff: a `NO_FILL` response will often still be `NO_FILL` a second later.
+
+Reuse the proxy across loads. Create a new one only after `destroy()`.
+
+## Events
+
+### Common events
+
+| Event                       | Interstitial | Rewarded | App open | Rewarded interstitial | Common payload                                     |
+| --------------------------- | -----------: | -------: | -------: | -------: | -------------------------------------------------- |
+| `loaded`                    |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`                               |
+| `failed_to_load`            |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`, `error`, `message`, `code`   |
+| `opened`                    |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`                               |
+| `showed_fullscreen_content` |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`                               |
+| `closed`                    |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`                               |
+| `clicked`                   |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`                               |
+| `impression`                |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`                               |
+| `failed_to_show`            |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`, `error`, `message`, `code`   |
+| `destroyed`                 |          Yes |      Yes |      Yes | Yes | `adUnitId`, `adType`                               |
+| `rewarded`                  |           No |      Yes |       No | Yes | `adUnitId`, `adType`, `rewardType`, `rewardAmount` |
+
+`message` duplicates `error` for compatibility. New code may use `error`; both keys are portable.
+
+## iPad collapsed-SVG workaround
+
+With the pinned GMA iOS 13.11.0 SDK, an Interstitial image creative can contain an SVG whose automatic width collapses in WebKit on iPad. The wrapper checks the presented Google WebView during a bounded first-second window. It repairs only `svg.advertiser-provided-image` with zero width, positive height, a valid SVG viewBox, a Google `simgad` background image and a column-flex parent. The parent receives the viewBox aspect ratio; visible images, intentionally hidden content and other layouts remain unchanged. Pending attempts stop on dismissal, presentation failure or destruction.
+
+The check applies to Interstitials on iPad with both demo and publisher-owned unit IDs. It uses internal creative markup and is not an official Google SDK setting. Other templates, nested content or later layout failures may remain outside its scope. Rewarded and Rewarded Interstitial are not modified. Device tests established the original repair with Google's demo creative; extending eligibility to publisher IDs does not certify every production creative. Validate your units with [test devices enabled](https://developers.google.com/admob/ios/test-ads).
+
+## Cleanup
+
+Use named callbacks and remove them before disposing the proxy:
+
+```js
+function disposeInterstitial() {
+  interstitial.removeEventListener(Admob.AD_LOADED, onLoaded)
+  interstitial.removeEventListener(Admob.AD_FAILED_TO_LOAD, onFailed)
+  interstitial.removeEventListener(Admob.AD_CLOSED, onClosed)
+  interstitial.destroy()
+}
+```
+
+Create a new proxy after disposal; a destroyed proxy cannot load again.
+
+## Not implemented
+
+The module exports format-name and test-ID constants for future compatibility, but it does not expose working factories for:
+
+- Native
+
+`TEST_NATIVE` names a unit no factory accepts.

package/skills/ti-admob-unified/references/game-monetization.md

@@ -0,0 +1,148 @@
+# Game monetization and module integration
+
+Use [fullscreen.md](fullscreen.md), [privacy.md](privacy.md) and
+[library.md](library.md) for calls. This reference adds game-specific product
+and lifecycle criteria, not a second module API. Reviewed against
+`ti.admob.unified@034843299b2984253988e0ffccb9f6a1c91682c9` (1.0.0).
+Read [production.md](production.md) before shipping an application. When
+available, `ti-game-assets/references/responsible-ads.md` adds asset/game
+coordination; this skill remains usable independently of it.
+
+## Current formats and their boundaries
+
+| Placement | Integration boundary |
+| --- | --- |
+| Interstitial | Preload; show at a natural break without offering a reward. Avoid app entry, exit, active gameplay and repeated/consecutive interruptions. |
+| Rewarded | Offer a clear voluntary exchange; present after acceptance; grant only from `rewarded` / `onRewarded`. |
+| Rewarded interstitial | Implemented by `createRewardedInterstitial()` and its library manager. At a natural transition, explain the configured reward and show a clear, unobstructed Skip option before presentation, with enough time to understand and decline. The proxy/manager does not build this introduction. See [rewarded-interstitial.md](rewarded-interstitial.md). |
+| App open | Implemented, but belongs only to an application's own foreground loading experience. Skip when content is already usable; do not show unconditionally from every resume. An expired ad needs a new load. |
+| Banner/adaptive banner | Reserve a safe, measured slot away from controls; preserve that slot across ordinary screen pauses. See [banners.md](banners.md). |
+| Native | No factory in 1.0.0. Format/test-ID constants alone do not implement it. |
+
+Adding another implemented format still requires an intentional product decision.
+Do not add forced rewarded continues or replace every retry with an ad. For a
+rewarded-interstitial introduction, use the reward configured for that unit;
+there is no pre-presentation reward getter. A visible Watch/Skip AlertDialog
+works on both platforms; an iPad OptionDialog's hidden cancel item is not an
+equivalent visible Skip action. Cancel a pending introduction when its screen
+closes, the foreground or eligibility is lost, or another fullscreen is chosen.
+
+Only the SDK's `rewarded` event grants value; `closed`, `impression`, clicks
+and a successful Show attempt do not. The rewarded-interstitial native proxies
+deduplicate reward callbacks per presentation and preserve the presented unit's
+SDK reward while another request may load. Keep reward handling alive for the
+SDK result: mediated reward and dismissal callback ordering can differ.
+`destroy()` is terminal and suppresses late callbacks; it is not a dismissal API.
+Client-side rewards do not provide server-side verification in this release.
+
+## Privacy and integration ownership
+
+Run the consent-first flow on every app launch: register listeners, request
+UMP, wait for `consent_complete`, evaluate `canRequestAds()`, initialize, then
+load. A failed UMP update may retain permission from a previous choice; an
+error alone is neither approval nor denial. Continue the game without ads
+when unavailable. Raw fullscreen proxies do not enforce this gate.
+
+ATT is separate. If the app uses it, resolve the foreground prompt after UMP
+and before initialization; keep the required description/translations even if
+an AdMob UMP IDFA message presents ATT. Query
+`getTrackingAuthorizationStatus()` to inspect state without prompting, including
+after Settings. Android's `applicable: false` / `authorized: true` convention
+is not general tracking permission. ATT denial does not override UMP's request
+gate. If explicitly requesting ATT, wait for `tracking_authorization_completed`
+even when permission was resolved in an earlier session. See [privacy.md](privacy.md).
+
+The copy-ready library owns sequencing, deferred loads, dimensions and placement
+cleanup. It does **not** choose game breaks, impose frequency limits, pause
+native gameplay/audio/input, or serialize unrelated application modal flows.
+Its `start()` promise is cached even after an unavailable result; repeating it
+is not a startup retry. Use the documented raw consent/init recovery flow if
+recoverable startup is part of the application. Never reset production consent
+to force another attempt.
+
+Provide an interactive privacy action when required. Serialize it with ads,
+ATT and Inspector; suspend new ad opportunities until its result is evaluated.
+The library reauthorizes/replaces requests after dismissal. Raw consumers must
+replace requests affected by changed choices themselves. Do not destroy an
+onscreen fullscreen ad to dismiss it or treat `destroyAll()` as cancelling
+UMP/Inspector: it releases placements only. See [library.md](library.md).
+
+## Community-Discovered Patterns
+
+These are preserved author guidance and integration lessons from Lander/Guardian,
+not additional module API or a verified optimal monetization policy. Their
+frequency/director separation remains useful alongside the official library;
+their application configuration and numeric thresholds are not defaults for
+other games.
+
+Choose deliberate natural breaks, such as settled end-of-run results, rather
+than interrupting flight/combat or attaching an ad to every retry. Preserve
+pause/tutorial/practice and voluntary-exit choices. Load early, but let the
+application choose Show. A time threshold makes a later break eligible; it
+never authorizes a timer-driven interruption. Google's
+[interstitial placement guidance](https://support.google.com/admob/answer/6201362?hl=en)
+disallows unexpected and excessive placements; re-check it before a live change.
+
+Before presentation, capture the intended scene state, suspend native motion
+and relevant timers, silence app-owned audio as appropriate, and release held
+input. A stopped JS tick does not stop native gravity. Restore only the scene,
+clock scale and audio that should still be active after dismissal or confirmed
+failure, provided the owner is alive and the app is foregrounded. Do not blindly
+resume a previously paused game, undo a newer navigation choice, or restore held
+throttle/fire inputs. Returning from an ad is a lifecycle event, not a new ad
+opportunity.
+
+One application director owns presentation and rejects simultaneous attempts,
+including UMP, ATT, Inspector and other fullscreen formats. Keep a once-only
+continuation and an ownership/generation token so callbacks from an abandoned
+screen cannot advance its successor. A missing-opening watchdog may recover an
+attempt that never opens; after a confirmed `opened`, clear that watchdog and
+wait for actual dismissal or presentation failure. An opening/impression does
+not prove the creative was visibly rendered. Associate completion with the
+active attempt: a rejected duplicate Show is not proof that an already open
+ad has ended.
+
+Distinguish the APIs at the boundary: raw `load()` / `show()` return no success
+value. Library-manager `show()` returns `false` when not ready or when the
+size guard requests a replacement; continue without blocking. A `true` result
+means presentation was attempted and may still fail through `onFailedToShow`.
+Supply the owning window. The manager does not queue a future Show after
+returning `false`; a late load or background/resume must not launch a missed
+interstitial. An explicit user-requested pending flow, such as the published
+rewarded-interstitial demo, needs its own cancellation and introduction state.
+
+Keep grace period, active-play accumulation, cooldown after dismissal,
+hourly/daily caps and permitted boundaries distinct. Count actual openings
+once and close separately; do not count both `opened` and
+`showed_fullscreen_content` as two exposures. Preserve persistence and
+conservative handling of clock rollback. Caps are ceilings, not exposure
+targets, and application eligibility is separate from AdMob's ad-unit cap.
+Use backoff after load/show failures; `autoReload` requests a replacement after
+`closed` only and never presents it automatically.
+
+A banner host must stay away from touch controls and reserve the native loaded
+height inside safe areas. Choose `collapseOnFailure: false` on a library banner
+when retrying should preserve its slot. Use screen-level `pause()` / `resume()`
+only when navigation hides it while the same host lifecycle remains active;
+background/activity lifecycle is already native. Pausing preserves the creative,
+visibility and geometry; no JS refresh timer or destroy/recreate loop is needed.
+On Android, ignore `_closeFromActivityForcedToDestroy` for placement teardown:
+that close can be activity recreation rather than a destroyed screen. Remove
+named listeners and destroy placements on actual owner disposal. Preserve reward
+listeners until their result; destruction must not resume an abandoned game.
+
+## Acceptance in the consuming game
+
+Use test units and test devices. Exercise unavailable module, no fill,
+load/show failures, repeated taps, late/duplicate callbacks, reward once,
+Skip, real dismissal, background/resume, privacy changes, rotation between
+load/introduction/Show, owner destruction and phone/tablet layouts on both
+platforms. Check native clock, input and audio restoration on each path.
+
+A source check, wrapper test, SDK opening or impression does not prove visible
+creative rendering, provider delivery or acceptable game frequency. Record
+physical visual acceptance separately. Where telemetry is authorized, measure
+confirmed exposure per active-play minute, abandonment at boundaries and
+retention/retries. Unit tests do not prove players enjoy the frequency.
+Production units, app verification, app-ads.txt, provider setup and store/privacy
+disclosures belong to [production.md](production.md), not game frequency logic.