@maccesar/titools 5.1.1 → 5.2.1

package/skills/ti-admob-unified/references/getting-started.md

@@ -0,0 +1,319 @@
+> 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.
+
+# Getting started
+
+<!-- TOC-START -->
+## Contents
+
+- [1. Install the modules](#1-install-the-modules)
+- [2. Configure the AdMob application IDs](#2-configure-the-admob-application-ids)
+- [3. Configure mediation if needed](#3-configure-mediation-if-needed)
+- [4. Configure Privacy & messaging](#4-configure-privacy--messaging)
+- [5. Use official test units](#5-use-official-test-units)
+- [6. Request consent, then initialize](#6-request-consent-then-initialize)
+- [7. Create an ad only after the gate opens](#7-create-an-ad-only-after-the-gate-opens)
+- [Common setup mistakes](#common-setup-mistakes)
+- [Before shipping](#before-shipping)
+- [Example appearance](#example-appearance)
+
+<!-- TOC-END -->
+
+## 1. Install the modules
+
+Download the core archives from [GitHub Releases](https://github.com/macCesar/ti.admob.unified/releases). Use `ti.admob.unified-iphone-1.0.0.zip` for iOS and `ti.admob.unified-android-1.0.0.zip` for Android. Extract each ZIP at your Titanium application's root, keeping the archive's `modules/` directory. The resulting manifests must be at `modules/iphone/ti.admob.unified/1.0.0/manifest` and `modules/android/ti.admob.unified/1.0.0/manifest`. Do not add another nested `modules/` directory.
+
+Install the `1.0.0` ZIP of `ti.admob.unified` for every platform you build. All artifacts of a given module must have the same module ID and version:
+
+```xml
+<modules>
+  <module version="1.0.0">ti.admob.unified</module>
+</modules>
+```
+
+An application that serves AdMob demand needs only the core. Android resolves its Maven dependencies during the consumer build, so the module ZIP size is not the installed app-size cost. CocoaPods and the framework installer scripts are for building this repository, not for applications installing its release ZIPs.
+
+If the application mediates, install the selected per-network complements at the same version. For AppLovin:
+
+```xml
+<modules>
+  <module version="1.0.0">ti.admob.unified</module>
+  <module version="1.0.0">ti.admob.unified.mediation.applovin</module>
+</modules>
+```
+
+Each complement carries one adapter and its dependencies, with no JavaScript API. Add a module line for each intended network; leave unneeded networks out. See [AdMob mediation](mediation.md).
+
+The minimum versions are Titanium `13.4.1.GA`, iOS `15.0+`, and Android API `24+`.
+
+For an existing AdMob integration, see [Migrating to ti.admob.unified](migration.md).
+
+## 2. Configure the AdMob application IDs
+
+An AdMob **application ID** contains a tilde:
+
+```text
+ca-app-pub-0000000000000000~0000000000
+```
+
+An **ad unit ID** contains a slash:
+
+```text
+ca-app-pub-0000000000000000/0000000000
+```
+
+Put the application ID in `tiapp.xml` and pass ad unit IDs to factories such as `createAdaptiveBanner()`. Each field requires its own ID type.
+
+### iOS
+
+Add the iOS application ID to the app plist section:
+
+```xml
+<ios>
+  <plist>
+    <dict>
+      <key>GADApplicationIdentifier</key>
+      <string>ca-app-pub-0000000000000000~0000000000</string>
+    </dict>
+  </plist>
+</ios>
+```
+
+App Tracking Transparency is optional and separate from UMP. Serving ads does not require tracking users across other companies' apps and websites. Add the usage description only when the application uses tracking, and describe that use accurately. Apple reviews the prompt against the app's behavior.
+
+```xml
+<ios>
+  <plist>
+    <dict>
+      <key>NSUserTrackingUsageDescription</key>
+      <string>This identifier helps us measure advertising performance.</string>
+    </dict>
+  </plist>
+</ios>
+```
+
+Include this key whenever the app or an included SDK requests ATT, including an IDFA message configured in AdMob UMP. Omit it only when the app and its SDK configuration never request ATT and do not perform tracking. UMP regional consent can run without ATT.
+
+The usage description is the explanation shown in Apple's ATT prompt. Localize it with `i18n/<language>/app.xml` in the consumer app, using the `NSUserTrackingUsageDescription` string name. Provide an English value and a translation for each supported language, including Spanish when the app supports it. This applies to Classic and Alloy projects; verify that the built app contains `<language>.lproj/InfoPlist.strings` with those values.
+
+```xml
+<resources>
+  <string name="NSUserTrackingUsageDescription">This identifier helps us measure advertising performance.</string>
+</resources>
+```
+
+These settings serve separate purposes:
+
+- `NSUserTrackingUsageDescription` and its translations explain the ATT request. They do not request permission by themselves.
+- `GADApplicationIdentifier` identifies the iOS app to AdMob. It is required even when ATT is disabled.
+- `SKAdNetworkItems` configures attribution identifiers. It does not grant ATT permission.
+- App Store Connect privacy disclosures describe the app's actual collection and tracking, including its SDKs. They must match the integration; a plist entry does not complete those disclosures. See Apple's [privacy and data use guidance](https://developer.apple.com/app-store/user-privacy-and-data-use/).
+
+A successful App Store review of another integration is a reference, not a promise that Apple will approve this app. Review depends on its behavior, configuration and disclosures.
+
+Keep any required `SKAdNetworkItems` in the consuming app. Follow Google's [iOS setup guide](https://developers.google.com/admob/ios/quick-start) for the current list and App Store requirements.
+
+### Android
+
+Merge the Android application ID into the application element:
+
+```xml
+<android xmlns:android="http://schemas.android.com/apk/res/android">
+  <manifest>
+    <application>
+      <meta-data
+        android:name="com.google.android.gms.ads.APPLICATION_ID"
+        android:value="ca-app-pub-0000000000000000~0000000000"/>
+    </application>
+  </manifest>
+</android>
+```
+
+Omitting this metadata causes the native Google Mobile Ads SDK to fail with a missing application ID. See Google's [Android setup guide](https://developers.google.com/admob/android/quick-start).
+
+Do not pass `applicationId` to `initialize()`; the module does not consume that property.
+
+## 3. Configure mediation if needed
+
+Skip this step unless the application already has, or is about to have, an AdMob mediation group with real ad sources in it. Installing adapters does not raise fill on its own: a network participates only once its publisher account is approved, it is added as an ad source, and its credentials are mapped to the ad unit.
+
+Install the corresponding complements from step 1 when the application will mediate. AppLovin, Meta, InMobi, Unity and Liftoff are available on both platforms; ironSource mediation is deferred. Add the intended networks to the AdMob mediation groups and complete their account, placement, privacy and store-disclosure setup.
+
+No platform-specific JavaScript or manual adapter initialization is required. After `module_initialized`, use `getMediationStatus()` to inspect the adapter states reported by Google; check package contents separately. See [AdMob mediation](mediation.md).
+
+### Automatic adapter discovery
+
+After the privacy gate, use `Admob.initialize({})` with either the core alone or selected complements. Google discovers the adapters included by `tiapp.xml`; no mediation flag or manual provider initialization is required.
+
+Install only networks with the intended accounts and AdMob mappings configured. An installed adapter with incomplete configuration may delay startup until it responds or times out. For exceptional sessions that deliberately skip installed adapters, see the [initialization reference](api-reference.md#automatic-adapter-discovery).
+
+## 4. Configure Privacy & messaging
+
+Create the required messages in the **Privacy & messaging** section of the AdMob console. UMP resolves the message configuration from the application ID in the consuming app.
+
+The application must request a fresh consent-information update on every launch. See [Privacy and initialization](privacy.md) before loading any ad.
+
+## 5. Use official test units
+
+The `TEST_*` constants resolve to Google's platform-specific demo ad unit IDs:
+
+```js
+const Admob = require('ti.admob.unified')
+
+const adaptiveId = Admob.TEST_ADAPTIVE_BANNER
+const interstitialId = Admob.TEST_INTERSTITIAL
+const rewardedId = Admob.TEST_REWARDED
+```
+
+The module exports the full set of test constants for compatibility. Native remains reserved without a factory:
+
+| Constant                     | Factory that accepts it                           |
+| ---------------------------- | ------------------------------------------------- |
+| `TEST_BANNER`                | `createBanner()`                                  |
+| `TEST_ADAPTIVE_BANNER`       | `createAdaptiveBanner()`                          |
+| `TEST_INTERSTITIAL`          | `createInterstitial()`                            |
+| `TEST_INTERSTITIAL_VIDEO`    | `createInterstitial()` (same API, video creative) |
+| `TEST_REWARDED`              | `createRewarded()`                                |
+| `TEST_REWARDED_INTERSTITIAL` | `createRewardedInterstitial()`                    |
+| `TEST_NATIVE`                | None. Reserved; the format is not implemented     |
+| `TEST_APP_OPEN`              | `createAppOpen()`                                 |
+
+See [Reserved and unavailable APIs](api-reference.md#reserved-and-unavailable-apis).
+
+Do not copy an Android demo ID into an iOS branch or the reverse. Let the module constant select the correct ID.
+
+Google recommends demo units or explicitly registered test devices during development. See the official [Android test-ad guide](https://developers.google.com/admob/android/test-ads) and [iOS test-ad guide](https://developers.google.com/admob/ios/test-ads).
+
+## 6. Request consent, then initialize
+
+Register all listeners first:
+
+```js
+const Admob = require('ti.admob.unified')
+
+let initialized = false
+
+function initializeOnce() {
+  if (initialized || !Admob.canRequestAds()) {
+    return
+  }
+
+  initialized = true
+  Admob.initialize({
+    ageRestrictedTreatment: Admob.AGE_RESTRICTED_TREATMENT_UNSPECIFIED,
+    maxAdContentRating: Admob.MAX_AD_CONTENT_RATING_GENERAL
+  })
+}
+
+Admob.addEventListener('module_initialized', event => {
+  if (event.success) {
+    Ti.API.info('Google Mobile Ads initialized')
+    // Create/load placements here, after initialization succeeds.
+  } else {
+    initialized = false // allow a later app-controlled retry
+    Ti.API.warn(`Google Mobile Ads initialization failed: ${event.error}`)
+  }
+})
+
+Admob.addEventListener('consent_complete', event => {
+  if (event.canRequestAds) {
+    initializeOnce()
+  }
+})
+
+Admob.requestConsent({
+  tagForUnderAgeOfConsent: false
+})
+```
+
+### Optional: if the application requests ATT
+
+Skip this section unless step 2 added `NSUserTrackingUsageDescription`. ATT is not a prerequisite for serving ads, and requesting it without a real tracking case invites an App Store rejection.
+
+Replace the `consent_complete` listener from step 6 with the listener below; do not register both. An application that requests ATT waits for the Apple prompt to settle before initializing, so that the SDK reads a final tracking status. Present it while the app is active and no other system prompt or consent form is onscreen:
+
+```js
+Admob.addEventListener('consent_complete', event => {
+  if (!event.canRequestAds) {
+    return
+  }
+
+  const onTrackingComplete = trackingEvent => {
+    Admob.removeEventListener(
+      'tracking_authorization_completed',
+      onTrackingComplete
+    )
+    Ti.API.info(`ATT status: ${trackingEvent.status}`)
+    initializeOnce()
+  }
+
+  Admob.addEventListener(
+    'tracking_authorization_completed',
+    onTrackingComplete
+  )
+  Admob.requestTrackingAuthorization()
+})
+```
+
+Google Mobile Ads reads `trackingAuthorizationStatus` on its own on iOS; that read does not open Apple's prompt. An IDFA message configured in AdMob can let UMP present ATT during `requestConsent()`. In that integration, keep the usage description and translations, let UMP finish, and use `getTrackingAuthorizationStatus()` to inspect the result. A separate explicit ATT request is unnecessary when UMP already handles it. See Google's [UMP IDFA message guide](https://developers.google.com/admob/ios/privacy/idfa).
+
+`initialize()` and `requestConsent()` are idempotent native operations. Application-level guards are still useful because cached terminal events may be emitted again when a caller invokes an already-completed operation.
+
+## 7. Create an ad only after the gate opens
+
+For a complete first banner, use the integration library below **instead of the raw startup listeners in step 6**. It runs the same consent/initialization sequence and waits for a real layout. Keep `const Admob = require('ti.admob.unified')` from step 5. Choose one startup owner for the app.
+
+Reserve the host height before the ad arrives. Growing it from zero when `loaded` fires moves surrounding content after the screen appears. Give the host its expected height and a background color that matches the screen. The empty slot then looks like a bottom margin:
+
+```js
+// Classic Titanium; copy example/lib/ads.js into Resources/lib/ first.
+// Alloy: copy to app/lib/ads.js and use require('ads').
+const ads = require('lib/ads')
+const win = Ti.UI.createWindow({ backgroundColor: '#ffffff' })
+const content = Ti.UI.createView({ top: 0, left: 0, right: 0, bottom: 0 })
+const bannerHost = Ti.UI.createView({ left: 0, right: 0, bottom: 0, height: '50dp' })
+win.add(content)
+win.add(bannerHost)
+
+const banner = ads.createAdaptiveBanner({
+  host: bannerHost,
+  content,
+  reservedHeight: 50,
+  adUnitId: Admob.TEST_ADAPTIVE_BANNER,
+  adaptiveType: Admob.ADAPTIVE_ANCHORED
+})
+
+win.addEventListener('close', event => {
+  if (!event._closeFromActivityForcedToDestroy) banner.destroy()
+})
+win.open()
+ads.start({ consent: { tagForUnderAgeOfConsent: false } }).catch(error => {
+  Ti.API.warn(`Ads startup failed: ${error.message || error}`)
+})
+```
+
+A fixed `BANNER` is `50dp` and `FULLBANNER` is `60dp`, so a fixed-size placement can reserve its exact height. An adaptive banner reports its final height after loading. Reserve a suitable minimum, then adjust it in the loaded event to avoid growing the host from zero.
+
+[Banner ads](banners.md) covers the full placement contract: reserving layout space without overlapping bottom-aligned UI, the named-listener lifecycle, and `pause()` / `resume()` / `destroy()`.
+
+The module does not enforce the privacy gate inside ad proxies. The consuming application owns the order.
+
+## Common setup mistakes
+
+- Passing an ad unit ID where an application ID is required.
+- Passing `applicationId` or `debugGeography` to `initialize()`.
+- Loading ads before `consent_complete` and `canRequestAds === true`.
+- Using `canShowPersonalizedAds()` or `isGDPR()` as a gate.
+- Hardcoding an adaptive banner height.
+- Keeping banner listeners after destroying or removing a placement.
+- Using a production ad unit while clicking ads during development.
+- Requesting ATT, or shipping `NSUserTrackingUsageDescription`, in an app with no tracking case. UMP does not require either one.
+- Installing mediation complements without configured ad sources adds SDK size and may delay startup while unused networks time out.
+- Publishing an app that is supposed to mediate without the selected complements installed, which must be checked through package inventories and Ad Inspector; an empty diagnostic map alone is not an installation check.
+
+## Before shipping
+
+Follow [Shipping an application](production.md) for production configuration, app-ads.txt, store disclosures, validation and troubleshooting.
+
+## Example appearance
+
+For the classic playground, copy `example/app.js` and `example/semantic.colors.json` into `Resources/`, and `example/lib/ads.js` into `Resources/lib/`. The named colors provide light and dark variants for the content and window title. Keep the default DayNight Android theme so system icons follow the selected appearance. The sample keeps the title and status bars visible. Changing appearance does not require rebuilding the ad proxies or resetting the scroll position.

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

@@ -0,0 +1,33 @@
+> 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.
+
+# ti.admob.unified documentation
+
+This documentation describes the public JavaScript contract implemented by `ti.admob.unified` `1.0.0`.
+
+## Start here
+
+1. [Getting started](getting-started.md): install the platform artifacts, configure the AdMob application IDs, and make a first test request.
+2. [Integrating the module](integration.md): the boundary between native lifecycle, application navigation, layout, and refresh ownership.
+3. [Copy-ready JavaScript library](library.md): copy one maintained file into `lib/` for startup, every implemented ad format, privacy, and cleanup.
+4. [Privacy and initialization](privacy.md): implement UMP, ATT, the `canRequestAds()` gate, and privacy options correctly.
+5. [AdMob mediation](mediation.md): install selected complements, and configure and validate the five networks without platform-specific JavaScript.
+6. [Banner ads](banners.md): integrate standard or adaptive banners with real layout space and deterministic cleanup.
+7. [Fullscreen ads](fullscreen.md): interstitial, rewarded, rewarded interstitial, and app open ads on one lifecycle, and when it is acceptable to interrupt the user.
+
+8. [Rewarded interstitial ads](rewarded-interstitial.md): introduce the reward, allow skipping, and handle actual earned rewards.
+9. [Shipping an application](production.md): production configuration, app verification, store disclosures, troubleshooting and validation.
+
+## Reference
+
+- [Complete API reference](api-reference.md): module methods, proxy methods, events, payloads, constants, compatibility APIs, and platform notes.
+- [Migrating to ti.admob.unified](migration.md): replace `ti.admob`, `ti.android.admob`, or an internal pre-release build.
+- [Third-party SDK notices](third-party-notices.md): licenses and terms for the distributed advertising SDKs.
+
+- [Adding a network](contributing.md#adding-a-network): package and validate an existing official mediation adapter.
+
+## Project information
+
+- [Dependency inventory](dependencies.md)
+- [Changelog](module-changelog.md)
+- [Roadmap](roadmap.md)
+- [Contributing](contributing.md)

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

@@ -0,0 +1,87 @@
+> 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.
+
+# Integrating the module
+
+The native module manages Google Mobile Ads, UMP, proxy behavior and host lifecycle on both platforms. Your application controls navigation, layout and which screen is visible.
+
+## Recommended path
+
+Copy [`example/lib/ads.js`](../assets/example/lib/ads.js) to `app/lib/ads.js` in Alloy or `Resources/lib/ads.js` in Classic Titanium. It supports every format in version `1.0.0` and handles startup, placement lifecycle and cleanup.
+
+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()
+showSameActivityOverlay()
+
+function onOverlayDismissed() {
+  banner.resume()
+}
+```
+
+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)
+- [Shipping an application](production.md)

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

@@ -0,0 +1,220 @@
+> 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.
+
+# 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`
+
+Import it from an Alloy controller with `require('ads')`, or from Classic Titanium with `require('lib/ads')`:
+
+```js
+const Admob = require('ti.admob.unified')
+const ads = require('lib/ads') // Classic; Alloy: require('ads')
+```
+
+Alloy copies `app/lib/ads.js` to the generated Resources root. Keep that import distinction when adapting the Classic examples.
+
+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()`                 |
+| Rewarded interstitial | `createRewardedInterstitial()` | `load()`, `show()`, `retry()`, `isLoaded()`, `destroy()` |
+| App open        | `createAppOpen()`        | `load()`, `show()`, `retry()`, `isLoaded()`, `destroy()`                 |
+
+Native ads have no factory in version `1.0.0`. For rewarded interstitials, show an introduction with a skip option before calling the manager's `show()`; see [Rewarded interstitial ads](rewarded-interstitial.md).
+
+## 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')
+  }
+}).catch(error => {
+  Ti.API.warn(`Ads startup failed: ${error.message || error}`)
+})
+```
+
+Set `requestTrackingAuthorization: true` only when the application has a real ATT use case and a valid `NSUserTrackingUsageDescription`. This option controls only the library's explicit ATT request. An IDFA message configured in AdMob may let UMP present ATT during the consent step even when this option is false. When UMP handles ATT, leave the option false and retain the required description/translations. The startup result's `tracking` value describes the explicit request only; query `Admob.getTrackingAuthorizationStatus()` for current system state. ATT is not another ad-request gate. Call `start()` from the active foreground after other prompts have closed. If an iOS interruption occurs during UMP, the library waits for `Ti.App.resumed` before requesting ATT, then removes its temporary lifecycle listeners. It does not coordinate unrelated prompts opened by application code.
+
+Use `Admob.getTrackingAuthorizationStatus()` to inspect ATT without prompting, including after a return from Settings. The same method works in Classic and Alloy. Android reports `applicable: false`; its `authorized: true` convention does not grant general tracking permission.
+
+`start()` caches its promise for the JavaScript session, including an unavailable result. Repeating it does not retry a failed consent update or initialization. If the app needs a recoverable startup retry UI, use the [raw event-based flow](privacy.md#requestconsentconfig), which supports consent retries; do not call `resetConsent()` in production. Native invocation exceptions are converted into failure results by the library; inspect `result.initialized` and the result events. Catch errors in application promise callbacks as well.
+
+## 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. Banner managers start their first request automatically when the gate and layout are ready; there is no public banner-manager `load()` method. 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.
+
+### Banner manager options
+
+Alongside the native banner properties, the library accepts:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `host` | Required | Permanent Titanium container for the banner. |
+| `content` | Omitted | Adjacent composite-layout view whose bottom inset follows the slot. |
+| `reservedHeight` | Required | Positive initial reservation in dp. |
+| `paused` | `false` | Defer the first request until `resume()`. |
+| `collapseOnFailure` | `true` | Set to `false` to preserve the slot on a load failure. |
+| `onLoaded`, `onFailedToLoad`, `onDestroyed` | Omitted | Placement lifecycle callbacks receiving the event. |
+| `onClicked`, `onImpression`, `onOpened`, `onClosed` | Omitted | Forwarded native event callbacks. |
+
+Keep the options object stable. Managers do not expose the raw proxy's mutable properties; use a new manager when changing configuration. `rebuild()` recreates the proxy from the manager's existing options, and `retry()` does the same for a failed placement. `destroy()` removes the placement and collapses its slot.
+
+## Fullscreen ads
+
+Create the placement once. Load before the intended break and show it when the application reaches that break:
+
+```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 records that window's 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. The callback can return the window itself (preferred) or a measured `{ width, height }` size. For a window, the guard compares valid outer `rect` bounds and falls back to `size` before layout. Transient Android client-area changes after dismissing an ad therefore keep a ready preload, while rotation and window resizing still invalidate it. This helper does not initialize the SDK or run consent. The playground adds a pending user request around this check so its Show button can wait for a replacement and present it without another tap. The manager API itself keeps the immediate Boolean return contract above; it does not queue a later presentation after returning `false`.
+
+`show()` returns `false` when no valid ad is ready. Do not delay navigation or user work waiting for a fullscreen request.
+
+### Fullscreen manager options and return values
+
+Pass the native creation properties plus `window` and optionally `autoLoad: true` to request the first ad automatically after startup. Otherwise call `load()`. `autoReload: true` requests another ad after close only. Managers forward `onLoaded`, `onFailedToLoad`, `onOpened`, `onShowed`, `onClosed`, `onClicked`, `onImpression`, `onFailedToShow`, `onDestroyed` and, for rewarded, `onRewarded`.
+
+`load()` and `retry()` report whether the manager accepted the call, not whether an ad arrived. `show()` reports whether presentation was attempted; native presentation may still fail and emit `onFailedToShow`. `isLoaded()` checks native readiness. These Boolean manager results differ from the raw proxy's `void` `load()` / `show()` methods.
+
+## 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 clear the operation's 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.