admanagekit-mcp-server 1.2.0 → 1.2.2

package/content/docs/release-notes/RELEASE_NOTES_v4.4.3.md

@@ -0,0 +1,121 @@
+# Release Notes — v4.4.3
+
+**Release Date:** 2026-08-15
+
+## Overview
+
+v4.4.3 is a bug-fix and dependency release. No API was added, removed or changed. Two of the fixes are silent-failure bugs that cost real money:
+
+- **A rewarded load the manager had given up on could sabotage the load that replaced it** — throwing away an ad that had just arrived, and clearing the "loading" flag out from under a request that was still running.
+- **Billing could stop acknowledging purchases for the rest of the process**, which lets Play auto-refund a completed purchase on day 3.
+
+It also picks up the Next-Gen GMA SDK **1.3.1**, Yandex Mobile Ads **8.3.0**, and refreshed AndroidX/Firebase/Compose BOMs.
+
+Upgrading is a drop-in from 4.4.x.
+
+---
+
+## Fixed
+
+### A timed-out rewarded load could sabotage the one that replaced it
+
+`RewardedAdManager.loadRewardedAdWithTimeout(...)` stops waiting for a load once its timeout elapses — but a request handed to the SDK **cannot be cancelled**, so it keeps running and reports back whenever it finishes. Its callbacks then ran the full success/failure path as though they still spoke for the manager, even though a replacement load had started in the meantime.
+
+Concretely, a late callback from an abandoned request could:
+
+- **Throw away a perfectly good ad.** The failure path ran `rewardedAd = null` unconditionally, so a stale failure discarded an ad a *later* load had just delivered. The next `showAd()` found nothing and skipped the reward.
+- **Clear `isLoading` out from under the load that was still running**, so the manager reported itself idle while a request was in flight — letting a duplicate load start and burning an extra ad request.
+- **Fail callers queued behind a load that had not finished yet**, via `notifyPendingLoadFailure`.
+- **Schedule a retry for a request nobody was waiting on.**
+
+Every load path now claims a generation token and checks it before touching anything shared — the same mechanism `RewardedWaterfall` already used internally. A stale callback answers *its own* caller (which is still owed a result and has no other source of one) and otherwise leaves shared state alone.
+
+A late ad is **kept rather than dropped**: it is real and showable no matter which request produced it, so it is adopted for the next show whenever nothing better is already in hand. This applies to both the AdMob path and the waterfall path.
+
+Two related unconditional writes were tightened at the same time:
+
+- The direct load's failure path no longer does `rewardedAd = null` at all. A failed request means *this* request produced nothing — not that an ad obtained elsewhere has stopped being showable.
+- The waterfall failure path now clears `rewardedWaterfall` only when the chain being reported on is still the one it installed (`if (rewardedWaterfall === waterfall)`), so a newer load's chain — or a late chain adopted in the meantime — is not discarded by an older failure.
+
+> This is the same class of bug as the v4.4.2 `AdManager` duplicate-callback fix, in the one manager that still resolved in-flight state with plain flags.
+
+### Billing could stop acknowledging purchases for the rest of the process
+
+`AppPurchase` gated every re-query on `isServiceConnected`, an `AtomicBoolean` written **only** by `onBillingSetupFinished` and cleared by `onBillingServiceDisconnected`.
+
+The library enables `enableAutoServiceReconnection()`, and the SDK restores the connection on its own without necessarily re-firing `onBillingSetupFinished`. So after a single disconnect the flag could stay `false` permanently — while the client itself was perfectly ready — silently disabling:
+
+- `verifyPurchased(...)` and `updatePurchaseStatus()` — entitlement re-checks
+- `refreshPurchases(...)` — including **the acknowledgment retry**
+- `consumePurchase(...)`, `queryProductDetails(...)`
+- `connectToGooglePlayBilling()`, which skipped reconnecting because it believed it was still connected
+
+That last one matters most: **Play auto-refunds any purchase left unacknowledged for 3 days.** A user who bought while the flag was stuck could be charged, granted the entitlement, and then silently refunded — with the app still treating them as a paying customer.
+
+All of these now consult the client's own live state (`billingClient.isReady()`) instead of the latched flag. `onBillingServiceDisconnected` also stops clearing `isBillingAvailable`: the client *was* set up successfully, and `isAvailable()` ANDs that fact with the live readiness check, so it now reports `false` only while the service is actually down rather than latching `false` for the rest of the process.
+
+### Acknowledgment required the purchase to match a configured product id
+
+In both `verifyPurchased(...)` and `updatePurchaseStatus()`, `acknowledgePurchaseIfNeeded(purchase)` was called *inside* the loop that matched the purchase against `inAppProductIdList` / `subProductIdList`. A `PURCHASED` order whose id the current build does not list was never acknowledged — and so was auto-refunded on day 3.
+
+That is not a hypothetical set: promo-code grants, products dropped from a newer release, a Play Console id typo, and a user who purchased on a build that configured more ids than the one they are running now all land here.
+
+Acknowledgment now happens **before** the id match, unconditionally for every `PURCHASED` purchase. Entitlement still requires a configured id — only the acknowledgment was decoupled, since the 3-day clock does not care whether your build recognises the product.
+
+---
+
+## Dependencies
+
+| Dependency | 4.4.2 | 4.4.3 |
+| --- | --- | --- |
+| Google Mobile Ads Next-Gen SDK | 1.3.0 | **1.3.1** |
+| Yandex Mobile Ads | 8.2.0 | **8.3.0** |
+| Compose BOM | 2026.06.01 | **2026.08.00** |
+| Firebase BOM | 34.15.0 | **34.17.0** |
+| AndroidX AppCompat | 1.7.1 | **1.8.0** |
+| ConstraintLayout | 2.2.1 | **2.2.2** |
+| org.json (test only) | 20250517 | **20260719** |
+
+Google Play Billing stays at **9.1.0** and Kotlin at **2.2.10**.
+
+### Sample app now compiles at JVM 17
+
+The `app` sample module was the only module still pinned to `jvmTarget = "1.8"`, while all five published modules use 17. Compose BOM 2026.08.00 ships artifacts compiled at JVM 11+, which cannot be inlined into 1.8 bytecode — so the bump broke `assembleDebug` on the sample with `Cannot inline bytecode built with JVM target 11 into bytecode that is being built with JVM target 1.8`.
+
+The sample now uses `VERSION_17` / `jvmTarget = "17"`, matching the library modules. **This does not affect the published artifacts** — their compile options were already 17 and are unchanged. It is noted here only because anyone building the repo from source would otherwise hit it.
+
+---
+
+## Documentation
+
+`docs/APP_PURCHASE_GUIDE.md` now documents what pending purchases require from the host app. A pending order (cash, bank transfer, parental approval) can complete hours or days later while the app is closed; `onPurchasesUpdated` only fires if the app happens to be running, so Play requires apps to re-query owned purchases on every foreground. `AppPurchase` queries on billing init, and if the process survives the transition that never runs again — so the guide now shows calling `refreshPurchases()` from the main activity's `onResume()`, and explains that this is what stops a completed pending order from being auto-cancelled on day 3.
+
+---
+
+## Verification
+
+`assembleDebug` succeeds and `testDebugUnitTest --rerun-tasks` passes **176 tests, 0 failures** — 173 existing plus 3 new `RewardedAdManagerStaleLoadTest` cases pinning down the stale-load contract:
+
+- an abandoned load's failure must not discard an ad another load produced
+- an abandoned load's failure must not clear the replacement's `isLoading`
+- an ad arriving after the timeout is kept for the next show rather than dropped
+
+The tests drive the waterfall path, whose providers are fakes the test can complete by hand; the AdMob path runs the same generation checks over a static SDK entry point.
+
+The billing changes are **not** covered by automated tests — both depend on `BillingClient` connection-state transitions that the existing `ProductDetailsFactory`-based harness cannot drive. They were verified by reading every call site of `isServiceConnected` and every `acknowledgePurchaseIfNeeded` path; on-device verification against a Play test track is recommended.
+
+---
+
+## Upgrading
+
+Drop-in from 4.4.x. No source changes required.
+
+If your app relies on pending purchases, add the `onResume()` refresh described under [Documentation](#documentation) — the library cannot do this for you, since it does not own your activity lifecycle.
+
+```groovy
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.3'
+```

package/content/wiki/Ad-Loading-Strategies.md

@@ -1,8 +1,8 @@
-# Ad Loading Strategies - AdManageKit v2.8.0
+# Ad Loading Strategies - AdManageKit v4.4.3
 
 ## Overview
 
-AdManageKit v2.6.0+ introduces three loading strategies that control how ads are fetched and displayed. Choose the right strategy based on your app's needs for user experience vs. ad coverage.
+AdManageKit v2.6.0+ introduces four loading strategies that control how ads are fetched and displayed. Choose the right strategy based on your app's needs for user experience vs. ad coverage.
 
 ## Strategy Types
 
@@ -63,15 +63,33 @@ AdManageKitConfig.interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
 - Default recommendation
 - Balanced UX and coverage
 
+### 4. FRESH_WITH_CACHE_FALLBACK
+
+**Fetch fresh first, fall back to cache on failure**
+
+```kotlin
+AdManageKitConfig.nativeLoadingStrategy = AdLoadingStrategy.FRESH_WITH_CACHE_FALLBACK
+```
+
+| Pros | Cons |
+|------|------|
+| Freshest creative when the network cooperates | Slower than cache-first when the fetch is slow |
+| Cache covers the failure case | Requires a warm cache to help |
+| Successful loads are cached for later | - |
+
+**Best for:**
+- RecyclerView / feed scenarios where each item should try for a fresh ad
+- Placements where creative freshness matters more than instant fill
+
 ## Strategy Availability
 
-| Ad Type | ON_DEMAND | ONLY_CACHE | HYBRID |
-|---------|-----------|------------|--------|
-| Interstitial | ✅ | ✅ | ✅ |
-| App Open | ✅ | ✅ | ✅ |
-| Native | ✅ | ❌ | ✅ |
+| Ad Type | ON_DEMAND | ONLY_CACHE | HYBRID | FRESH_WITH_CACHE_FALLBACK |
+|---------|-----------|------------|--------|---------------------------|
+| Interstitial | ✅ | ✅ | ✅ | ✅ |
+| App Open | ✅ | ✅ | ✅ | ✅ |
+| Native | ✅ | ✅ | ✅ | ✅ |
 
-> **Note:** Native ads use shimmer instead of dialog, so ONLY_CACHE hides container if not cached.
+> **Note:** Native ads use shimmer instead of a dialog, so `ONLY_CACHE` hides the container when nothing is cached rather than blocking the UI.
 
 ## Configuration
 

package/content/wiki/App-Open-Ads.md

@@ -1,10 +1,10 @@
-# App Open Ads - AdManageKit v4.3.5
+# App Open Ads - AdManageKit v4.4.3
 
 ## Overview
 
 AdManageKit provides lifecycle-aware app open ad management through `AppOpenManager`. App open ads display when users launch or return to your app, with support for loading strategies, ad freshness enforcement, welcome dialogs, activity/screen exclusion, and the multi-provider waterfall.
 
-**Library Version**: v4.3.5
+**Library Version**: v4.4.3
 
 ## Features
 
@@ -23,9 +23,9 @@ AdManageKit provides lifecycle-aware app open ad management through `AppOpenMana
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.3.5'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.3.5'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.3.5'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.3'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.3'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
 }
 ```
 

package/content/wiki/Banner-Ads.md

@@ -1,10 +1,10 @@
-# Banner Ads - AdManageKit v4.3.5
+# Banner Ads - AdManageKit v4.4.3
 
 ## Overview
 
 AdManageKit provides `BannerAdView` for banner ad integration with every standard AdMob size, adaptive banners, collapsible banners, a size-aware loading shimmer, auto-refresh, and smart retry logic.
 
-**Library Version**: v4.3.5
+**Library Version**: v4.4.3
 
 ## Features
 
@@ -23,8 +23,8 @@ AdManageKit provides `BannerAdView` for banner ad integration with every standar
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.3.5'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.3.5'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.3'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
 }
 ```
 

package/content/wiki/Billing-Integration.md

@@ -7,8 +7,8 @@ AdManageKit provides a comprehensive billing integration module (`admanagekit-bi
 ### 1. Add Dependency
 
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.0'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
 ```
 
 ### 2. Define Products
@@ -52,6 +52,24 @@ class MyApp : Application() {
 > Only `PurchaseState.PURCHASED` grants entitlement (pending purchases do not).
 > Consumables still require a manual `consumePurchase(productId)` after granting.
 
+> **Pending purchases need one thing from you (v4.4.3).** A pending order (cash,
+> bank transfer, parental approval) can complete hours or days later, while your
+> app is closed. `onPurchasesUpdated` only fires if the app happens to be
+> running, so Play requires apps to re-query owned purchases on every foreground.
+> `AppPurchase` queries on billing init; if your process stays alive across the
+> transition, that never runs again — so call `refreshPurchases()` from your main
+> activity's `onResume()`:
+>
+> ```kotlin
+> override fun onResume() {
+>     super.onResume()
+>     AppPurchase.getInstance().refreshPurchases()
+> }
+> ```
+>
+> It acknowledges every unacknowledged `PURCHASED` purchase it finds, which is
+> what stops a completed pending order from being auto-cancelled on day 3.
+
 ### 4. Make Purchases
 
 ```kotlin

