@maccesar/titools 5.1.1 → 5.2.0

package/skills/ti-admob-unified/references/dependencies.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.
+
+# Dependency inventory
+
+The core and five optional complements use the published versions verified on September 23, 2026. Each module has its own iOS Podfile, lockfile and framework checksum inventory. Android pins live in each module’s `android/build.gradle`.
+
+## iOS vendored XCFrameworks: `ti.admob.unified`
+
+| Component               | Framework                           |  Version |
+| ----------------------- | ----------------------------------- | -------: |
+| Google Mobile Ads       | `GoogleMobileAds.xcframework`       | `13.10.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.20.1 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.4.1.0` |
+| InMobi SDK                | `InMobiSDK.xcframework`              |     `11.4.1` |
+| Unity adapter             | `UnityAdapter.xcframework`           |   `4.20.1.0` |
+| Unity Ads SDK             | `UnityAds.xcframework`               |     `4.20.1` |
+| Unity support library     | `UnityCoherenceLib.xcframework`      |      `0.1.0` |
+| Liftoff Monetize adapter  | `LiftoffMonetizeAdapter.xcframework` |    `7.7.7.0` |
+| Vungle Ads SDK            | `VungleAdsSDK.xcframework`           |      `7.7.7` |
+
+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.7 on iOS and 7.7.8 on Android. The version contract test retains this remaining difference and checks the matching networks.
+
+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.1-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.4.1.2 |
+| `com.google.ads.mediation:unity`    | 4.20.1.0 |
+| `com.google.ads.mediation:applovin` | 13.6.4.2 |
+| `com.google.ads.mediation:vungle`   | 7.7.8.1 |
+
+Each complement declares one adapter coordinate. InMobi and Liftoff also pin OkHttp 4.12.0. This replaces InMobi’s 3.14.9 and lifts Liftoff’s Okio dependency above the affected 3.0.0 release while retaining the okhttp3 API. Generated POMs propagate these versions and the matching network SDK into the consuming application. The core POM declares GMA, UMP and a patched Guava utility dependency. Guava replaces the older transitive version; it adds no ad network. Inspect all six POMs and resolved consumer dependency graphs before release.
+
+## 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 September 23, 2026 refresh checks resolved dependencies for all eight Android consumer combinations. Updating the ad adapters alone still selected older utility libraries, so the distributed POMs include these corrections:
+
+| Dependency | Previous resolution | Updated resolution | Where the pin lives |
+| --- | --- | --- | --- |
+| Guava | `31.1-android` in core and several combinations | `33.7.1-android` | Core Android module |
+| OkHttp | `3.14.9` with InMobi; `4.10.0` with Liftoff | `4.12.0` | InMobi and Liftoff Android complements |
+| Okio / Okio-jvm | `3.0.0` with Liftoff | At least `3.6.0`, through OkHttp; InMobi selects `3.7.0` | Resolved transitively |
+
+Guava's Android variant requires API 24, matching this module's existing floor. [Guava release notes](https://github.com/google/guava/releases/tag/v33.7.1) identify the published Android artifact. [OkHttp 4's compatibility guide](https://lysine.dev/okhttp/changelogs/upgrading_to_okhttp_4/) documents binary compatibility with the okhttp3 API; its [4.x changelog](https://lysine.dev/okhttp/changelogs/changelog_4x/) records the hostname-verification fix and Okio update. These are utility dependencies, not additional ad networks.
+
+The earlier matches were `GHSA-5mg8-w23w-74h3`, `GHSA-7g45-4rm6-3mm3` (Guava), `GHSA-3cqm-mf7h-prrj` (OkHttp) and `GHSA-w33c-445m-f8w7` (Okio). The final [OSV querybatch](https://google.github.io/osv.dev/api/) scan covered 149 distinct Maven name/version pairs across all eight consumer combinations and returned no matches on September 23, 2026. A version scan does not establish provider delivery or prove that every internal SDK path is safe.
+
+Unity `4.20.1.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,223 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at commit `5b4cbf9` (copied 2026-10-11). Relative links rebased for this skill.
+
+# Fullscreen ads
+
+Interstitial, rewarded 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. Presenting inside the `loaded` listener lets network timing determine when the user is interrupted.
+
+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()` to reward users for watching ads. Interstitials must not offer rewards.
+- Avoid consecutive interstitials and excessive frequency. Configure frequency capping on the ad unit in the AdMob console; JavaScript does not control it.
+
+The full lists are 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.
+
+## 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()
+```
+
+Closing a rewarded ad is not proof that the reward was earned.
+
+## 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 onApplicationResumed() {
+  if (appOpen && appOpen.isLoaded()) {
+    appOpen.show()
+  }
+}
+```
+
+### The four hour window
+
+Google documents that an app open ad expires four hours after it was requested. An ad rendered later is no longer valid and may not earn revenue, so the proxy enforces the window itself, with no timer and no extra event:
+
+- 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 three 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 the five configuration properties affect the next request on both platforms. An already loaded ad keeps the configuration of its original request.
+
+## 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. After a presentation or a show failure the proxy holds no ad: its native reference is cleared and `isLoaded()` turns `false`. 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 | Common payload                                     |
+| --------------------------- | -----------: | -------: | -------: | -------------------------------------------------- |
+| `loaded`                    |          Yes |      Yes |      Yes | `adUnitId`, `adType`                               |
+| `failed_to_load`            |          Yes |      Yes |      Yes | `adUnitId`, `adType`, `error`, `message`, `code`   |
+| `opened`                    |          Yes |      Yes |      Yes | `adUnitId`, `adType`                               |
+| `showed_fullscreen_content` |          Yes |      Yes |      Yes | `adUnitId`, `adType`                               |
+| `closed`                    |          Yes |      Yes |      Yes | `adUnitId`, `adType`                               |
+| `clicked`                   |          Yes |      Yes |      Yes | `adUnitId`, `adType`                               |
+| `impression`                |          Yes |      Yes |      Yes | `adUnitId`, `adType`                               |
+| `failed_to_show`            |          Yes |      Yes |      Yes | `adUnitId`, `adType`, `error`, `message`, `code`   |
+| `destroyed`                 |          Yes |      Yes |      Yes | `adUnitId`, `adType`                               |
+| `rewarded`                  |           No |      Yes |       No | `adUnitId`, `adType`, `rewardType`, `rewardAmount` |
+
+`message` duplicates `error` for compatibility. New code may use `error`; both keys are portable.
+
+## 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:
+
+- Rewarded interstitial
+- Native
+
+`TEST_REWARDED_INTERSTITIAL` and `TEST_NATIVE` name units no factory accepts.

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

@@ -0,0 +1,17 @@
+# Game monetization and module integration
+
+Use the official `fullscreen.md`, `privacy.md` and `library.md` contract for calls. This reference adds product/lifecycle criteria, not a second module API. The detailed asset-to-game coordination guide is `ti-game-assets/references/responsible-ads.md` when that skill is available; this skill works independently of it.
+
+## Community-Discovered Patterns
+
+These are author guidance and integration lessons from Lander/Guardian, not additional module API or a verified optimal monetization policy. Preserve this section during official-doc refreshes and re-evaluate its lifecycle claims against current builds.
+
+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 only the application decides to show; reaching a time threshold makes a later boundary eligible, never a timer-based interruption. Current [Google guidance](https://support.google.com/admob/answer/6201362?hl=en) disallows unexpected and excessive interstitial placements; re-check it before a live change.
+
+The ad boundary must suspend/release native motion and sound as appropriate. A stopped JS tick does not stop native gravity. Resume only the intended scene after an actual dismissal or confirmed show failure. One director owns presentation, protects against simultaneous attempts, and discards continuations after the screen/session closes. Timeouts may handle missing opening; they must not resume gameplay behind a confirmed open ad. A background/resume or late load callback does not start a missed ad.
+
+Keep grace period, active-play accumulation, cooldown after dismissal, hourly/daily caps and permitted boundaries distinct. Count actual openings once and track close separately. Preserve persistence and conservative handling of clock rollback. Lander and Guardian implement this separation, but their numeric thresholds are initial settings without evidence of an optimum; do not transplant them into every game. Caps are ceilings, not exposure targets. Application eligibility is separate from the network's AdMob frequency cap.
+
+Use test IDs and the official consent-first flow. Banners need layout away from controls; rewarded ads need an explicit voluntary offer, a real reward and one grant from the documented rewarded event. Interstitials are not rewarded ads. Do not add forced rewarded continues, App Open or a new format without product scope. The module's implemented formats and roadmap determine what is possible.
+
+Test unavailable module, no fill, load/show failures, repeated taps, late/duplicate callbacks, real close, background/resume, destruction and phone/tablet layout on both platforms. An SDK opening/impression does not prove the creative was visible: physical visual acceptance is separate. Measure confirmed exposure per active-play minute, abandonment at ad boundaries and retention/retries where telemetry is authorized; unit tests do not prove players enjoy the frequency.

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

@@ -0,0 +1,275 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at commit `5b4cbf9` (copied 2026-10-11). Relative links rebased for this skill.
+
+# Getting started
+
+## 1. Install the modules
+
+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: about 14 MB on iOS and 325 KB on Android, with no third-party network SDKs in the build.
+
+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 current baselines are Titanium `13.2.0.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
+```
+
+They are not interchangeable. The application ID belongs in `tiapp.xml`; ad unit IDs are supplied to ad factories such as `createAdaptiveBanner()`.
+
+### 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. Most banner applications do not need it: 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>
+```
+
+Omit that key entirely if the application never calls `requestTrackingAuthorization()`. UMP still runs and still shows the consent form where the region requires one; the two mechanisms are unrelated.
+
+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. Two formats have no implemented 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` | None. Reserved; the format is not implemented     |
+| `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')
+  } else {
+    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.
+
+An application that does request it waits for the Apple prompt to settle before initializing, so that the SDK reads a final tracking status:
+
+```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 is not a permission request and does not open Apple's prompt: only `requestTrackingAuthorization()` does.
+
+`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
+
+A banner needs a host view that is already in the hierarchy, so the native view can measure its real width.
+
+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 colour that matches the screen, so the empty slot looks like a bottom margin:
+
+```js
+const bannerHost = Ti.UI.createView({
+  left: 0,
+  right: 0,
+  bottom: 0,
+  height: '50dp'
+})
+
+if (Admob.canRequestAds()) {
+  const banner = Admob.createAdaptiveBanner({
+    adUnitId: Admob.TEST_ADAPTIVE_BANNER,
+    adaptiveType: Admob.ADAPTIVE_ANCHORED,
+    width: Ti.UI.FILL
+  })
+
+  banner.addEventListener(Admob.AD_LOADED, event => {
+    bannerHost.height = `${event.height}dp`
+  })
+
+  bannerHost.add(banner)
+  banner.load()
+}
+```
+
+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.
+
+## 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,30 @@
+> Source snapshot: official ti.admob.unified 1.0.0 documentation at commit `5b4cbf9` (copied 2026-10-11). 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, and app open ads on one lifecycle, and when it is acceptable to interrupt the user.
+
+## 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)