admanagekit-mcp-server 1.0.0

package/content/docs/release-notes/RELEASE_NOTES_v3.3.0.md

@@ -0,0 +1,252 @@
+# Release Notes - v3.3.0
+
+## Highlights
+
+- **Single-Activity App Support**: Screen and fragment tag-based exclusions for app open ads
+- **Background-Aware Ad Display**: Ads no longer show when app is in background
+- **Dialog Stability Fixes**: Prevents duplicate dialogs and threading issues
+- **New onAdShowed() Callback**: Know when interstitial ad covers the screen
+
+---
+
+## New Features
+
+### Single-Activity App Support for App Open Ads
+
+For apps using a single activity with multiple fragments (Navigation Component, Jetpack Compose Navigation), you can now control app open ads per screen:
+
+#### Screen Tag Exclusions
+
+```kotlin
+// In Application class
+appOpenManager = AppOpenManager(this, "ca-app-pub-xxxxx/yyyyy").apply {
+    excludeScreenTags("Payment", "Onboarding", "Checkout")
+}
+
+// In MainActivity - track current screen on navigation
+navController.addOnDestinationChangedListener { _, destination, _ ->
+    (application as MyApp).appOpenManager.setCurrentScreenTag(
+        destination.label?.toString()
+    )
+}
+```
+
+#### Fragment Tag Exclusions
+
+```kotlin
+// Set provider for automatic fragment detection
+appOpenManager.setFragmentTagProvider {
+    supportFragmentManager.fragments.lastOrNull()?.tag
+}
+
+// Exclude specific fragment tags
+appOpenManager.excludeFragmentTags("PaymentFragment", "OnboardingFragment")
+```
+
+#### Temporary Disable/Enable
+
+```kotlin
+// Disable during critical flows
+appOpenManager.disableAppOpenAdsTemporarily()
+
+// ... perform operation ...
+
+// Re-enable when done
+appOpenManager.enableAppOpenAds()
+
+// Check current state
+if (appOpenManager.areAppOpenAdsEnabled()) { }
+```
+
+### Background-Aware Ad Display
+
+App open ads now intelligently handle background/foreground transitions:
+
+- **No Background Ads**: Ads won't try to show when app is in background
+- **Pending Ad Queue**: If ad loads while app is in background, it's saved for when user returns
+- **Welcome Dialog on Return**: When user returns, a welcome dialog appears briefly before showing the saved ad
+
+```kotlin
+// This is automatic - no code changes needed!
+// When user switches apps during ad loading:
+// 1. Ad loads in background -> saved as pending
+// 2. Dialog dismisses automatically
+// 3. User returns to app
+// 4. Welcome dialog appears
+// 5. Pending ad shows smoothly
+```
+
+### New onAdShowed() Callback
+
+Know exactly when an interstitial ad is displayed on screen:
+
+```kotlin
+AdManager.getInstance().forceShowInterstitial(activity, object : AdManagerCallback() {
+    override fun onAdShowed() {
+        // Ad is now covering the screen
+        // Pause game, mute audio, track analytics
+        gameEngine.pause()
+        audioManager.mute()
+    }
+
+    override fun onNextAction() {
+        // Ad dismissed - resume normal operation
+        gameEngine.resume()
+        audioManager.unmute()
+    }
+})
+```
+
+---
+
+## Bug Fixes
+
+### Dialog Duplication Fix
+
+**Issue**: When app was paused and resumed during ad loading dialog, a new dialog would appear without dismissing the old one, causing multiple overlapping dialogs.
+
+**Fix**:
+- Track current dialog instance to prevent duplicates
+- Dismiss existing dialog before showing new one
+- Added `isFetchingWithDialog` flag to prevent concurrent fetch requests
+
+### Threading Issues Fix
+
+**Issue**: Ad SDK callbacks could be called from background threads, causing crashes:
+- `Animators may only be run on Looper threads`
+- `Can't toast on a thread that has not called Looper.prepare()`
+
+**Fix**: All ad callbacks in both `AdManager` and `AppOpenManager` now properly dispatch to main thread using `Handler(Looper.getMainLooper()).post { }`.
+
+### Interstitial Priority Fix
+
+**Issue**: App open ads would show on top of interstitial loading dialogs when user switched apps and came back.
+
+**Fix**:
+- `onStart` now checks `isAdOrDialogShowing()` instead of just `isDisplayingAd()`
+- If interstitial dialog is showing, app open ad is skipped
+- Pending app open ads are cleared when interstitial has priority
+
+### Race Condition Fix
+
+**Issue**: Multiple ads could show in rapid succession due to flag being set after `show()` instead of before.
+
+**Fix**: `isShowingAd` flag is now set synchronously before calling `show()` to prevent concurrent show attempts.
+
+---
+
+## New API Methods
+
+### AdManagerCallback
+
+```kotlin
+// NEW - Called when ad covers the full screen
+open fun onAdShowed() { }
+```
+
+### AdManager
+
+```kotlin
+// NEW - Check if loading dialog is showing
+fun isLoadingDialogShowing(): Boolean
+
+// NEW - Check if ad OR loading dialog is showing
+fun isAdOrDialogShowing(): Boolean
+```
+
+### AppOpenManager
+
+#### Screen Tag Exclusions
+```kotlin
+fun setCurrentScreenTag(tag: String?)
+fun getCurrentScreenTag(): String?
+fun excludeScreenTag(tag: String)
+fun excludeScreenTags(vararg tags: String)
+fun includeScreenTag(tag: String)
+fun clearScreenTagExclusions()
+```
+
+#### Fragment Tag Exclusions
+```kotlin
+fun setFragmentTagProvider(provider: (() -> String?)?)
+fun excludeFragmentTag(tag: String)
+fun excludeFragmentTags(vararg tags: String)
+fun includeFragmentTag(tag: String)
+```
+
+#### Temporary Control
+```kotlin
+fun disableAppOpenAdsTemporarily()
+fun enableAppOpenAds()
+fun areAppOpenAdsEnabled(): Boolean
+```
+
+---
+
+## Migration Guide
+
+### From v3.2.0 to v3.3.0
+
+This is a **backward-compatible** release. No code changes are required.
+
+**Optional Enhancements**:
+
+#### 1. Use onAdShowed() for better app state management
+
+```kotlin
+// Before (v3.1.0)
+AdManager.getInstance().forceShowInterstitial(activity, object : AdManagerCallback() {
+    override fun onNextAction() { navigateNext() }
+})
+
+// After (v3.2.0) - Know when ad is actually showing
+AdManager.getInstance().forceShowInterstitial(activity, object : AdManagerCallback() {
+    override fun onAdShowed() {
+        pauseAppContent()  // Ad is now visible
+    }
+    override fun onNextAction() {
+        resumeAppContent()
+        navigateNext()
+    }
+})
+```
+
+#### 2. Single-Activity App Support
+
+```kotlin
+// Before (v3.1.0) - No way to exclude specific screens in single-activity apps
+
+// After (v3.2.0) - Exclude specific screens
+appOpenManager.excludeScreenTags("Payment", "Onboarding")
+navController.addOnDestinationChangedListener { _, destination, _ ->
+    appOpenManager.setCurrentScreenTag(destination.label?.toString())
+}
+```
+
+---
+
+## Full Changelog
+
+### New Features
+- Added screen tag exclusions (`setCurrentScreenTag`, `excludeScreenTags`, `includeScreenTag`)
+- Added fragment tag exclusions (`setFragmentTagProvider`, `excludeFragmentTags`, `includeFragmentTag`)
+- Added temporary disable/enable (`disableAppOpenAdsTemporarily`, `enableAppOpenAds`, `areAppOpenAdsEnabled`)
+- Added `onAdShowed()` callback to `AdManagerCallback`
+- Added `isLoadingDialogShowing()` and `isAdOrDialogShowing()` to `AdManager`
+- Added background/foreground detection for app open ads
+- Added pending ad queue for ads loaded while in background
+
+### Bug Fixes
+- Fixed duplicate dialog display when app is paused/resumed during ad loading
+- Fixed threading crashes ("Animators may only be run on Looper threads")
+- Fixed app open ads showing on top of interstitial loading dialogs
+- Fixed race condition allowing multiple concurrent ad shows
+- Fixed `currentWelcomeDialog` not being cleared properly after dismissal
+
+### Internal Improvements
+- Added `currentLoadingDialog` tracking in `AdManager`
+- Added `isFetchingWithDialog` flag to prevent duplicate fetch requests
+- Added `isAppInForeground` tracking in `AppOpenManager`
+- Added `onStop` lifecycle callback for background detection
+- Wrapped all ad SDK callbacks in main thread handlers
+- Updated `cleanup()` to clear new exclusion collections