package/content/wiki/Configuration.md

@@ -1,4 +1,4 @@
-# Configuration - AdManageKit v2.8.0
+# Configuration - AdManageKit v4.4.3
 
 ## Overview
 
@@ -32,6 +32,8 @@ class MyApp : Application() {
 }
 ```
 
+> **Since 4.2.0 you must also call `MobileAds.initialize()` yourself**, before any ad request — the Next-Gen SDK removed the legacy SDK's silent lazy-init. `AdManageKitConfig` only configures this library's behavior; it does not initialize the ads SDK. See [[Home]] for the initialization pattern.
+
 ## All Configuration Options
 
 ### Performance Settings
@@ -138,6 +140,28 @@ AdManageKitConfig.apply {
 }
 ```
 
+### Native Ad Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `nativeLoadingStrategy` | Loading strategy | HYBRID |
+| `nativeCacheExpiry` | Cache expiry for native ads | 1 hour |
+| `defaultNativeMediaAspect` | Media aspect-ratio hint sent with every native request (v4.3.3+) | ANY |
+| `nativeVideoStartMuted` | Start video creatives muted (v4.3.3+) | true |
+| `nativeVideoClickToExpand` | Allow click-to-expand on video creatives (v4.3.3+) | false |
+| `nativeVideoCustomControls` | Request custom video controls (v4.3.3+) | false |
+
+`NativeMediaAspect` values: `UNSPECIFIED`, `ANY`, `LANDSCAPE`, `PORTRAIT`, `SQUARE`. `NativeTemplateView.setMediaAspect(...)` overrides the global default per view.
+
+```kotlin
+AdManageKitConfig.apply {
+    nativeLoadingStrategy = AdLoadingStrategy.HYBRID
+    nativeCacheExpiry = 1.hours
+    defaultNativeMediaAspect = NativeMediaAspect.ANY
+    nativeVideoStartMuted = true
+}
+```
+
 ### App Open Settings
 
 | Setting | Description | Default |

