admanagekit-mcp-server 1.0.0

package/content/wiki/NativeAdManager.md

@@ -0,0 +1,220 @@
+# Native Ads - AdManageKit v2.8.0
+
+## Overview
+
+AdManageKit provides comprehensive native ad support with caching, multiple formats, and the new `NativeTemplateView` (v2.6.0+). Native ads blend seamlessly with your app's content while maximizing engagement.
+
+**Library Version**: v2.8.0
+
+## Features
+
+- **Multiple Formats**: Small, Medium, Large, and 17+ template styles
+- **Smart Caching**: Per-unit caching with 1-hour expiration
+- **Loading Strategies**: ON_DEMAND, ONLY_CACHE, HYBRID
+- **Shimmer Loading**: Beautiful loading placeholders
+- **NativeTemplateView**: Unified component with 17 templates (v2.6.0+)
+- **Video Support**: All templates support video ads
+
+## 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'
+}
+```
+
+## Native Ad Formats
+
+### Traditional Views
+
+| Class | Best For |
+|-------|----------|
+| `NativeBannerSmall` | Compact spaces, lists |
+| `NativeBannerMedium` | General content areas |
+| `NativeLarge` | Featured placements |
+
+### NativeTemplateView (v2.6.0+)
+
+17 template styles in one unified component:
+
+| Template | Best For |
+|----------|----------|
+| `card_modern` | General use |
+| `material3` | Material 3 apps |
+| `minimal` | Content-focused |
+| `compact_horizontal` | Lists |
+| `list_item` | RecyclerView items |
+| `magazine` | News/blog apps |
+| `video_small/medium/large` | Video content |
+| `video_square/vertical/fullscreen` | Social feeds |
+| `featured`, `grid_card`, `overlay_dark`, `story_style` | Various layouts |
+
+## Usage
+
+### NativeTemplateView (Recommended)
+
+**XML:**
+```xml
+<com.i2hammad.admanagekit.admob.NativeTemplateView
+    android:id="@+id/nativeTemplateView"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content"
+    app:adTemplate="material3" />
+```
+
+**Kotlin:**
+```kotlin
+// Load with default template
+nativeTemplateView.loadNativeAd(activity, "ca-app-pub-xxx/yyy")
+
+// Change template
+nativeTemplateView.setTemplate(NativeAdTemplate.MAGAZINE)
+nativeTemplateView.loadNativeAd(activity, "ca-app-pub-xxx/yyy")
+
+// With callback
+nativeTemplateView.loadNativeAd(activity, adUnitId, object : AdLoadCallback() {
+    override fun onAdLoaded() { /* success */ }
+    override fun onFailedToLoad(error: AdError?) { /* error */ }
+})
+
+// With strategy override
+nativeTemplateView.loadNativeAd(activity, adUnitId, callback, AdLoadingStrategy.ONLY_CACHE)
+```
+
+### Traditional Views
+
+```kotlin
+// NativeBannerSmall
+val nativeBannerSmall = NativeBannerSmall(context)
+nativeBannerSmall.loadNativeBannerAd(activity, "ca-app-pub-xxx/yyy")
+
+// NativeBannerMedium
+val nativeBannerMedium = NativeBannerMedium(context)
+nativeBannerMedium.loadNativeBannerAd(activity, "ca-app-pub-xxx/yyy", useCachedAd = true)
+
+// NativeLarge
+val nativeLarge = NativeLarge(context)
+nativeLarge.loadNativeAds(activity, "ca-app-pub-xxx/yyy")
+```
+
+## Caching System
+
+### Configuration
+
+```kotlin
+AdManageKitConfig.apply {
+    nativeLoadingStrategy = AdLoadingStrategy.HYBRID
+    nativeCacheExpiry = 1.hours
+    maxCachedAdsPerUnit = 3
+    enableLRUEviction = true
+    maxCacheMemoryMB = 200
+}
+```
+
+### NativeAdManager API
+
+```kotlin
+// Enable/disable caching globally
+NativeAdManager.enableCachingNativeAds = true
+
+// Clear cache for specific unit
+NativeAdManager.clearCachedAd("ad-unit-id")
+
+// Clear all cached ads
+NativeAdManager.clearAllCachedAds()
+
+// Get cached ad
+val cachedAd = NativeAdManager.getCachedNativeAd("ad-unit-id")
+```
+
+### Cache Behavior
+
+- **Per-Unit Caching**: Each ad unit has its own cache
+- **1-Hour Expiration**: Cached ads expire after 1 hour
+- **Automatic Cleanup**: Expired ads are automatically destroyed
+- **Memory Management**: LRU eviction when cache is full
+
+## Loading Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| ON_DEMAND | Show shimmer, fetch fresh ad |
+| ONLY_CACHE | Show cached or hide container |
+| HYBRID | Show cached if ready, fetch with shimmer otherwise |
+
+```kotlin
+// Global strategy
+AdManageKitConfig.nativeLoadingStrategy = AdLoadingStrategy.HYBRID
+
+// Per-call override
+nativeTemplateView.loadNativeAd(activity, adUnitId, callback, AdLoadingStrategy.ONLY_CACHE)
+```
+
+### Strategy Flow
+
+**ON_DEMAND/HYBRID (not cached):**
+```
+Load → Show shimmer → Fetch ad →
+    Success: Show ad, hide shimmer
+    Failure: Hide container
+```
+
+**ONLY_CACHE:**
+```
+Load → Check cache →
+    Cached: Show immediately
+    Not cached: Hide container
+```
+
+## API Reference
+
+### NativeTemplateView Methods
+
+| Method | Description |
+|--------|-------------|
+| `setTemplate(template)` | Set template style |
+| `loadNativeAd(activity, adUnitId)` | Load with defaults |
+| `loadNativeAd(activity, adUnitId, callback)` | Load with callback |
+| `loadNativeAd(activity, adUnitId, callback, strategy)` | Load with strategy |
+
+### NativeAdManager Methods
+
+| Method | Description |
+|--------|-------------|
+| `enableCachingNativeAds` | Enable/disable caching |
+| `getCachedNativeAd(adUnitId)` | Get cached ad |
+| `setCachedNativeAd(adUnitId, ad)` | Store ad in cache |
+| `clearCachedAd(adUnitId)` | Clear specific cache |
+| `clearAllCachedAds()` | Clear all caches |
+
+### AdManageKitConfig Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `nativeLoadingStrategy` | Loading strategy | HYBRID |
+| `nativeCacheExpiry` | Cache expiration | 1 hour |
+| `maxCachedAdsPerUnit` | Ads per unit | 3 |
+| `maxCacheMemoryMB` | Max cache memory | 200 MB |
+| `enableLRUEviction` | LRU eviction | true |
+| `enableAutoCacheCleanup` | Auto cleanup | true |
+
+## Best Practices
+
+1. **Use NativeTemplateView** - Unified API with 17 templates
+2. **Enable Caching** - Improves load times and reduces requests
+3. **Use HYBRID Strategy** - Best balance for most cases
+4. **Clear on Destroy** - Call `clearAllCachedAds()` in `onDestroy()`
+5. **Match Template to Context** - Use appropriate template for placement
+
+## Troubleshooting
+
+- **Ad Not Showing**: Check cache status, strategy, network
+- **Shimmer Forever**: Verify adUnitId and network connectivity
+- **Memory Issues**: Enable `enableLRUEviction` and set `maxCacheMemoryMB`
+
+## References
+
+- [AdMob Native Ads](https://developers.google.com/admob/android/native/start)
+- [NativeTemplateView Guide](https://github.com/i2hammad/AdManageKit/blob/main/docs/NATIVE_TEMPLATE_VIEW.md)
+- [GitHub Repository](https://github.com/i2hammad/AdManageKit)

package/content/wiki/Purchase-Categories.md

@@ -0,0 +1,94 @@
+# Purchase Categories
+
+AdManageKit v2.9.0 introduces a category system for classifying in-app products.
+
+## Categories
+
+| Category | Description | Disables Ads | Re-purchasable |
+|----------|-------------|--------------|----------------|
+| `CONSUMABLE` | Virtual currency, power-ups | No | Yes (after consume) |
+| `FEATURE_UNLOCK` | Level packs, themes | No | No |
+| `LIFETIME_PREMIUM` | Permanent premium access | Yes | No |
+| `REMOVE_ADS` | Ad removal only | Yes | No |
+
+## Usage
+
+```kotlin
+// Consumable - coins, gems, credits
+PurchaseItem("coins_100", TYPE_IAP.PURCHASE, PurchaseCategory.CONSUMABLE)
+
+// Feature unlock - doesn't disable ads
+PurchaseItem("dark_theme", TYPE_IAP.PURCHASE, PurchaseCategory.FEATURE_UNLOCK)
+
+// Lifetime premium - disables ads, grants all features
+PurchaseItem("lifetime", TYPE_IAP.PURCHASE, PurchaseCategory.LIFETIME_PREMIUM)
+
+// Remove ads only - just removes ads
+PurchaseItem("remove_ads", TYPE_IAP.PURCHASE, PurchaseCategory.REMOVE_ADS)
+
+// Subscription (category not applicable)
+PurchaseItem("premium_monthly", "trial_offer", TYPE_IAP.SUBSCRIPTION)
+```
+
+## How Categories Affect `isPurchased()`
+
+Only certain categories cause `isPurchased()` to return `true`:
+
+```kotlin
+// isPurchased() returns true for:
+// - Any active subscription
+// - LIFETIME_PREMIUM purchases
+// - REMOVE_ADS purchases
+
+// isPurchased() returns false for:
+// - CONSUMABLE purchases
+// - FEATURE_UNLOCK purchases
+// - No purchases
+```
+
+## Checking Specific Categories
+
+```kotlin
+// Check by purchase type
+when (AppPurchase.getInstance().getActivePurchaseType()) {
+    PurchaseType.SUBSCRIPTION -> showSubscriberUI()
+    PurchaseType.LIFETIME_PREMIUM -> showLifetimeUI()
+    PurchaseType.REMOVE_ADS -> hideAdsOnly()
+    PurchaseType.NONE -> showPurchaseOptions()
+}
+
+// Check specific categories
+AppPurchase.getInstance().hasLifetimePremium()     // LIFETIME_PREMIUM
+AppPurchase.getInstance().hasRemoveAdsPurchase()   // REMOVE_ADS
+AppPurchase.getInstance().hasLifetimePurchase()    // Any lifetime (LIFETIME_PREMIUM or REMOVE_ADS)
+```
+
+## PurchaseItem Helper Methods
+
+```kotlin
+val item = PurchaseItem("product", TYPE_IAP.PURCHASE, PurchaseCategory.LIFETIME_PREMIUM)
+
+item.shouldDisableAds()    // true - LIFETIME_PREMIUM disables ads
+item.isLifetimePurchase()  // true - one-time purchase (not subscription)
+item.isConsumable          // false - not a consumable
+```
+
+## Default Category
+
+When creating a `PurchaseItem` without specifying a category:
+
+```kotlin
+// Default is LIFETIME_PREMIUM (v2.9.0+)
+PurchaseItem("product", TYPE_IAP.PURCHASE)
+
+// Equivalent to:
+PurchaseItem("product", TYPE_IAP.PURCHASE, PurchaseCategory.LIFETIME_PREMIUM)
+```
+
+## Best Practices
+
+1. **Always specify category explicitly** for clarity
+2. **Use CONSUMABLE** for any product users can buy multiple times
+3. **Use FEATURE_UNLOCK** for one-time unlocks that don't affect ads
+4. **Use LIFETIME_PREMIUM** for permanent "premium" access
+5. **Use REMOVE_ADS** when you have separate ad removal and premium tiers