@maccesar/titools 5.1.0 → 5.2.0

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

@@ -0,0 +1,85 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at commit `5b4cbf9` (copied 2026-10-11). Relative links rebased for this skill.
+
+# Integrating the module
+
+The native module manages Google Mobile Ads, UMP, portable proxy behavior and host lifecycle. The consuming application controls navigation and layout, including which screen is visible.
+
+## Recommended path
+
+Copy [`example/lib/ads.js`](../assets/example/lib/ads.js) into the consuming application's `lib/` directory. It covers every format implemented by version `1.0.0` and supplies the startup, cleanup and placement code shared by applications.
+
+See [Copy-ready JavaScript library](library.md) for the API and examples, and [`example/library-usage.js`](../assets/example/library-usage.js) for a compact runnable integration.
+
+## Division of responsibility
+
+| Responsibility                                               | Owner                                                               |
+| ------------------------------------------------------------ | ------------------------------------------------------------------- |
+| UMP, Google Mobile Ads initialization and native callbacks   | Module                                                              |
+| Application/activity background and foreground               | Module                                                              |
+| Automatic banner refresh                                     | Google Mobile Ads SDK, using the ad-unit policy configured in AdMob |
+| Consent → `canRequestAds()` → initialization sequence        | Copy-ready library, or the application when using the raw API       |
+| Tab/window coverage                                          | Application                                                         |
+| Permanent banner host and content inset                      | Application                                                         |
+| Production/test ad-unit selection                            | Application build configuration                                     |
+| Frequency and natural presentation points for fullscreen ads | Application                                                         |
+
+## Screen lifecycle
+
+Handle screen navigation separately from application backgrounding.
+
+The module automatically follows the Android activity and iOS application lifecycle. Do not add duplicate `Ti.App` pause/resume handlers for banners.
+
+An Android secondary window backed by another activity is already covered by the automatic lifecycle handling. The application calls `pause()` only when its own navigation hides a placement while the same host lifecycle remains active, such as a custom same-activity overlay:
+
+```js
+banner.pause()
+
+const child = Alloy.createController('child').getView()
+child.addEventListener('close', () => banner.resume())
+child.open()
+```
+
+Pausing does not change `visible`, opacity, height, the host, or the loaded creative. Do not destroy/recreate on tab changes, focus/blur, or light/dark appearance changes. Rebuild only for a real configuration or authorization boundary, or after a recoverable failure.
+
+On Android, the module handles activity recreation caused by a configuration change. It releases the stale native `AdView`, preserves the JavaScript proxy without emitting `destroyed`, and reloads after Titanium creates the replacement view.
+
+## Refresh ownership
+
+Call `load()` once when creating a banner. Do not add `setInterval`, `setTimeout`, or a periodic destroy/create loop. Google Mobile Ads reads the refresh policy configured for that ad unit in AdMob and owns subsequent banner requests.
+
+The application pauses a placement when navigation hides it. On iOS the module disables native autoload until every pause cause clears. On Android it pauses native ad-view processing; Google also requires the banner to be visible for automatic refresh. Keep a visible banner active even if an internal screen state changes.
+
+## Banner layout
+
+Reserve the slot when creating the placement. Expanding it after the first creative arrives moves content that is already on screen.
+
+Keep these layout values aligned:
+
+```js
+bannerHost.height = dimension
+content.bottom = dimension
+```
+
+Keep both values unchanged during `pause()` and `resume()` to avoid reflowing lists and scroll views while the same placement remains in use.
+
+Adaptive banners report their real `event.height` in dp. Fixed banners should reserve the exact height of the requested size. See [Banner ads](banners.md#reserve-real-layout-space).
+
+## Raw API
+
+Applications that do not want the copy-ready library can use the module directly. [`example/app.js`](../assets/example/app.js) exercises the low-level API, including:
+
+- consent and optional ATT;
+- initialization and mediation diagnostics;
+- standard and adaptive banners;
+- explicit screen-level banner pause/resume;
+- interstitial, rewarded and app-open load/show separation;
+- privacy options and deterministic cleanup.
+
+When using the raw API, keep named event callbacks so every listener can be removed before `destroy()`.
+
+## Next
+
+- [Copy-ready JavaScript library](library.md)
+- [Banner ads](banners.md)
+- [Fullscreen ads](fullscreen.md)
+- [Privacy and initialization](privacy.md)

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

@@ -0,0 +1,189 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at commit `5b4cbf9` (copied 2026-10-11). Relative links rebased for this skill.
+
+# Copy-ready JavaScript library
+
+The integration library is [`example/lib/ads.js`](../assets/example/lib/ads.js). Copy it unchanged to the appropriate location:
+
+- Alloy: `app/lib/ads.js`
+- Classic Titanium: `Resources/lib/ads.js`
+
+Then import it with:
+
+```js
+const Admob = require('ti.admob.unified')
+const ads = require('lib/ads')
+```
+
+The library handles UMP sequencing, the `canRequestAds()` check, initialization, named-listener cleanup, banner slots, deferred loads, privacy-option reauthorization and terminal cleanup. You can also use the native module directly, as [`example/app.js`](../assets/example/app.js) does while sharing the library’s fullscreen size guard.
+
+## What it covers
+
+| Format          | Library factory          | Lifecycle returned                                                       |
+| --------------- | ------------------------ | ------------------------------------------------------------------------ |
+| Standard banner | `createBanner()`         | `pause()`, `resume()`, `retry()`, `rebuild()`, `isLoaded()`, `destroy()` |
+| Adaptive banner | `createAdaptiveBanner()` | `pause()`, `resume()`, `retry()`, `rebuild()`, `isLoaded()`, `destroy()` |
+| Interstitial    | `createInterstitial()`   | `load()`, `show()`, `retry()`, `isLoaded()`, `destroy()`                 |
+| Rewarded        | `createRewarded()`       | `load()`, `show()`, `retry()`, `isLoaded()`, `destroy()`                 |
+| App open        | `createAppOpen()`        | `load()`, `show()`, `retry()`, `isLoaded()`, `destroy()`                 |
+
+Rewarded interstitial and native ads are not included because version `1.0.0` does not implement those factories.
+
+## Start once
+
+Create placements before or after `start()`. Loads requested before initialization wait until privacy checks and SDK initialization complete.
+
+```js
+ads.start({
+  consent: {
+    tagForUnderAgeOfConsent: false
+  },
+  initialization: {
+    testDeviceIds: ['YOUR_TEST_DEVICE_ID']
+  }
+}).then(result => {
+  if (!result.initialized) {
+    Ti.API.warn('Ads are unavailable for this session')
+  }
+})
+```
+
+Set `requestTrackingAuthorization: true` only when the application has a real ATT use case and a valid `NSUserTrackingUsageDescription`. ATT is not another ad-request gate.
+
+## Banners
+
+A banner needs a permanent host and a positive reservation in dp. The library changes the host height and the adjacent content inset together; it never overlays the content.
+
+```js
+const banner = ads.createAdaptiveBanner({
+  host: bannerHost,
+  content,
+  reservedHeight: 50,
+  adUnitId: Admob.TEST_ADAPTIVE_BANNER,
+  adaptiveType: Admob.ADAPTIVE_ANCHORED,
+  onLoaded: event => Ti.API.info(`Banner: ${event.height}${event.heightUnit}`),
+  onFailedToLoad: event => Ti.API.warn(event.error)
+})
+```
+
+Use `createBanner()` with `adSize` or `customAdSize` for a fixed banner. Use `createAdaptiveBanner()` when Google should choose the height for the available width.
+
+Call `pause()` when that placement stops being shown because the application selected another tab or opened another window over it. Call `resume()` when the same screen is shown again. These methods preserve the same native proxy, creative, visibility, opacity, host, and reserved height:
+
+```js
+banner.pause()
+openChildWindow()
+
+child.addEventListener('close', () => {
+  banner.resume()
+})
+```
+
+Do not mirror `Ti.App` background and foreground events. The native module already owns activity/application lifecycle as an independent pause cause.
+
+The library creates no refresh timer. The first request comes from `load()`; later banner refreshes belong to Google Mobile Ads and the refresh policy configured for that ad unit in AdMob. A banner that is not actually on screen is ineligible for Android auto-refresh. On iOS the module disables and restores native autoload while paused.
+
+Use `retry()` after a recoverable failure. Use `rebuild()` when the placement configuration changes, such as its width or orientation. Tab focus, window focus, appearance changes and ordinary background/foreground transitions do not require a rebuild.
+
+## Fullscreen ads
+
+Create once, load early, and show only at a moment chosen by the application:
+
+```js
+const interstitial = ads.createInterstitial({
+  window: win,
+  adUnitId: Admob.TEST_INTERSTITIAL,
+  autoReload: true,
+  onLoaded: () => Ti.API.info('Ready for the next natural break')
+})
+
+interstitial.load()
+
+function onNaturalBreak() {
+  interstitial.show() // false means no ready ad; continue without blocking
+}
+```
+
+Rewarded ads grant value only from `onRewarded`:
+
+```js
+const rewarded = ads.createRewarded({
+  window: win,
+  adUnitId: Admob.TEST_REWARDED,
+  onRewarded: event => grantReward(event.rewardAmount, event.rewardType)
+})
+```
+
+App-open ads are prepared the same way and shown only during the application's own foreground loading experience:
+
+```js
+const appOpen = ads.createAppOpen({
+  window: win,
+  adUnitId: Admob.TEST_APP_OPEN
+})
+
+appOpen.load()
+
+function onApplicationResumed() {
+  appOpen.show()
+}
+```
+
+Pass the owning `window` to each fullscreen factory (otherwise the library reads `Ti.UI.currentWindow`). The library remembers its dimensions when requesting the ad. Rotation alone makes no requests. At `show()`, a changed size discards and reloads only that ad and returns `false`; wait for `onLoaded` and a later user action to show it. Banners are not rebuilt by this check.
+
+The raw-API playground shares this logic through `createFullscreenSizeGuard(getSize)`: call `recordLoad()` before requesting, then `show(present, reload)` when the user requests presentation. This helper does not initialize the SDK or run consent.
+
+`show()` returns `false` when no valid ad is ready. Do not delay navigation or user work waiting for a fullscreen request.
+
+## Privacy and diagnostics
+
+Expose the privacy entry point only when required:
+
+```js
+privacyButton.visible = ads.isPrivacyOptionsRequired()
+
+function openPrivacyOptions() {
+  ads.showPrivacyOptions().then(event => {
+    if (event.success === false) {
+      Ti.API.warn(event.error)
+    }
+  })
+}
+```
+
+After the form closes, the library reevaluates authorization and rebuilds active ad requests to account for any consent changes.
+
+Ad Inspector also has a promise wrapper:
+
+```js
+ads.openAdInspector().then(event => {
+  if (!event.success) {
+    Ti.API.warn(event.error)
+  }
+})
+```
+
+## Cleanup
+
+Destroy a placement when its owning window closes. For application shutdown or a test harness, dispose every registered placement at once.
+
+On Android, Titanium also fires `close` while it recreates the window's activity, for example when the user switches between light and dark mode. The window survives, and the event carries `_closeFromActivityForcedToDestroy`. Skip that event, or the ads and their listeners are gone when the window comes back:
+
+```js
+win.addEventListener('close', event => {
+  if (!event._closeFromActivityForcedToDestroy) banner.destroy()
+})
+
+// Or, when this ads service owns every placement:
+ads.destroyAll()
+```
+
+Every destroy operation is idempotent. A destroyed manager cannot be reused; create another manager for a new placement.
+
+See [`example/library-usage.js`](../assets/example/library-usage.js) for a complete runnable integration.
+
+
+## Concurrent operations and cleanup
+
+Concurrent calls to `showPrivacyOptions()` share one native presentation and one promise. `openAdInspector()` does the same for Inspector. Terminal events and synchronous native exceptions remove their listeners; a later call starts a new operation. `destroyAll()` releases placements only. It does not cancel an SDK form or its pending promise.
+
+A banner failure or destruction cleans up the old proxy before invoking application callbacks, so calling `retry()` from those callbacks preserves the replacement. On iOS, adaptive placements reserve the native anchored height when width is known and wait for positive layout before loading. Destroying a placement removes any pending layout listener.

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

@@ -0,0 +1,132 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at commit `5b4cbf9` (copied 2026-10-11). Relative links rebased for this skill.
+
+# AdMob mediation
+
+The first release, `1.0.0`, provides five optional dependency modules with identical identifiers on iOS and Android. Install only the networks the application intends to use. The core `ti.admob.unified` contains Google Mobile Ads and UMP only. Each complement has no JavaScript API and performs no manual provider initialization.
+
+| Network                   | Module ID                             | iOS adapter | Android adapter |
+| ------------------------- | ------------------------------------- | ----------- | --------------- |
+| AppLovin                  | `ti.admob.unified.mediation.applovin` | `13.6.4.0`  | `13.6.4.2`      |
+| Meta Audience Network     | `ti.admob.unified.mediation.meta`     | `6.22.0.0`  | `6.22.0.1`      |
+| InMobi                    | `ti.admob.unified.mediation.inmobi`   | `11.4.1.0`  | `11.4.1.2`      |
+| Unity Ads                 | `ti.admob.unified.mediation.unity`    | `4.20.1.0`  | `4.20.1.0`      |
+| Liftoff Monetize (Vungle) | `ti.admob.unified.mediation.liftoff`  | `7.7.7.0`   | `7.7.8.1`       |
+
+ironSource mediation is deferred: neither its adapter nor its advertising SDK is distributed. Unity includes UnityCoherenceLib. Unity Ads 4.20.1 no longer depends on IronSourceAdQualitySDK, so it is not distributed.
+
+## Installing one or several networks
+
+Install the core ZIP and each selected complement ZIP for every target platform. One declaration covers both platforms:
+
+```xml
+<modules>
+  <module version="1.0.0">ti.admob.unified</module>
+  <module version="1.0.0">ti.admob.unified.mediation.applovin</module>
+</modules>
+```
+
+For AppLovin and Unity together:
+
+```xml
+<modules>
+  <module version="1.0.0">ti.admob.unified</module>
+  <module version="1.0.0">ti.admob.unified.mediation.applovin</module>
+  <module version="1.0.0">ti.admob.unified.mediation.unity</module>
+</modules>
+```
+
+Use `1.0.0` for the core and complements. Call only `require('ti.admob.unified')` and its factories. To remove a network, remove its declaration and rebuild.
+
+## Installing an adapter is not the same as enabling a network
+
+Installing an adapter adds its SDK to the application and makes it discoverable by Google Mobile Ads. It does not approve a publisher account, configure a mediation group or validate credentials. Leave unneeded complements out of the build. Their exact frameworks, dependencies and versions are recorded in [Dependencies](dependencies.md).
+
+## Publisher setup
+
+For each network that an application will use:
+
+1. Create or connect the publisher account for that network.
+2. Add the network as an ad source in the AdMob mediation group.
+3. Enter the provider credentials and map the provider placement to the AdMob ad unit.
+4. Complete the provider's privacy and store-disclosure requirements.
+5. Validate the integration with test ads and Ad Inspector before enabling production traffic.
+
+Google Mobile Ads can still inspect or initialize every installed adapter during SDK startup. In development, incomplete or conflicting server mappings can produce provider warnings even when Google serves the requested test banner. Examples include a missing AppLovin SDK key and multiple Liftoff Monetize app IDs. The module does not add provider credentials to either native manifest; AdMob supplies those server parameters from the mediation mapping.
+
+Do not silence these messages with placeholder credentials. Complete the provider mapping, use that provider's test mode, and verify it through single-source testing in Ad Inspector. If the application does not intend to use a network, leave it out of the AdMob mediation group.
+
+Google maintains the current setup instructions and format caveats in its [Android mediation network guide](https://developers.google.com/admob/android/choose-networks) and [iOS mediation network guide](https://developers.google.com/admob/ios/choose-networks). Use formats supported by the selected network and adapter version.
+
+## Missing configuration and startup errors
+
+Only install selected complements when the app will use mediation and its publisher accounts, source mappings and credentials are configured. The examples and the core-only test app do not require these accounts. Do not install the complements merely to run Google demo ads.
+
+An internal Android demo build with several adapters produced these messages. Each points to a different failure; only some identify missing credentials:
+
+| Message                                 | What it establishes                                                                                                                                                | Action                                                                                                                                                   |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| AppLovin: `Missing or invalid SDK Key.` | The adapter did not receive a usable SDK key.                                                                                                                      | Verify the publisher SDK key and the AppLovin mapping in AdMob.                                                                                          |
+| AdColony: `Failed to create Adapter.`   | Google could not construct the requested adapter. This does not establish a missing key. AdColony is not one of the five distributed adapters.                     | Inspect the requested ad source/mapping and adapter availability in Ad Inspector. Do not add a legacy SDK or placeholder credentials just to silence it. |
+| Liftoff/Vungle: `Timeout.`              | Initialization did not finish before the SDK timeout. In the observed run, a preceding warning reported conflicting app IDs and selection of `fake-vungle-app-id`. | Check the provider app ID and AdMob mapping; the timeout alone does not prove which configuration value is wrong.                                        |
+
+### Why there is no automatic “missing local key → skip this network” filter
+
+Each optional module only packages dependencies; it does not call each provider's initializer. Google Mobile Ads controls adapter initialization and supplies mediation parameters from AdMob. There is no supported pre-initialization API in the Google Mobile Ads APIs used here that lets this module read all publisher mappings and selectively suppress adapters with missing credentials.
+
+A key may be absent from JavaScript or the native manifest and still be configured in AdMob. The [AppLovin adapter guide](https://developers.google.com/admob/android/mediation/applovin) instructs publishers to enter the SDK key in AdMob; its changelog says adapter 12.1.0.0 stopped checking the Android manifest. The module leaves readiness checks and provider initialization to Google, without using private SDK internals.
+
+Choose the setup that matches the application:
+
+- For Google ads alone, omit complements and call `Admob.initialize({})`. There are no third-party adapters to initialize.
+- For mediation, include one `tiapp.xml` entry per selected network, configure its account and AdMob mappings, and call `Admob.initialize({})`. Google discovers the installed adapters without an `enableMediation` flag or manual provider initializer. Check native initialization results and Ad Inspector; `getMediationStatus()` reports the adapter initialization states known to Google.
+
+For a session that deliberately skips initialization of installed adapters, see the [initialization reference](api-reference.md#automatic-adapter-discovery). That exception is global and does not validate credentials or filter individual networks.
+
+## Portable diagnostics
+
+`getMediationStatus()` belongs to the core and returns `{ initializationState, adapters }`. It includes every adapter Google reports, including Google, sorted by native class name. Entries contain `adapterClass`, `state`, `description` and numeric `latencyMs`; native class names may differ across platforms.
+
+```js
+const Admob = require('ti.admob.unified')
+Admob.addEventListener('module_initialized', event => {
+  const diagnostic = Admob.getMediationStatus()
+  Ti.API.info(diagnostic.initializationState)
+  diagnostic.adapters.forEach(adapter => {
+    Ti.API.info(`${adapter.adapterClass}: ${adapter.state} (${adapter.latencyMs} ms) ${adapter.description}`)
+  })
+})
+```
+
+Before `initialize()`, the result is `not_started` with no adapters. During startup it is `initializing` and Google's map may be partial or empty. `completed` means the core callback finished, even when an adapter is `not_ready`; an initialization exception reports `failed`. The query does not initialize SDKs or request ads. Neither absence from this map nor `ready` establishes installed-module inventory, valid accounts, credentials or ad delivery. See the [complete contract](api-reference.md#mediation-diagnostics).
+
+New providers need no core registration. Follow [Adding a network](contributing.md#adding-a-network) to package an existing official adapter.
+
+After initialization on a registered test device, inspect actual requests:
+
+```js
+Admob.addEventListener('ad_inspector_closed', event => {
+  Ti.API.info(JSON.stringify(event))
+})
+Admob.openAdInspector()
+```
+
+## Privacy and bundled resources
+
+Continue using UMP and `canRequestAds()` before requests. Each selected iOS complement includes its vendor resources and privacy manifests. Review the current Google/provider guidance for SKAdNetwork entries, privacy disclosures and consent propagation for the networks the application distributes. Android resolves each selected adapter's SDK transitively through its POM.
+
+The public example and the test demo use only the core, with no mediation flag. No provider credentials are required to run Google demo ads. Adding a selected complement to `tiapp.xml` makes its adapter discoverable at SDK startup; configure the provider account and AdMob mapping before using that network. Automatic discovery does not validate credentials or eliminate initialization timeouts.
+
+## Release validation
+
+Build all discovered modules (two ZIPs per module) and inspect their framework inventories and generated POMs. Compile isolated consumer applications on both platforms with core only, each of the five complements individually, AppLovin + Unity, and all five together. Check that no framework is duplicated and that resolved dependency versions remain pinned.
+
+Record separately:
+
+- Integration and linking: the build succeeds, expected adapter classes are visible, and official Google test ads load.
+- Provider ad delivery: the provider returns its own test ad with valid publisher accounts and AdMob mappings, confirmed by single-source testing in Ad Inspector.
+
+Google test ads do not prove provider delivery. iOS simulator results do not substitute for device results. Re-run device validation when hardware is available. Do not use or click production ads during development.
+
+## Unity consent with the pinned adapter
+
+The distribution uses Unity adapter `4.20.1.0` on both platforms. It includes the automatic forwarding of `IABTCF_AddtlConsent` introduced in `4.19.0.1` on [Android](https://developers.google.com/admob/android/mediation/unity) and [iOS](https://developers.google.com/admob/ios/mediation/unity). Configure Unity as a consent partner and verify signal propagation with the provider before enabling demand. Adapter presence and a Google test ad do not establish provider consent or delivery.

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

@@ -0,0 +1,255 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at commit `5b4cbf9` (copied 2026-10-11). Relative links rebased for this skill.
+
+# Migrating to ti.admob.unified
+
+This guide covers adopting the first release, `1.0.0`, from a platform-specific AdMob module or an internal development build. There are no previously published versions of this module.
+
+## Selecting mediation dependencies
+
+Install only the core for Google ads. If the application mediates, install a complement for each selected network. For example:
+
+```xml
+<modules>
+  <module version="1.0.0">ti.admob.unified</module>
+  <module version="1.0.0">ti.admob.unified.mediation.applovin</module>
+</modules>
+```
+
+The aggregate development package is not part of this release. Replace its declaration with the desired per-network modules. `getMediationStatus()` now reports Google initialization states through `{ initializationState, adapters }`; it does not validate mappings or delivery. ironSource mediation is deferred. See [AdMob mediation](mediation.md).
+
+## If you used an internal pre-release build
+
+Internal ZIPs exposed API differences that never reached a published release. Update code that depends on them as follows.
+
+### Generic mediation diagnostics
+
+Replace reads of the old six-Boolean map (for example `status.appLovin`) with iteration over `Admob.getMediationStatus().adapters` after `module_initialized`. Use `initializationState` for the core process and each entry's `state` for Google's adapter report. There is no portable provider-key mapping: native class names differ between iOS and Android. Before startup the array is empty; during startup it may be partial. A `ready` entry does not prove account configuration or ad delivery.
+
+Remove calls to `isAppLovinAvailable`, `isMetaAvailable`, `isInMobiAvailable`, `isVungleAvailable`, `isUnityAvailable`, `isIronSourceAvailable` and `enableOptionalMediationNetworks`. Also remove `setAppLovinGDPRConsent`, `setInMobiGDPRConsent` and `setVungleGDPRConsent`; those pre-release setters only logged warnings. Continue using UMP and each provider's documented consent requirements. `disableMediation` and the `module_initialized` payload are unchanged.
+
+### There is no `COLLAPSIBLE_TOP` or `COLLAPSIBLE_BOTTOM`
+
+Neither constant is exported. Reading it returns `undefined`; passing `Admob.COLLAPSIBLE_TOP` therefore sends `undefined` to the native layer.
+
+They used to hold `"collapsible_top"` and `"collapsible_bottom"`. Google's SDK accepts only `"top"` and `"bottom"`, and the module forwarded the value unchanged, so every request built from those constants was invalid.
+
+The `collapsible` property itself is unchanged and now works on both platforms. It takes Google's native string:
+
+```js
+const banner = Admob.createAdaptiveBanner({
+  adUnitId: Admob.TEST_ADAPTIVE_BANNER,
+  collapsible: 'bottom'
+})
+```
+
+### `smart_banner` no longer produces a full-width banner on iOS
+
+Google removed the size on Android and deprecated it on iOS. Internal builds selected a fixed 320×50 banner on Android and a full-width strip on iOS. The value now falls back to `BANNER` on both platforms, like any other unrecognised size.
+
+Android behaviour is unaffected. On iOS, a placement that relied on `adSize: 'smart_banner'` for a full-width strip now renders a 320×50 banner.
+
+The replacement is `customAdSize`, which both platforms accept:
+
+```js
+function screenWidthInDp() {
+  const caps = Ti.Platform.displayCaps
+
+  if (Ti.Platform.osname === 'android') {
+    return Math.round(caps.platformWidth / caps.logicalDensityFactor)
+  }
+
+  return Math.round(caps.platformWidth)
+}
+
+const banner = Admob.createBanner({
+  adUnitId: Admob.TEST_BANNER,
+  customAdSize: { width: screenWidthInDp(), height: 50 },
+  width: Ti.UI.FILL
+})
+```
+
+`createAdaptiveBanner()` is the other option when Google should choose the height. See [Standard banner properties](banners.md#creation-properties-1).
+
+### Legacy privacy methods no longer gate ads
+
+`canShowPersonalizedAds()` always returns `false` and `canShowAds()` is an alias of `canRequestAds()`. Code that branched on either one has to move to the single gate described below.
+
+## Module declaration
+
+Replace platform-specific or older AdMob modules with one declaration:
+
+```xml
+<modules>
+  <module version="1.0.0">ti.admob.unified</module>
+</modules>
+```
+
+Add the selected network complements only if the application mediates; for example, `<module version="1.0.0">ti.admob.unified.mediation.applovin</module>` for AppLovin.
+
+Update JavaScript imports:
+
+```js
+const Admob = require('ti.admob.unified')
+```
+
+Install both local artifacts when the app targets iOS and Android.
+
+## Move the application ID to `tiapp.xml`
+
+Remove `applicationId` from JavaScript initialization. Configure `GADApplicationIdentifier` on iOS and `com.google.android.gms.ads.APPLICATION_ID` on Android as described in [Getting started](getting-started.md).
+
+## Replace privacy gates
+
+Before:
+
+```js
+if (Admob.canShowPersonalizedAds() || !Admob.isGDPR()) {
+  loadAds()
+}
+```
+
+After:
+
+```js
+if (Admob.canRequestAds()) {
+  loadAds()
+}
+```
+
+Do not consume:
+
+- `canShowPersonalizedAds()`
+- `isGDPR()`
+- `canShowAds()`
+- `consent_ready`
+- `consent_error`
+- legacy payload aliases such as `isPrivacyOptionsRequired`
+
+Use `consent_complete`, `canRequestAds`, and `privacyOptionsRequired`.
+
+## Replace callback-style consent code
+
+The supported contract is event-based:
+
+```js
+Admob.addEventListener('consent_complete', onConsentComplete)
+Admob.requestConsent({})
+```
+
+Callback properties passed inside the config object are not invoked.
+
+## Request UMP before initialization
+
+The recommended order is:
+
+```text
+UMP -> canRequestAds -> initialize -> load ads
+```
+
+Use that same sequence on both platforms. Do not initialize before UMP has updated the current session.
+
+App Tracking Transparency is optional and sits outside this sequence. If your application has its own tracking case, resolve it before `initialize()`; it is not an ad-request gate, and `canRequestAds()` remains the only one. The call is portable: iOS resolves ATT, and Android emits `tracking_authorization_completed` immediately with `applicable: false`.
+
+## Adopt adaptive banner sizing
+
+Replace fixed full-width or smart-banner assumptions:
+
+```js
+const banner = Admob.createAdaptiveBanner({
+  adUnitId: Admob.TEST_ADAPTIVE_BANNER,
+  adaptiveType: Admob.ADAPTIVE_ANCHORED,
+  width: Ti.UI.FILL
+})
+```
+
+On `loaded`, use `event.height` with `event.heightUnit`. Update both the banner host and the adjacent content inset. Collapse both on error and destruction.
+
+Do not keep a fixed `50`, `90`, or device-specific height.
+
+`ADAPTIVE_INLINE` and `maxHeight` work on iOS too. An application that branched on `Ti.Platform.osname` to keep inline banners off iOS can drop the branch.
+
+## Adopt the banner lifecycle
+
+Both standard and adaptive banners support:
+
+```js
+banner.load()
+banner.pause()
+banner.resume()
+banner.isLoaded()
+banner.destroy()
+```
+
+`destroy()` is terminal and idempotent. Remove JavaScript event listeners and the proxy from its parent when the owning placement closes.
+
+The module pauses banners when the Android activity pauses or the iOS application enters the background. Remove any application code that duplicates those handlers. Keep calls for navigation changes the module cannot observe, such as hiding a tab or covering a window. See [Who pauses a banner](banners.md#who-pauses-a-banner).
+
+Do not carry forward code that changes `visible`, opacity, height, or the banner host during pause/resume. TiAdMobUnified preserves the same visual slot and creative; navigation owns only the application pause cause.
+
+Replace both historical aliases when practical:
+
+```js
+banner.destroyAdViewAndCancelRequest()
+banner.destoyAdViewAndCancelRequest()
+```
+
+with:
+
+```js
+banner.destroy()
+```
+
+## Remove manual refresh timers
+
+Delete `setTimeout`/`setInterval` banner renewal loops. Configure refresh in AdMob and let the native SDK own it.
+
+The application issues the initial `load()`. Google Mobile Ads manages later refresh requests; TiAdMobUnified manages lifecycle.
+
+## Adopt the fullscreen lifecycle
+
+Interstitial, rewarded, and app open proxies share the same methods and event payloads on iOS and Android:
+
+```js
+fullscreen.load()
+fullscreen.show()
+fullscreen.isLoaded()
+fullscreen.destroy()
+```
+
+Calls to `load()` while a request, loaded ad, or presentation is active are ignored. Each native fullscreen ad is single-use. `destroy()` is terminal and idempotent, and emits `destroyed` once.
+
+Common events include `adUnitId` and `adType`; failures add `error`, `message`, and `code`. Both platforms emit `opened` and `showed_fullscreen_content`. Rewarded value must be granted only from the `rewarded` event.
+
+### App open
+
+`createAppOpen()` returns a proxy on both platforms. Of the modules it replaces, `ti.admob` documents the iOS type without a factory, and `ti.android.admob` supplies an Android-only proxy. Applications previously had to implement the missing iOS support themselves.
+
+It follows the fullscreen contract above, with one addition: an app open ad expires four hours after the request. Past that point `isLoaded()` reports `false` and `show()` emits `failed_to_show` with code `1`. See [The four hour window](fullscreen.md#the-four-hour-window).
+
+## Mediation
+
+Five optional complements carry AppLovin, Meta, InMobi, Unity and Liftoff dependencies on both platforms. Google Mobile Ads discovers their adapters; applications keep calling the core factories. ironSource mediation is deferred.
+
+Availability probes remain in `ti.admob.unified` for portable diagnostics, and report `false` for every network when no complements are installed. Legacy provider consent setters are deprecated no-ops because UMP and each provider's current requirements must drive privacy configuration. Installing an adapter does not create an account or enable a mediation source: configure mappings and credentials in AdMob, then validate with Ad Inspector.
+
+An application that serves AdMob demand only leaves the complements out and uses `Admob.initialize({})`, with no disabling flag. Including selected complements opts into automatic adapter discovery; no `enableMediation` flag is needed. An exceptional session that skips installed adapters is covered in the [initialization reference](api-reference.md#automatic-adapter-discovery).
+
+## Development checklist
+
+- Use the module's `TEST_*` constants.
+- Keep production IDs disabled until physical validation is complete.
+- Test consent accepted, rejected, not required, and previous-session states.
+- Test ATT authorized, denied, and previously resolved on iOS.
+- Test banner load, error collapse, rotation, background/resume, and repeated window close.
+- Test interstitial, rewarded, and app open duplicate loads, show failures, close, reward delivery, and repeated destruction.
+- Confirm no duplicate banners or retained listeners.
+- Inspect requests with Ad Inspector.
+- Inspect `getMediationStatus()` after `module_initialized`, and verify installed complements separately through package inventories and Ad Inspector.
+- Run `npm test` and `./scripts/verify-artifacts.sh`.
+
+
+## Corrections from internal audit builds
+
+Boolean results and payload fields use JavaScript Booleans on both platforms; replace comparisons to numeric `0` or `1`. iOS load errors now use the shared error constants; presentation, UMP and Inspector codes remain domain-specific. Use the event name and the reference's error table when migrating code that compared raw NSError values.
+
+Application volume now works on iOS using the same percentage string accepted on Android. Fullscreen configuration properties are mutable for subsequent loads on both platforms. Native helper/delegate methods and internal state from earlier iOS builds are no longer exposed as application APIs. Availability diagnostics require the adapter class, so a network SDK installed without its adapter reports `false`.