admanagekit-mcp-server 1.0.0

package/content/wiki/Configuration.md

@@ -0,0 +1,252 @@
+# Configuration - AdManageKit v2.8.0
+
+## Overview
+
+`AdManageKitConfig` is the central configuration object for all AdManageKit features. Configure it once in your `Application.onCreate()` and all ad components will respect these settings.
+
+## Basic Setup
+
+```kotlin
+class MyApp : Application() {
+    override fun onCreate() {
+        super.onCreate()
+
+        // Configure billing first
+        BillingConfig.setPurchaseProvider(BillingPurchaseProvider())
+
+        // Configure AdManageKit
+        AdManageKitConfig.apply {
+            // Debug settings
+            debugMode = BuildConfig.DEBUG
+            testMode = false
+
+            // Loading strategies
+            interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
+            appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+            nativeLoadingStrategy = AdLoadingStrategy.HYBRID
+
+            // Auto-reload (v2.8.0+)
+            interstitialAutoReload = true
+        }
+    }
+}
+```
+
+## All Configuration Options
+
+### Performance Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `defaultAdTimeout` | Timeout for ad loading | 15 seconds |
+| `nativeCacheExpiry` | Cache expiry for native ads | 1 hour |
+| `maxCachedAdsPerUnit` | Max cached ads per unit | 3 |
+
+```kotlin
+AdManageKitConfig.apply {
+    defaultAdTimeout = 15.seconds
+    nativeCacheExpiry = 1.hours
+    maxCachedAdsPerUnit = 3
+}
+```
+
+### Reliability Features
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `autoRetryFailedAds` | Enable auto retry | true |
+| `maxRetryAttempts` | Max retry attempts | 3 |
+| `circuitBreakerThreshold` | Failures before circuit trips | 5 |
+| `circuitBreakerResetTimeout` | Circuit reset timeout | 5 minutes |
+
+```kotlin
+AdManageKitConfig.apply {
+    autoRetryFailedAds = true
+    maxRetryAttempts = 3
+    circuitBreakerThreshold = 5
+    circuitBreakerResetTimeout = 300.seconds
+}
+```
+
+### Advanced Features
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `enableSmartPreloading` | Smart preload based on usage | false |
+| `enableAdaptiveIntervals` | Adjust intervals by success rate | false |
+| `enablePerformanceMetrics` | Enable metrics collection | false |
+| `enableAutoCacheCleanup` | Auto cleanup on low memory | true |
+
+```kotlin
+AdManageKitConfig.apply {
+    enableSmartPreloading = true
+    enableAdaptiveIntervals = true
+    enablePerformanceMetrics = BuildConfig.DEBUG
+    enableAutoCacheCleanup = true
+}
+```
+
+### Debug & Testing
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `debugMode` | Enable debug logging | false |
+| `testMode` | Use test ads | false |
+| `privacyCompliantMode` | GDPR/CCPA compliance | true |
+| `enableDebugOverlay` | Show debug overlay | false |
+
+```kotlin
+AdManageKitConfig.apply {
+    debugMode = BuildConfig.DEBUG
+    testMode = false
+    privacyCompliantMode = true
+    enableDebugOverlay = BuildConfig.DEBUG
+}
+```
+
+### Interstitial Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `defaultInterstitialInterval` | Time between ads | 15 seconds |
+| `interstitialAutoReload` | Auto-reload after show | true |
+| `interstitialLoadingStrategy` | Loading strategy | HYBRID |
+
+```kotlin
+AdManageKitConfig.apply {
+    defaultInterstitialInterval = 20.seconds
+    interstitialAutoReload = true
+    interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
+}
+```
+
+### Banner Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `defaultBannerRefreshInterval` | Banner refresh interval | 60 seconds |
+| `enableCollapsibleBannersByDefault` | Enable collapsible | false |
+| `defaultCollapsiblePlacement` | Collapsible position | BOTTOM |
+
+```kotlin
+AdManageKitConfig.apply {
+    defaultBannerRefreshInterval = 60.seconds
+    enableCollapsibleBannersByDefault = false
+    defaultCollapsiblePlacement = CollapsibleBannerPlacement.BOTTOM
+}
+```
+
+### App Open Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `appOpenAdTimeout` | Load timeout | 4 seconds |
+| `appOpenFetchFreshAd` | Disable prefetching | false |
+| `appOpenLoadingStrategy` | Loading strategy | HYBRID |
+
+```kotlin
+AdManageKitConfig.apply {
+    appOpenAdTimeout = 4.seconds
+    appOpenFetchFreshAd = false
+    appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+}
+```
+
+### Dialog Customization
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `dialogBackgroundColor` | Dialog background | transparent |
+| `dialogOverlayColor` | Overlay color | 50% black |
+| `dialogCardBackgroundColor` | Card background | theme default |
+| `welcomeDialogAppIcon` | App icon resource | 0 |
+| `welcomeDialogTitle` | Title text | "Welcome Back!" |
+| `welcomeDialogSubtitle` | Subtitle text | "Loading..." |
+| `welcomeDialogFooter` | Footer text | "Just a moment..." |
+| `welcomeDialogDismissDelay` | Dismiss delay | 0.8 seconds |
+| `loadingDialogTitle` | Interstitial title | "Loading Ad" |
+| `loadingDialogSubtitle` | Interstitial subtitle | "Please wait..." |
+
+```kotlin
+AdManageKitConfig.apply {
+    welcomeDialogAppIcon = R.mipmap.ic_launcher
+    welcomeDialogTitle = "Welcome Back!"
+    dialogOverlayColor = 0x80000000.toInt()
+}
+```
+
+### Cache Management
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `maxCacheMemoryMB` | Max cache memory | 200 MB |
+| `enableLRUEviction` | LRU cache eviction | true |
+| `cacheCleanupInterval` | Cleanup interval | 30 minutes |
+
+```kotlin
+AdManageKitConfig.apply {
+    maxCacheMemoryMB = 200
+    enableLRUEviction = true
+    cacheCleanupInterval = 30.seconds * 60
+}
+```
+
+### Network Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `enableExponentialBackoff` | Exponential retry | true |
+| `baseRetryDelay` | First retry delay | 1 second |
+| `maxRetryDelay` | Max retry delay | 30 seconds |
+
+```kotlin
+AdManageKitConfig.apply {
+    enableExponentialBackoff = true
+    baseRetryDelay = 1.seconds
+    maxRetryDelay = 30.seconds
+}
+```
+
+## Utility Methods
+
+### Reset to Defaults
+
+```kotlin
+AdManageKitConfig.resetToDefaults()
+```
+
+### Validate Configuration
+
+```kotlin
+val isValid = AdManageKitConfig.validate()
+// Logs warnings in debug mode for invalid settings
+```
+
+### Get Summary
+
+```kotlin
+val summary = AdManageKitConfig.getConfigSummary()
+Log.d("Config", summary)
+```
+
+### Production Ready Check
+
+```kotlin
+if (AdManageKitConfig.isProductionReady()) {
+    // Configuration is suitable for production
+}
+```
+
+## Best Practices
+
+1. **Configure early** - Set in `Application.onCreate()`
+2. **Use BuildConfig** - Set `debugMode = BuildConfig.DEBUG`
+3. **Validate before release** - Use `isProductionReady()`
+4. **Different strategies** - Use appropriate strategies per ad type
+5. **Privacy first** - Keep `privacyCompliantMode = true`
+
+## References
+
+- [GitHub Repository](https://github.com/i2hammad/AdManageKit)
+- [[Ad Loading Strategies]]
+- [[Interstitial Ads]]

package/content/wiki/Consumable-Products.md

@@ -0,0 +1,166 @@
+# Consumable Products
+
+Consumable products are items that users can purchase multiple times, such as virtual currency, power-ups, or credits.
+
+## Key Concept: Manual Consumption
+
+In v2.9.0+, consumables are **NOT auto-consumed**. You must manually call `consumePurchase()` after granting items to the user.
+
+## Why Manual Consumption?
+
+1. **Server verification**: Verify on your server before granting items
+2. **Error recovery**: If granting fails, you don't lose the purchase
+3. **Accurate tracking**: Track exactly when items are granted
+4. **Multi-quantity**: Handle quantity > 1 correctly
+
+## Implementation
+
+### 1. Define Consumable Products
+
+```kotlin
+val products = listOf(
+    PurchaseItem("coins_100", TYPE_IAP.PURCHASE, PurchaseCategory.CONSUMABLE),
+    PurchaseItem("coins_500", TYPE_IAP.PURCHASE, PurchaseCategory.CONSUMABLE),
+    PurchaseItem("gems_50", TYPE_IAP.PURCHASE, PurchaseCategory.CONSUMABLE)
+)
+```
+
+### 2. Set Up Purchase History Listener
+
+```kotlin
+AppPurchase.getInstance().setPurchaseHistoryListener(object : PurchaseHistoryListener {
+    override fun onNewPurchase(productId: String, purchase: PurchaseResult) {
+        // Called when purchase is acknowledged
+        handlePurchase(productId, purchase)
+    }
+
+    override fun onPurchaseConsumed(productId: String, purchase: PurchaseResult) {
+        // Called after consumePurchase() completes
+        Log.d("Billing", "Consumed: $productId")
+    }
+})
+```
+
+### 3. Handle the Purchase
+
+```kotlin
+fun handlePurchase(productId: String, purchase: PurchaseResult) {
+    // Check purchase state
+    if (!purchase.isPurchased()) {
+        // Pending payment - don't grant yet
+        return
+    }
+
+    // Grant items based on product and quantity
+    val quantity = purchase.quantity
+    when (productId) {
+        "coins_100" -> {
+            userBalance.coins += 100 * quantity
+        }
+        "coins_500" -> {
+            userBalance.coins += 500 * quantity
+        }
+        "gems_50" -> {
+            userBalance.gems += 50 * quantity
+        }
+    }
+
+    // Save user balance
+    saveUserBalance()
+
+    // NOW consume so user can buy again
+    AppPurchase.getInstance().consumePurchase(productId)
+}
+```
+
+## Purchase Flow
+
+```
+┌─────────────┐     ┌──────────────┐     ┌──────────────┐     ┌─────────────┐
+│   Purchase  │ ──► │  Acknowledge │ ──► │ onNewPurchase│ ──► │ Grant Items │
+└─────────────┘     └──────────────┘     └──────────────┘     └──────┬──────┘
+                                                                     │
+                         ┌──────────────┐     ┌───────────────┐     │
+                         │onPurchaseCon-│ ◄── │consumePurchase│ ◄───┘
+                         │    sumed     │     └───────────────┘
+                         └──────────────┘
+```
+
+## "You Already Own This Item" Error
+
+If users see this error, the product wasn't consumed. Reasons:
+
+1. App crashed before `consumePurchase()` was called
+2. Developer forgot to call `consumePurchase()`
+3. Old code using deprecated auto-consume
+
+### Fix: Consume Pending Purchases
+
+```kotlin
+// On app start, check for unconsumed purchases
+AppPurchase.getInstance().setPurchaseListener(object : PurchaseListener {
+    override fun onProductPurchased(orderId: String?, originalJson: String?) {
+        // This fires for unconsumed purchases too
+        // Your PurchaseHistoryListener will handle it
+    }
+    // ...
+})
+
+// Verify purchases to trigger callbacks
+AppPurchase.getInstance().verifyPurchased(true)
+```
+
+## Server-Side Verification
+
+For important purchases, verify on your server:
+
+```kotlin
+override fun onNewPurchase(productId: String, purchase: PurchaseResult) {
+    if (purchase.hasVerificationData()) {
+        // Send to server
+        verifyPurchaseOnServer(
+            productId = productId,
+            token = purchase.purchaseToken,
+            json = purchase.originalJson!!,
+            signature = purchase.signature!!
+        ) { isValid ->
+            if (isValid) {
+                grantItems(productId, purchase.quantity)
+                AppPurchase.getInstance().consumePurchase(productId)
+            } else {
+                // Handle invalid purchase
+            }
+        }
+    }
+}
+```
+
+## Tracking Purchase Count
+
+```kotlin
+class PurchaseTracker : PurchaseHistoryListener {
+    private val prefs: SharedPreferences
+
+    override fun onNewPurchase(productId: String, purchase: PurchaseResult) {
+        // Increment total count
+        val key = "total_purchased_$productId"
+        val current = prefs.getInt(key, 0)
+        prefs.edit().putInt(key, current + purchase.quantity).apply()
+
+        // Grant and consume
+        grantItems(productId, purchase.quantity)
+        AppPurchase.getInstance().consumePurchase(productId)
+    }
+
+    fun getTotalPurchased(productId: String): Int {
+        return prefs.getInt("total_purchased_$productId", 0)
+    }
+}
+```
+
+## Testing
+
+1. Use Google Play Console license testers
+2. Test with real products in closed testing
+3. Test app crash scenarios (purchase acknowledged but not consumed)
+4. Test multi-quantity purchases if supported

package/content/wiki/Home.md

@@ -0,0 +1,144 @@
+# 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)
+![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`**
+
+## What's New in 2.8.0
+
+- **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
+
+## Features
+
+### AdMob Ads Management
+- **Banner Ads**: Auto-refresh, collapsible banners, smart retry
+- **Native Ads**: Small, Medium, Large formats with caching
+- **Interstitial Ads**: Time/count-based triggers, dialog support, loading strategies
+- **App Open Ads**: Lifecycle-aware with activity exclusion
+
+### NativeTemplateView (v2.6.0+)
+- 17 Template Styles: card_modern, material3, minimal, list_item, magazine, video templates
+- XML & Programmatic: Set templates via `app:adTemplate` or `setTemplate()`
+- 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)
+
+### Centralized Configuration
+- **AdManageKitConfig**: Single configuration point
+- Environment-specific settings (debug vs production)
+- Runtime configuration changes
+
+### Reliability & Performance
+- Smart retry with exponential backoff
+- Circuit breaker for failing ad units
+- Memory leak prevention with WeakReference
+
+### Privacy & Compliance
+- UMP consent management (GDPR/CCPA)
+- Automatic ad hiding for purchased users
+
+## Getting Started
+
+### Installation
+
+**Step 1:** Add JitPack to your root `build.gradle`:
+
+```groovy
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        mavenCentral()
+        maven { url 'https://jitpack.io' }
+    }
+}
+```
+
+**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'
+
+// For Jetpack Compose support
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v2.8.0'
+```
+
+**Step 3:** Sync your project with Gradle.
+
+### Quick Configuration
+
+Configure AdManageKit in your Application class:
+
+```kotlin
+class MyApp : Application() {
+    private lateinit var appOpenManager: AppOpenManager
+
+    override fun onCreate() {
+        super.onCreate()
+
+        // Configure AdManageKit
+        AdManageKitConfig.apply {
+            debugMode = BuildConfig.DEBUG
+            enableSmartPreloading = true
+            autoRetryFailedAds = true
+
+            // Ad Loading Strategies
+            interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
+            appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+            nativeLoadingStrategy = AdLoadingStrategy.HYBRID
+
+            // 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")
+    }
+}
+```
+
+## Wiki Pages
+
+### Ad Types
+- [[Interstitial Ads]] - Complete guide to interstitial ad integration
+- [[Rewarded Ads]] - Rewarded video ads with callbacks and analytics
+- [[App Open Ads]] - App open ad implementation
+- [[Native Ads|NativeAdManager]] - Native ad caching and NativeTemplateView
+- [[Banner Ads]] - Banner ad integration
+
+### Features
+- [[Ad Loading Strategies]] - ON_DEMAND, ONLY_CACHE, HYBRID strategies
+- [[Configuration]] - Complete AdManageKitConfig reference
+- [[Jetpack Compose]] - Compose integration and helpers
+
+## Sample Project
+
+The `app` module demonstrates all features. To run:
+
+1. Clone: `git clone https://github.com/i2hammad/AdManageKit.git`
+2. Open in Android Studio
+3. Replace placeholder AdMob IDs
+4. Run on device or emulator
+
+## Support
+
+[Buy me a coffee](https://buymeacoffee.com/i2hammad)
+
+For issues: [GitHub Issues](https://github.com/i2hammad/AdManageKit/issues) or [hammadmughal0001@gmail.com](mailto:hammadmughal0001@gmail.com)
+
+## License
+
+Licensed under the MIT License. See [LICENSE](https://github.com/i2hammad/AdManageKit/blob/main/LICENSE).