package/content/wiki/Home.md

@@ -1,18 +1,35 @@
 # AdManageKit
 
 [![JitPack](https://jitpack.io/v/i2hammad/AdManageKit.svg)](https://jitpack.io/#i2hammad/AdManageKit)
-![API](https://img.shields.io/badge/API-21%2B-brightgreen.svg?style=flat)
+![API](https://img.shields.io/badge/API-24%2B-brightgreen.svg?style=flat)
 ![License](https://img.shields.io/badge/License-MIT-blue.svg)
 
 AdManageKit is a comprehensive Android library designed to simplify the integration and management of Google AdMob ads, Google Play Billing, and User Messaging Platform (UMP) consent.
 
-**Latest Version: `2.8.0`**
+**Latest Version: `4.4.3`**
 
-## What's New in 2.8.0
+## What's New in 4.4.3
 
-- **Loading Strategy for AdManager**: `forceShowInterstitial()` now respects global loading strategy
-- **Global Auto-Reload Config**: New `interstitialAutoReload` setting with per-call override
-- **New Method**: `forceShowInterstitialAlways()` for explicit force fetch behavior
+Bug-fix and dependency release, no API changes. Two silent-failure bugs, both of which cost money.
+
+- **A timed-out rewarded load could sabotage the one that replaced it** — a request handed to the SDK cannot be cancelled, and when it finally reported back it could discard an ad a *newer* load had just delivered, clear the loading flag out from under a request still in flight, and fail callers waiting on a load that had not finished. Every load path now carries a generation token, and a late ad is kept for the next show instead of dropped
+- **Billing could stop acknowledging purchases for the rest of the process** — the connection flag could latch `false` after one disconnect while the client was actually ready, disabling every purchase re-query including the acknowledgment retry. Play auto-refunds an unacknowledged purchase after 3 days
+- **Acknowledgment no longer requires a configured product id** — a `PURCHASED` order the current build does not list (promo grants, dropped products, a Console typo) was never acknowledged, and so was auto-refunded on day 3
+- **Dependencies** — Next-Gen GMA SDK 1.3.1, Yandex Mobile Ads 8.3.0, Compose BOM 2026.08.00, Firebase BOM 34.17.0, AppCompat 1.8.0
+
+> **Pending purchases need one thing from your app:** call `refreshPurchases()` from your main activity's `onResume()`. See [[Billing Integration]].
+
+## Recent Highlights
+
+- **4.4.2** — Rewarded callbacks marshalled to the main thread (they could crash the app), a completed purchase could fail to disable ads, blank gaps where banner/native slots should have collapsed, and a `BannerAdView` Activity leak. Behavior changes: an account-hold subscription no longer disables ads, and premium users no longer reserve ad space in Compose
+- **4.4.1** — Google Mobile Ads Next-Gen SDK 1.3.0 (from 1.2.1), plus repairs to API doc generation and the MCP documentation server
+- **4.4.0** — Subscription offers can be **purchased individually** (`subscribe(activity, offer)`), offer lookup by id/base plan/tag, cross-cadence price normalization (`BillingPeriod`, `getSavingsPercent`), trial eligibility, Play Billing 9 one-time product offers, and client-side **account hold** detection. See [[Subscription Offers]]
+- **4.3.x** — All standard banner sizes (`BannerAdSize`), custom native templates, and app-open ad freshness enforcement
+- **4.2.0** — Migrated to the Google Mobile Ads **Next-Gen SDK** and Play Billing 9. `MobileAds.initialize()` must now be called explicitly before any ad request
+
+> Upgrading from 3.x or earlier? Read the [Migrating to 4.2.0](https://github.com/i2hammad/AdManageKit#migrating-to-420) notes first — it is the one release in the 4.x line that is not source-compatible.
+
+Full details: [Changelog](https://github.com/i2hammad/AdManageKit/blob/main/CHANGELOG.md) · [Release Notes](https://github.com/i2hammad/AdManageKit/tree/main/docs/release-notes)
 
 ## Features
 
@@ -23,14 +40,16 @@ AdManageKit is a comprehensive Android library designed to simplify the integrat
 - **App Open Ads**: Lifecycle-aware with activity exclusion
 
 ### NativeTemplateView (v2.6.0+)
-- 17 Template Styles: card_modern, material3, minimal, list_item, magazine, video templates
+- 38 Template Styles: card_modern, material3, minimal, list_item, magazine, app_store, social_feed, spotlight, plus the video_* and flat_* families
 - XML & Programmatic: Set templates via `app:adTemplate` or `setTemplate()`
+- Custom Templates (v4.3.0+): supply your own layout via `setCustomTemplate()` or `app:customAdLayout`
 - Material 3 Theming: Automatic dark/light mode support
 
 ### Ad Loading Strategies (v2.6.0+)
 - **ON_DEMAND**: Fetch fresh ads with loading dialog
 - **ONLY_CACHE**: Instant display from cache
 - **HYBRID**: Cache-first with fallback fetch (recommended)
+- **FRESH_WITH_CACHE_FALLBACK**: Fetch fresh, fall back to cache on failure
 
 ### Centralized Configuration
 - **AdManageKitConfig**: Single configuration point
@@ -65,27 +84,39 @@ dependencyResolutionManagement {
 **Step 2:** Add dependencies to your app's `build.gradle`:
 
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v2.8.0'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v2.8.0'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v2.8.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
 
 // For Jetpack Compose support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v2.8.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.3'
+
+// For Yandex Ads multi-provider support
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.3'
 ```
 
-**Step 3:** Sync your project with Gradle.
+**Step 3:** Ensure your app's `compileSdk` is **37 or higher** (required transitively as of 4.2.0).
+
+**Step 4:** Sync your project with Gradle.
 
 ### Quick Configuration
 
 Configure AdManageKit in your Application class:
 
+> **Since 4.2.0 you must call `MobileAds.initialize()` yourself.** The Next-Gen SDK removed the legacy SDK's silent lazy-init, so an app that skips it never loads ads. AdManageKit does not call it for you, because it does not own your consent flow.
+
 ```kotlin
 class MyApp : Application() {
-    private lateinit var appOpenManager: AppOpenManager
+    var appOpenManager: AppOpenManager? = null
 
     override fun onCreate() {
         super.onCreate()
 
+        initAds()
+
+        // Set up billing
+        BillingConfig.setPurchaseProvider(BillingPurchaseProvider())
+
         // Configure AdManageKit
         AdManageKitConfig.apply {
             debugMode = BuildConfig.DEBUG
@@ -100,16 +131,29 @@ class MyApp : Application() {
             // Auto-reload interstitial after showing
             interstitialAutoReload = true  // default: true
         }
+    }
 
-        // Set up billing
-        BillingConfig.setPurchaseProvider(BillingPurchaseProvider())
-
-        // Initialize app open ads
-        appOpenManager = AppOpenManager(this, "your-app-open-ad-unit-id")
+    private fun initAds() {
+        val config = InitializationConfig.Builder(readApplicationIdFromManifest()).build()
+
+        // initialize() blocks, so keep it off the main thread or it can ANR.
+        Thread {
+            MobileAds.initialize(this, config)
+
+            // Construct AppOpenManager only after initialize() returns. Constructing it
+            // arms its ProcessLifecycleOwner observer, and onStart() fires as soon as any
+            // activity starts — created earlier, that observer can race ahead of
+            // initialization and issue a load the Next-Gen SDK rejects as "not initialized".
+            Handler(Looper.getMainLooper()).post {
+                appOpenManager = AppOpenManager(this, "your-app-open-ad-unit-id")
+            }
+        }.start()
     }
 }
 ```
 
+The Next-Gen SDK no longer reads the application id from the manifest automatically, so `readApplicationIdFromManifest()` pulls `com.google.android.gms.ads.APPLICATION_ID` from your `ApplicationInfo` metadata. See the sample app's [`MyApplication.kt`](https://github.com/i2hammad/AdManageKit/blob/main/app/src/main/java/com/i2hammad/admanagekit/sample/MyApplication.kt) for the full version.
+
 ## Wiki Pages
 
 ### Ad Types
@@ -128,6 +172,14 @@ class MyApp : Application() {
 - [[Multi-Provider Waterfall]] - Load ads from multiple networks with automatic fallback
 - [[Yandex Integration]] - Yandex Ads SDK provider setup and configuration
 
+### Billing
+- [[Billing Integration]] - Play Billing setup, products, and purchase flows
+- [[Purchase Categories]] - Product type classification
+- [[Consumable Products]] - Consumable in-app purchases
+- [[Subscriptions]] - Subscription state, renewal, and account hold
+- [[Subscription Offers]] - Multi-offer paywalls, price comparison, trial eligibility
+- [[Subscription Upgrades]] - Plan changes and proration modes
+
 ## Sample Project
 
 The `app` module demonstrates all features. To run:

package/content/wiki/Interstitial-Ads.md

@@ -1,10 +1,10 @@
-# Interstitial Ads - AdManageKit v2.8.0
+# Interstitial Ads - AdManageKit v4.4.3
 
 ## Overview
 
 AdManageKit provides a complete interstitial ad stack with `AdManager` and the fluent `InterstitialAdBuilder`. Features include loading strategies, automatic retry, frequency controls, splash screen support, and Jetpack Compose utilities.
 
-**Library Version**: v2.8.0
+**Library Version**: v4.4.3
 
 ## What's New
 
@@ -23,11 +23,11 @@ AdManageKit provides a complete interstitial ad stack with `AdManager` and the f
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v2.8.0'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v2.8.0'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v2.8.0'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.3'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.3'
     // Optional - Jetpack Compose
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v2.8.0'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.3'
 }
 ```
 
@@ -58,6 +58,8 @@ class MyApp : Application() {
 }
 ```
 
+> **Since 4.2.0 you must also call `MobileAds.initialize()` yourself**, before any ad request — the Next-Gen SDK removed the legacy SDK's silent lazy-init. This snippet covers configuration only. See [[Home]] or the sample app's [`MyApplication.kt`](https://github.com/i2hammad/AdManageKit/blob/main/app/src/main/java/com/i2hammad/admanagekit/sample/MyApplication.kt) for the initialization pattern.
+
 ## Option 1: Direct AdManager
 
 ### Basic Usage
@@ -104,6 +106,7 @@ fun showInterstitial(activity: Activity) {
 | ON_DEMAND | Always fetch fresh ad with dialog |
 | ONLY_CACHE | Show cached if ready, skip otherwise |
 | HYBRID | Show cached if ready, fetch fresh otherwise |
+| FRESH_WITH_CACHE_FALLBACK | Fetch fresh, fall back to cache if the load fails |
 
 ```kotlin
 // Set strategy

package/content/wiki/Jetpack-Compose.md

@@ -1,18 +1,18 @@
-# Jetpack Compose Integration - AdManageKit v2.8.0
+# Jetpack Compose Integration - AdManageKit v4.4.3
 
 ## Overview
 
 AdManageKit provides first-class Jetpack Compose support with composable functions for all ad types, state management helpers, and programmatic native ad loading.
 
-**Library Version**: v2.8.0
+**Library Version**: v4.4.3
 
 ## Installation
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v2.8.0'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v2.8.0'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v2.8.0'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.3'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.3'
 }
 ```
 
@@ -60,6 +60,27 @@ fun MyScreen() {
 }
 ```
 
+### Custom Templates & Shimmer (v4.3.0+)
+
+If none of the 38 built-in templates fit, pass your own layout instead of a `template`:
+
+```kotlin
+NativeTemplateCompose(
+    adUnitId = "ca-app-pub-xxx/yyy",
+    customLayoutResId = R.layout.my_native_ad,
+    customShimmerResId = R.layout.my_native_ad_shimmer,  // recommended, see below
+    customSizeHint = NativeAdSize.MEDIUM
+)
+```
+
+`customLayoutResId` takes precedence over `template`. The layout's root must be (or inflate as) a Next-Gen SDK `NativeAdView`, reusing the standard asset ids so the library can bind them: `ad_headline`, `ad_body`, `ad_call_to_action`, `ad_app_icon`, `ad_advertiser`, `ad_media`, `ad_stars`, `ad_choices_view`. Omitted ids are simply not populated, but keep the call-to-action fully visible and tappable — the native ad validator flags clipping as a policy violation.
+
+> **`customShimmerResId` is optional, but omitting it is rarely what you want.** The shimmer then falls back to the one belonging to `template` (default `CARD_MODERN`), so a custom layout still shows a placeholder — just one shaped like a different ad, which visibly jumps when the real ad arrives. Either supply a matching shimmer, or set `template` to whichever built-in most resembles your layout so the fallback is the right shape. Passing `0` is the same as omitting it.
+
+`customSizeHint` classifies the ad for the cache and gives the Yandex waterfall a fallback size, since a custom layout has no built-in size bucket — `SMALL` (icon + title + CTA), `MEDIUM` (adds body), `LARGE` (adds media). It does not affect how your layout is measured.
+
+The XML and programmatic equivalents are covered in [[Native Ads|NativeAdManager]].
+
 ### Traditional Native Composables
 
 ```kotlin

package/content/wiki/Multi-Provider-Waterfall.md

@@ -38,11 +38,11 @@ This is fully backward compatible -- if no provider chains are configured, all e
 
 ```groovy
 dependencies {
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit:VERSION"
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-core:VERSION"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.3"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3"
 
     // Add Yandex provider
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:VERSION"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.3"
 }
 ```
 
@@ -161,7 +161,7 @@ if (isRussia) {
 All existing features continue to work when the waterfall is active:
 
 - Time-based and count-based interstitial display
-- Loading strategies (ON_DEMAND, ONLY_CACHE, HYBRID)
+- Loading strategies (ON_DEMAND, ONLY_CACHE, HYBRID, FRESH_WITH_CACHE_FALLBACK)
 - Shimmer loading placeholders
 - Loading dialogs for interstitials
 - Welcome back dialog for app open ads