package/content/docs/release-notes/RELEASE_NOTES_v3.3.2.md

@@ -0,0 +1,215 @@
+# Release Notes - v3.3.2
+
+## Highlights
+
+- **InterstitialAdBuilder Fix**: Ad unit now properly assigned to AdManager on first HYBRID fetch
+- **everyNthTime Fix**: Call counter persists across builder instances
+- **New Native Templates**: `flexible`, `icon_left`, and `top_icon_media` for GridView display
+- **Call Counter API**: Manage everyNthTime counters via AdManager
+
+---
+
+## Bug Fixes
+
+### InterstitialAdBuilder Ad Unit Assignment
+
+**Issue**: When using `InterstitialAdBuilder` with HYBRID strategy and no cached ad available, the first "force fetch" path would fail because the ad unit was only stored in `primaryAdUnit` but never assigned to `AdManager.adUnitId`.
+
+**Fix**: The `adUnit()` method now immediately sets the ad unit on AdManager:
+
+```kotlin
+// Before (v3.3.1) - Ad unit not available in AdManager
+InterstitialAdBuilder.with(activity)
+    .adUnit("ca-app-pub-xxx/yyy")  // Only stored in builder
+    .strategy(AdLoadingStrategy.HYBRID)
+    .showWithDialog { navigateNext() }
+// First call with empty cache would fail!
+
+// After (v3.3.2) - Ad unit immediately available
+InterstitialAdBuilder.with(activity)
+    .adUnit("ca-app-pub-xxx/yyy")  // Now also sets AdManager.adUnitId
+    .strategy(AdLoadingStrategy.HYBRID)
+    .showWithDialog { navigateNext() }
+// Works correctly on first call
+```
+
+### everyNthTime Counter Persistence
+
+**Issue**: The `everyNthTime()` feature would not work correctly because the call counter was stored as an instance variable in `InterstitialAdBuilder`. Since a new builder is created for each call, the counter would always reset to 0.
+
+**Fix**: Call counters are now stored in `AdManager` singleton and persist across builder instances:
+
+```kotlin
+// Before (v3.3.1) - Counter reset each call
+InterstitialAdBuilder.with(activity)
+    .adUnit(adUnitId)
+    .everyNthTime(3)  // Counter always starts at 0
+    .show { }
+// Ads shown on EVERY call (counter never reaches 3)
+
+// After (v3.3.2) - Counter persists
+InterstitialAdBuilder.with(activity)
+    .adUnit(adUnitId)
+    .everyNthTime(3)  // Counter increments: 1, 2, 3, 1, 2, 3...
+    .show { }
+// Ads shown on 3rd, 6th, 9th calls, etc.
+```
+
+---
+
+## New Features
+
+### New Native Templates for GridView
+
+Three new templates designed for displaying native ads in GridView or similar layouts:
+
+#### flexible Template
+- Adaptive layout that adjusts to available space
+- MediaView support for video content
+- Responsive design for various screen sizes
+
+#### icon_left Template
+- Icon positioned on the left side
+- MediaView at top for video content support
+- Headline and CTA in content section
+- Matches `grid_item` styling
+
+#### top_icon_media Template
+- Icon and text at top
+- MediaView in the middle section
+- CTA button at bottom
+
+```kotlin
+nativeTemplateView.setTemplate(NativeAdTemplate.FLEXIBLE)
+nativeTemplateView.loadNativeAd(activity, adUnitId)
+
+nativeTemplateView.setTemplate(NativeAdTemplate.ICON_LEFT)
+nativeTemplateView.loadNativeAd(activity, adUnitId)
+
+nativeTemplateView.setTemplate(NativeAdTemplate.TOP_ICON_MEDIA)
+nativeTemplateView.loadNativeAd(activity, adUnitId)
+```
+
+### AdManager Call Counter API
+
+New methods for managing `everyNthTime` counters programmatically:
+
+```kotlin
+// Get current counter value for an ad unit
+val count = AdManager.getInstance().getCallCount("ca-app-pub-xxx/yyy")
+
+// Manually increment counter
+val newCount = AdManager.getInstance().incrementCallCount("ca-app-pub-xxx/yyy")
+
+// Reset counter for specific ad unit
+AdManager.getInstance().resetCallCount("ca-app-pub-xxx/yyy")
+
+// Reset all counters (useful when user upgrades to premium)
+AdManager.getInstance().resetAllCallCounts()
+```
+
+### AdManager.setAdUnitId()
+
+New method to set ad unit ID directly:
+
+```kotlin
+// Useful when you need to configure AdManager before using builder
+AdManager.getInstance().setAdUnitId("ca-app-pub-xxx/yyy")
+```
+
+---
+
+## New API Methods
+
+### AdManager
+
+```kotlin
+// Set ad unit ID directly
+fun setAdUnitId(adUnitId: String?)
+
+// Increment and return call counter
+fun incrementCallCount(adUnitId: String): Int
+
+// Get current call counter value
+fun getCallCount(adUnitId: String): Int
+
+// Reset counter for specific ad unit
+fun resetCallCount(adUnitId: String)
+
+// Reset all call counters
+fun resetAllCallCounts()
+```
+
+### NativeAdTemplate (Enum)
+
+```kotlin
+FLEXIBLE        // Adaptive layout for various screen sizes
+ICON_LEFT       // Icon on left, MediaView at top
+TOP_ICON_MEDIA  // Icon at top, MediaView in middle
+```
+
+---
+
+## Sample App
+
+Added comprehensive **Interstitial Test Suite** activity with tests for:
+
+- **Loading**: Preload, Load with callback, isReady check
+- **Strategies**: ON_DEMAND, ONLY_CACHE, HYBRID, FRESH_WITH_FALLBACK
+- **Builder Options**: Basic show, force show, timeout, callbacks, everyNthTime, maxShows, minInterval, autoReload
+- **AdManager Direct**: forceShowWithDialog, showIfReady, showByTime, showByCount
+- **Edge Cases**: Show before load, rapid clicks (duplicate prevention), builder without preload
+
+Access via `InterstitialActivity` > "Interstitial Test Suite" button.
+
+---
+
+## Migration Guide
+
+### From v3.3.1 to v3.3.2
+
+This is a **backward-compatible** release. No code changes required.
+
+**Optional Enhancements**:
+
+#### 1. Use Counter API for everyNthTime Reset
+
+```kotlin
+// Reset ad counter when user purchases premium
+fun onPremiumPurchased() {
+    AdManager.getInstance().resetAllCallCounts()
+}
+```
+
+#### 2. Use New Native Templates
+
+```kotlin
+// Adaptive layout for various screen sizes
+nativeTemplateView.setTemplate(NativeAdTemplate.FLEXIBLE)
+
+// For GridView/RecyclerView grid layouts
+nativeTemplateView.setTemplate(NativeAdTemplate.ICON_LEFT)
+
+// For vertical scrolling lists
+nativeTemplateView.setTemplate(NativeAdTemplate.TOP_ICON_MEDIA)
+```
+
+---
+
+## Full Changelog
+
+### Bug Fixes
+- Fixed InterstitialAdBuilder not assigning ad unit to AdManager on first HYBRID fetch
+- Fixed everyNthTime counter resetting on each builder instance
+
+### New Features
+- Added `flexible` native template with adaptive layout
+- Added `icon_left` native template with MediaView for GridView
+- Added `top_icon_media` native template with MediaView
+- Added `setAdUnitId()` to AdManager
+- Added call counter API: `incrementCallCount()`, `getCallCount()`, `resetCallCount()`, `resetAllCallCounts()`
+- Added Interstitial Test Suite activity to sample app
+
+### Internal Changes
+- Call counters moved from InterstitialAdBuilder instance to AdManager singleton
+- `InterstitialAdBuilder.adUnit()` now calls `AdManager.getInstance().setAdUnitId()`

