admanagekit-mcp-server 1.0.0

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

@@ -0,0 +1,209 @@
+# Ad Loading Strategies - AdManageKit v2.8.0
+
+## 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.
+
+## Strategy Types
+
+### 1. ON_DEMAND
+
+**Always fetch fresh ads with loading UI**
+
+```kotlin
+AdManageKitConfig.interstitialLoadingStrategy = AdLoadingStrategy.ON_DEMAND
+```
+
+| Pros | Cons |
+|------|------|
+| Maximum ad coverage | May interrupt user flow |
+| Always fresh ads | Loading dialog shown |
+| Best for important moments | Slower on poor network |
+
+**Best for:**
+- Important monetization points
+- After significant user actions
+- When you need maximum coverage
+
+### 2. ONLY_CACHE
+
+**Only show ads already preloaded**
+
+```kotlin
+AdManageKitConfig.interstitialLoadingStrategy = AdLoadingStrategy.ONLY_CACHE
+```
+
+| Pros | Cons |
+|------|------|
+| Instant display | Lower ad coverage |
+| Smooth UX | Skips if not cached |
+| No loading dialogs | Requires good preloading |
+
+**Best for:**
+- Frequent ad opportunities
+- During gameplay
+- When UX is priority
+
+### 3. HYBRID (Recommended)
+
+**Check cache first, fetch if needed**
+
+```kotlin
+AdManageKitConfig.interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
+```
+
+| Pros | Cons |
+|------|------|
+| Instant when cached | May show dialog if not cached |
+| Falls back to fetch | Slightly complex flow |
+| Best of both worlds | - |
+
+**Best for:**
+- Most general use cases
+- Default recommendation
+- Balanced UX and coverage
+
+## Strategy Availability
+
+| Ad Type | ON_DEMAND | ONLY_CACHE | HYBRID |
+|---------|-----------|------------|--------|
+| Interstitial | ✅ | ✅ | ✅ |
+| App Open | ✅ | ✅ | ✅ |
+| Native | ✅ | ❌ | ✅ |
+
+> **Note:** Native ads use shimmer instead of dialog, so ONLY_CACHE hides container if not cached.
+
+## Configuration
+
+### Global Settings
+
+```kotlin
+// In Application.onCreate()
+AdManageKitConfig.apply {
+    interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
+    appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+    nativeLoadingStrategy = AdLoadingStrategy.HYBRID
+}
+```
+
+### Per-Call Override
+
+```kotlin
+// InterstitialAdBuilder
+InterstitialAdBuilder.with(activity)
+    .adUnit(adUnitId)
+    .loadingStrategy(AdLoadingStrategy.ONLY_CACHE)
+    .show { next() }
+
+// NativeTemplateView
+nativeTemplateView.loadNativeAd(activity, adUnitId, callback, AdLoadingStrategy.ON_DEMAND)
+```
+
+## Flow Diagrams
+
+### Interstitial ON_DEMAND
+```
+User triggers → Show dialog → Fetch ad →
+    Loaded: Show ad → Continue
+    Timeout: Skip → Continue
+```
+
+### Interstitial ONLY_CACHE
+```
+User triggers → Check cache →
+    Cached: Show ad → Continue
+    Not cached: Skip → Continue
+```
+
+### Interstitial HYBRID
+```
+User triggers → Check cache →
+    Cached: Show ad → Continue
+    Not cached: Show dialog → Fetch →
+        Loaded: Show ad → Continue
+        Timeout: Skip → Continue
+```
+
+### Native HYBRID
+```
+Load → Check cache →
+    Cached: Show immediately
+    Not cached: Show shimmer → Fetch →
+        Success: Show ad
+        Failure: Hide container
+```
+
+## Strategy Selection Guide
+
+| Use Case | Recommended |
+|----------|-------------|
+| Level completion | HYBRID |
+| During gameplay | ONLY_CACHE |
+| Navigation | ONLY_CACHE |
+| Long tasks | ON_DEMAND |
+| App open/resume | HYBRID |
+| Cold start | ON_DEMAND |
+| Feed/list items | ONLY_CACHE |
+| Article content | HYBRID |
+
+## Example Configurations
+
+### Gaming App
+
+```kotlin
+AdManageKitConfig.apply {
+    interstitialLoadingStrategy = AdLoadingStrategy.ONLY_CACHE
+    appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+    nativeLoadingStrategy = AdLoadingStrategy.ONLY_CACHE
+}
+```
+
+### Utility App
+
+```kotlin
+AdManageKitConfig.apply {
+    interstitialLoadingStrategy = AdLoadingStrategy.ON_DEMAND
+    appOpenLoadingStrategy = AdLoadingStrategy.ON_DEMAND
+    nativeLoadingStrategy = AdLoadingStrategy.ON_DEMAND
+}
+```
+
+### Content App
+
+```kotlin
+AdManageKitConfig.apply {
+    interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
+    appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+    nativeLoadingStrategy = AdLoadingStrategy.HYBRID
+}
+```
+
+## v2.8.0 Updates
+
+**`forceShowInterstitial()` now respects loading strategy!**
+
+```kotlin
+// Before v2.8.0: Always fetched fresh
+// After v2.8.0: Respects interstitialLoadingStrategy
+
+AdManager.getInstance().forceShowInterstitial(activity, callback)
+
+// To always force fetch (old behavior):
+AdManager.getInstance().forceShowInterstitialAlways(activity, callback)
+```
+
+## Best Practices
+
+1. **Set once** in `Application.onCreate()`
+2. **Use HYBRID** as default
+3. **Use ONLY_CACHE** for frequent interruptions
+4. **Use ON_DEMAND** for critical moments
+5. **Enable background preloading** for ONLY_CACHE/HYBRID
+6. **Monitor coverage** and adjust based on metrics
+
+## References
+
+- [GitHub Repository](https://github.com/i2hammad/AdManageKit)
+- [[Interstitial Ads]]
+- [[App Open Ads]]
+- [[Native Ads|NativeAdManager]]

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

@@ -0,0 +1,189 @@
+# App Open Ads - AdManageKit v2.8.0
+
+## 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, welcome dialogs, and activity exclusion.
+
+**Library Version**: v2.8.0
+
+## Features
+
+- **Lifecycle-Aware**: Automatically shows ads when app moves to foreground
+- **Loading Strategies**: ON_DEMAND, ONLY_CACHE, HYBRID support
+- **Welcome Dialog**: Beautiful animated loading UI while fetching ads
+- **Activity Exclusion**: Skip ads for specific activities
+- **Purchase Check**: Automatically skips for premium users
+- **Firebase Analytics**: Comprehensive event tracking
+
+## Installation
+
+```groovy
+dependencies {
+    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'
+}
+```
+
+## Configuration
+
+### Basic Setup
+
+```kotlin
+class MyApp : Application() {
+    private lateinit var appOpenManager: AppOpenManager
+
+    override fun onCreate() {
+        super.onCreate()
+
+        // Set up billing first
+        BillingConfig.setPurchaseProvider(BillingPurchaseProvider())
+
+        // Configure loading strategy
+        AdManageKitConfig.apply {
+            appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+            appOpenAdTimeout = 4.seconds
+            welcomeDialogAppIcon = R.mipmap.ic_launcher
+        }
+
+        // Initialize app open manager
+        appOpenManager = AppOpenManager(this, "ca-app-pub-xxx/yyy")
+    }
+}
+```
+
+### Welcome Dialog Customization
+
+```kotlin
+AdManageKitConfig.apply {
+    // App icon in welcome dialog
+    welcomeDialogAppIcon = R.mipmap.ic_launcher
+
+    // Custom texts
+    welcomeDialogTitle = "Welcome Back!"
+    welcomeDialogSubtitle = "Loading your content..."
+    welcomeDialogFooter = "Just a moment..."
+
+    // Colors
+    dialogOverlayColor = 0x80000000.toInt()  // 50% black
+    dialogCardBackgroundColor = Color.WHITE
+
+    // Dismiss delay after ad shows
+    welcomeDialogDismissDelay = 0.8.seconds
+}
+```
+
+## Usage
+
+### Automatic Display
+
+App open ads show automatically when the app comes to foreground:
+
+```kotlin
+// Initialize in Application.onCreate()
+appOpenManager = AppOpenManager(this, "ca-app-pub-xxx/yyy")
+// That's it! Ads show automatically on app foreground
+```
+
+### Force Show
+
+```kotlin
+appOpenManager.forceShowAdIfAvailable(activity, object : AdManagerCallback() {
+    override fun onNextAction() {
+        // Continue with your flow
+        navigateToMain()
+    }
+    override fun onAdLoaded() {
+        // Ad was displayed
+    }
+})
+```
+
+### Excluding Activities
+
+```kotlin
+// Exclude splash screen from showing ads
+appOpenManager.disableAppOpenWithActivity(SplashActivity::class.java)
+
+// Re-enable later if needed
+appOpenManager.includeAppOpenActivityForAds(SplashActivity::class.java)
+```
+
+### Skip Next Ad
+
+```kotlin
+// Skip the next ad (e.g., after returning from in-app purchase)
+appOpenManager.skipNextAd()
+```
+
+### Check Availability
+
+```kotlin
+if (appOpenManager.isAdAvailable()) {
+    // Ad is ready to show
+}
+```
+
+## Loading Strategies
+
+Configure via `AdManageKitConfig.appOpenLoadingStrategy`:
+
+| Strategy | Behavior |
+|----------|----------|
+| ON_DEMAND | Always fetch fresh ad with welcome dialog |
+| ONLY_CACHE | Only show if cached, skip otherwise |
+| HYBRID | Show cached if ready, fetch with dialog otherwise |
+
+```kotlin
+// Set strategy
+AdManageKitConfig.appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+```
+
+## API Reference
+
+### AppOpenManager Methods
+
+| Method | Description |
+|--------|-------------|
+| `fetchAd()` | Preload ad in background |
+| `fetchAd(callback, timeout)` | Preload with callback and timeout |
+| `showAdIfAvailable()` | Show if cached (lifecycle triggered) |
+| `forceShowAdIfAvailable(activity, callback)` | Force show with callback |
+| `isAdAvailable()` | Check if ad is cached |
+| `skipNextAd()` | Skip next ad display |
+| `disableAppOpenWithActivity(class)` | Exclude activity |
+| `includeAppOpenActivityForAds(class)` | Re-include activity |
+
+### AdManageKitConfig Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `appOpenLoadingStrategy` | Loading strategy | HYBRID |
+| `appOpenAdTimeout` | Load timeout | 4 seconds |
+| `appOpenFetchFreshAd` | Disable background prefetch | false |
+| `welcomeDialogAppIcon` | App icon resource | 0 |
+| `welcomeDialogTitle` | Dialog title | "Welcome Back!" |
+| `welcomeDialogSubtitle` | Dialog subtitle | "Loading..." |
+| `welcomeDialogFooter` | Dialog footer | "Just a moment..." |
+| `welcomeDialogDismissDelay` | Delay before dismiss | 0.8 seconds |
+| `dialogOverlayColor` | Overlay color | 50% black |
+| `dialogCardBackgroundColor` | Card background | Theme default |
+
+## Best Practices
+
+1. **Initialize in Application** - Set up `AppOpenManager` in `Application.onCreate()`
+2. **Exclude Splash** - Use `disableAppOpenWithActivity(SplashActivity::class.java)`
+3. **Use HYBRID** - Best balance of UX and coverage
+4. **Set App Icon** - Configure `welcomeDialogAppIcon` for branded experience
+5. **Wire Billing** - Ensure `BillingConfig` is set up to skip premium users
+
+## Troubleshooting
+
+- **Ad Not Showing**: Check `isAdAvailable()`, exclusion list, purchase status
+- **Welcome Dialog Issues**: Verify `welcomeDialogAppIcon` is set
+- **Strategy Not Working**: Ensure v2.8.0+ and check `appOpenLoadingStrategy`
+
+## References
+
+- [AdMob App Open Ads](https://developers.google.com/admob/android/app-open-ads)
+- [GitHub Repository](https://github.com/i2hammad/AdManageKit)

package/content/wiki/Banner-Ads.md

@@ -0,0 +1,133 @@
+# Banner Ads - AdManageKit v2.8.0
+
+## Overview
+
+AdManageKit provides `BannerAdView` for easy banner ad integration with features like auto-refresh, collapsible banners, and smart retry logic.
+
+**Library Version**: v2.8.0
+
+## Features
+
+- **Auto-Refresh**: Configurable refresh intervals
+- **Collapsible Banners**: Expandable/collapsible banner support
+- **Smart Retry**: Automatic retry with exponential backoff
+- **Purchase Check**: Auto-hide for premium users
+- **Firebase Analytics**: Event tracking integration
+
+## 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'
+}
+```
+
+## Usage
+
+### XML Layout
+
+```xml
+<com.i2hammad.admanagekit.admob.BannerAdView
+    android:id="@+id/bannerAdView"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content" />
+```
+
+### Load Banner
+
+```kotlin
+// Standard banner
+bannerAdView.loadBanner(activity, "ca-app-pub-xxx/yyy")
+
+// With callback
+bannerAdView.loadBanner(activity, "ca-app-pub-xxx/yyy", object : AdLoadCallback() {
+    override fun onAdLoaded() { /* success */ }
+    override fun onFailedToLoad(error: AdError?) { /* error */ }
+    override fun onAdImpression() { /* impression */ }
+    override fun onAdClicked() { /* clicked */ }
+})
+```
+
+### Collapsible Banner
+
+```kotlin
+// Load collapsible banner at bottom
+bannerAdView.loadCollapsibleBanner(activity, "ca-app-pub-xxx/yyy", isBottom = true)
+
+// Load collapsible banner at top
+bannerAdView.loadCollapsibleBanner(activity, "ca-app-pub-xxx/yyy", isBottom = false)
+```
+
+## Configuration
+
+### Global Settings
+
+```kotlin
+AdManageKitConfig.apply {
+    // Auto-refresh interval (minimum 30 seconds per AdMob policy)
+    defaultBannerRefreshInterval = 60.seconds
+
+    // Enable collapsible by default
+    enableCollapsibleBannersByDefault = false
+
+    // Default collapsible placement
+    defaultCollapsiblePlacement = CollapsibleBannerPlacement.BOTTOM
+}
+```
+
+### Collapsible Placement Options
+
+```kotlin
+// Available placements
+CollapsibleBannerPlacement.TOP
+CollapsibleBannerPlacement.BOTTOM
+```
+
+## Jetpack Compose
+
+```kotlin
+@Composable
+fun MyScreen() {
+    BannerAdCompose(
+        adUnitId = "ca-app-pub-xxx/yyy",
+        modifier = Modifier.fillMaxWidth()
+    )
+}
+```
+
+## API Reference
+
+### BannerAdView Methods
+
+| Method | Description |
+|--------|-------------|
+| `loadBanner(activity, adUnitId)` | Load standard banner |
+| `loadBanner(activity, adUnitId, callback)` | Load with callback |
+| `loadCollapsibleBanner(activity, adUnitId, isBottom)` | Load collapsible |
+
+### AdManageKitConfig Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `defaultBannerRefreshInterval` | Refresh interval | 60 seconds |
+| `enableCollapsibleBannersByDefault` | Enable collapsible | false |
+| `defaultCollapsiblePlacement` | Collapsible position | BOTTOM |
+
+## Best Practices
+
+1. **Place wisely** - Don't cover important content
+2. **Respect refresh** - Minimum 30 seconds per AdMob policy
+3. **Test placements** - Try different positions for best performance
+4. **Use collapsible** - Better UX for tall banners
+
+## Troubleshooting
+
+- **Banner Not Showing**: Check adUnitId, network, purchase status
+- **Refresh Issues**: Ensure interval is 30+ seconds
+- **Sizing Issues**: Use `wrap_content` for height
+
+## References
+
+- [AdMob Banner Ads](https://developers.google.com/admob/android/banner)
+- [GitHub Repository](https://github.com/i2hammad/AdManageKit)

package/content/wiki/Billing-Integration.md

@@ -0,0 +1,69 @@
+# Billing Integration
+
+AdManageKit provides a comprehensive billing integration module (`admanagekit-billing`) that simplifies Google Play Billing Library v8 implementation.
+
+## Quick Start
+
+### 1. Add Dependency
+
+```groovy
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v2.9.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v2.9.0'
+```
+
+### 2. Define Products
+
+```kotlin
+val products = listOf(
+    // Consumable (coins, gems)
+    PurchaseItem("coins_100", TYPE_IAP.PURCHASE, PurchaseCategory.CONSUMABLE),
+
+    // Lifetime premium (disables ads)
+    PurchaseItem("lifetime", TYPE_IAP.PURCHASE, PurchaseCategory.LIFETIME_PREMIUM),
+
+    // Remove ads only
+    PurchaseItem("remove_ads", TYPE_IAP.PURCHASE, PurchaseCategory.REMOVE_ADS),
+
+    // Subscription with trial
+    PurchaseItem("premium_monthly", "free_trial", TYPE_IAP.SUBSCRIPTION)
+)
+```
+
+### 3. Initialize
+
+```kotlin
+class MyApp : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        AppPurchase.getInstance().initBilling(this, products)
+    }
+}
+```
+
+### 4. Make Purchases
+
+```kotlin
+// In-app purchase
+AppPurchase.getInstance().purchase(activity, "remove_ads")
+
+// Subscription
+AppPurchase.getInstance().subscribe(activity, "premium_monthly")
+```
+
+### 5. Check Purchase Status
+
+```kotlin
+if (AppPurchase.getInstance().isPurchased()) {
+    // User has premium (subscription, lifetime, or remove_ads)
+}
+```
+
+## Pages
+
+- [[Purchase Categories]] - Product classification system
+- [[Consumable Products]] - Handling consumables with manual consumption
+- [[Subscriptions]] - Subscription lifecycle management
+- [[Subscription Upgrades]] - Upgrade/downgrade handling
+- [[Purchase History]] - Tracking purchases with PurchaseHistoryListener
+- [[PurchaseResult API]] - Full API reference for PurchaseResult
+- [[Server Verification]] - Server-side purchase verification