package/content/docs/release-notes/RELEASE_NOTES_v3.3.3.md

@@ -0,0 +1,116 @@
+# Release Notes - v3.3.3
+
+## Highlights
+
+- **SDK-Agnostic Type Aliases**: Callbacks now use type aliases for migration compatibility between GMS SDK and Next-Gen SDK versions
+- **Migration Ready**: Same callback signatures work on both `main` and `nextgen` branches
+
+---
+
+## New Features
+
+### SDK-Agnostic Type Aliases
+
+Added type aliases that abstract SDK-specific types, enabling seamless migration between the legacy GMS SDK (main branch) and the Next-Gen GMA SDK (nextgen branch).
+
+#### TypeAliases.kt
+
+```kotlin
+// Main branch (GMS SDK)
+typealias AdKitError = com.google.android.gms.ads.AdError
+typealias AdKitLoadError = com.google.android.gms.ads.LoadAdError
+typealias AdKitValue = com.google.android.gms.ads.AdValue
+
+// Nextgen branch (Next-Gen GMA SDK)
+typealias AdKitError = com.google.android.libraries.ads.mobile.sdk.common.LoadAdError
+typealias AdKitValue = com.google.android.libraries.ads.mobile.sdk.common.AdValue
+```
+
+#### Updated Callbacks
+
+All callback interfaces now use type aliases:
+
+```kotlin
+// AdLoadCallback
+open fun onFailedToLoad(error: AdKitError?) { }
+open fun onPaidEvent(adValue: AdKitValue) { }
+
+// AdManagerCallback
+open fun onFailedToLoad(error: AdKitError?) { }
+
+// OnAdFailedListener / InterstitialAdCallback
+fun onAdFailed(error: AdKitError)
+```
+
+#### Usage
+
+Your callback implementations work identically on both branches:
+
+```kotlin
+nativeTemplateView.loadNativeAd(activity, adUnitId, object : AdLoadCallback() {
+    override fun onAdLoaded() {
+        Log.d("Ads", "Ad loaded successfully")
+    }
+
+    override fun onFailedToLoad(error: AdKitError?) {  // Same on both branches
+        Log.e("Ads", "Failed to load: ${error?.message}")
+    }
+
+    override fun onPaidEvent(adValue: AdKitValue) {    // Same on both branches
+        trackRevenue(adValue.valueMicros)
+    }
+})
+```
+
+---
+
+## Migration Guide
+
+### From v3.3.2 to v3.3.3
+
+This is a **backward-compatible** release. No code changes required.
+
+**Optional Migration**:
+
+If you're preparing to migrate to the Next-Gen SDK version:
+
+1. Update your callback implementations to use type aliases
+2. Avoid direct references to SDK-specific types in your callbacks
+3. When ready, switch to `nextgen` branch artifacts
+
+```groovy
+// Main branch (current)
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v3.3.3'
+
+// Next-Gen branch (when ready to migrate)
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-nextgen:v4.1.1'
+```
+
+---
+
+## Next-Gen SDK Information
+
+The `nextgen` branch offers additional features:
+
+| Feature | Main Branch | Next-Gen Branch |
+|---------|-------------|-----------------|
+| SDK | GMS play-services-ads | GMA Next-Gen SDK |
+| Ad Loading | Traditional load/show | Preloader-based |
+| Threading | Manual dispatch | Automatic |
+| Buffer System | N/A | Configurable |
+
+See the [README](../../README.md#next-gen-gma-sdk-version) for more details.
+
+---
+
+## Full Changelog
+
+### New Features
+- Added `TypeAliases.kt` with SDK-agnostic type aliases
+- Updated `AdLoadCallback` to use `AdKitError` and `AdKitValue`
+- Updated `AdManagerCallback` to use `AdKitError`
+- Updated `AdCallback` interfaces to use `AdKitError`
+
+### Documentation
+- Added Next-Gen SDK section to README
+- Added migration compatibility information