feat: Fix App Open ad race conditions and waterfall loading

i2hammad · i2hammad · commit e63b7fad44dc · 2026-03-06T03:03:15.000+05:00
This release addresses several critical race conditions in `AppOpenManager` related to concurrent ad loads, splash screen navigation, and resume behavior. It ensures that duplicate ad requests are deduplicated and that lifecycle callbacks are fired reliably.

### App Open Ad Improvements
- **Duplicate Load Prevention**: Implemented a `pendingFetchCallback` mechanism in `fetchViaWaterfall` and `fetchAd`. If a load is already in progress (e.g., a background preload), subsequent calls attach to the existing fetch instead of starting a new one.
- **Splash Auto-Navigation Fix**: Resolved an issue where orphaned timeout runnables would trigger `onFailedToLoad` after an ad had already successfully shown, causing the splash screen to navigate away prematurely.
- **Resume Show Logic**: Updated `showAdIfAvailable()` to only skip when a dialog-based fetch is active. Background auto-reload preloads no longer block ads from showing when the app is resumed.
- **Strategy Refinements**:
    - Added `hasBeenBackgrounded` flag to distinguish cold starts from app resumes.
    - Prevented `ON_DEMAND` strategy from triggering automatic loads during `onStart` on cold starts, allowing explicit `fetchAd` or `forceShow` calls to take priority.

### Logging &amp; Debugging
- **Enhanced Traceability**: Added comprehensive `AdDebugUtils.logEvent` calls across all loading paths, including `loading`, `showCachedAd`, `onAdLoaded`, and `onFailedToLoad` for both waterfall and standard AdMob paths.

### Sample App &amp; Versioning
- **Sample Updates**: Modified `MyApplication` to use `HYBRID` loading for app open ads by default and adjusted provider chain configurations. Updated `SplashActivity` UMP request parameters.
- **Version Bump**: Incremented library version to `3.4.3` across all modules:
    - `ad-manage-kit`
    - `ad-manage-kit-billing`
    - `ad-manage-kit-core`
    - `ad-manage-kit-compose`
    - `ad-manage-kit-yandex`
- **Documentation**: Updated `README.md`, `CHANGELOG.md`, and created detailed release notes for `v3.4.3`.
diff --git a/AdManageKit/build.gradle.kts b/AdManageKit/build.gradle.kts
@@ -68,7 +68,7 @@ afterEvaluate {
                 from(components["release"])
                 groupId = "com.github.i2hammad"
                 artifactId = "ad-manage-kit"
-                version = "3.4.2"
+                version = "3.4.3"
             }
 
 
diff --git a/AdManageKit/src/main/java/com/i2hammad/admanagekit/admob/AppOpenManager.kt b/AdManageKit/src/main/java/com/i2hammad/admanagekit/admob/AppOpenManager.kt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,22 @@ All notable changes to AdManageKit will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.4.3] - 2026-03-06
+
+### Fixed
+- **Duplicate Ad Loads**: `fetchViaWaterfall(callback, timeout)` and `fetchAd(callback, timeout)` now check `isLoading` before starting, attaching to the in-progress fetch instead of creating a duplicate (both waterfall and non-waterfall paths)
+- **Splash Auto-Navigation**: Orphaned `pendingFetchTimeoutRunnable` no longer fires stale `onFailedToLoad` callbacks after the ad has already loaded and shown
+- **Resume Ad Show Blocked**: `showAdIfAvailable()` no longer skips when a background auto-reload preload is in progress (only skips for dialog-based fetches)
+- **ON_DEMAND Cold Start**: `onStart` no longer triggers automatic ad load for ON_DEMAND strategy on cold start; explicit `fetchAd`/`forceShow` handles it
+- **Hot-Start Duplicate Loads**: Fixed concurrent loads when returning to SplashActivity via hot start
+
+### Added
+- **Background Fetch Callback Attachment**: `pendingFetchCallback` mechanism allows splash `fetchAd` to receive results from an already-running background preload
+- **Cold Start Detection**: `hasBeenBackgrounded` flag distinguishes cold start from resume for ON_DEMAND strategy
+- **Load Start Logging**: `AdDebugUtils.logEvent` `loading` event added to all ad load start paths
+- **Cached Ad Logging**: `AdDebugUtils.logEvent` `showCachedAd` event when cached ads are shown
+- **Comprehensive Logging**: `AdDebugUtils.logEvent` added to all previously missing load/failure paths in `AppOpenManager`
+
 ## [3.4.2] - 2026-03-06
 
 ### Fixed
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 
 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 `3.4.2`** improves App Open ad reliability with `autoRetryFailedAds` support and late-loading ad preservation.
+**Latest Version `3.4.3`** fixes race conditions in App Open ad waterfall loading — duplicate loads, splash auto-navigation, and resume ad show blocking.
 
 ---
 
@@ -54,27 +54,23 @@ Your callback implementations work on both branches without changes.
 
 | Use Case | Recommended |
 |----------|-------------|
-| Production apps (stable) | **Main branch** (v3.4.2) |
+| Production apps (stable) | **Main branch** (v3.4.3) |
 | New projects wanting latest features | **Nextgen branch** (v4.1.1) |
 | Testing preloader system | **Nextgen branch** |
 | Risk-averse production | **Main branch** |
 
 ---
 
-## What's New in 3.4.2
+## What's New in 3.4.3
 
-### App Open Ads: `autoRetryFailedAds` Support
-App open ads now respect `AdManageKitConfig.autoRetryFailedAds`, matching interstitial, rewarded, and native ads. Failed loads are automatically retried via `AdRetryManager` with exponential backoff.
+### Duplicate Waterfall Load Prevention
+Concurrent waterfall loads from `onStart` preload and splash `fetchAd` are now deduplicated. The splash callback attaches to the in-progress fetch instead of starting a second one.
 
-```kotlin
-AdManageKitConfig.apply {
-    autoRetryFailedAds = true   // Now respected by app open ads
-    maxRetryAttempts = 3        // Used instead of hardcoded value
-}
-```
+### Splash Auto-Navigation Fix
+Orphaned timeouts no longer fire stale `onFailedToLoad` callbacks after the ad has already loaded — preventing the splash from navigating away while the ad is still displayed.
 
-### Late-Loading Ad Preservation
-App open ads that load after the timeout has fired are now cached for later use instead of being discarded. The next `showAdIfAvailable()` call will use the cached ad instantly.
+### Resume Ad Show After Auto-Reload
+`showAdIfAvailable()` no longer skips when a background auto-reload preload is running. App open ads now show correctly on resume after auto-reload.
 
 For previous versions, see the [Changelog](CHANGELOG.md) or individual [release notes](docs/release-notes/).
 
@@ -117,15 +113,15 @@ dependencyResolutionManagement {
 <td>
 
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v3.4.2'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v3.4.2'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v3.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v3.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v3.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v3.4.3'
 
 // For Jetpack Compose support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v3.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v3.4.3'
 
 // For Yandex Ads multi-provider support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v3.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v3.4.3'
 ```
 
 </td>
@@ -253,7 +249,7 @@ Add Yandex (or other providers) as fallback ad networks with zero changes to you
 
 ```groovy
 // Add Yandex module
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v3.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v3.4.3'
 ```
 
 ```kotlin
@@ -603,6 +599,7 @@ AppPurchase.getInstance().changeSubscription(
 - [Multi-Provider Waterfall](docs/MULTI_PROVIDER_WATERFALL.md)
 - [Yandex Integration](docs/YANDEX_INTEGRATION.md)
 - [Billing Integration Guide](docs/APP_PURCHASE_GUIDE.md)
+- [Release Notes v3.4.3](docs/release-notes/RELEASE_NOTES_v3.4.3.md)
 - [Release Notes v3.4.2](docs/release-notes/RELEASE_NOTES_v3.4.2.md)
 - [Release Notes v3.4.1](docs/release-notes/RELEASE_NOTES_v3.4.1.md)
 - [Release Notes v3.4.0](docs/release-notes/RELEASE_NOTES_v3.4.0.md)
diff --git a/admanagekit-billing/build.gradle.kts b/admanagekit-billing/build.gradle.kts
@@ -51,7 +51,7 @@ afterEvaluate {
                 from(components["release"])  // Now works correctly
                 groupId = "com.github.i2hammad"
                 artifactId = "ad-manage-kit-billing"
-                version = "3.4.2"
+                version = "3.4.3"
             }
         }
     }
diff --git a/admanagekit-compose/build.gradle.kts b/admanagekit-compose/build.gradle.kts
@@ -84,7 +84,7 @@ afterEvaluate {
                 from(components["release"])
                 groupId = "com.github.i2hammad"
                 artifactId = "ad-manage-kit-compose"
-                version = "3.4.2"
+                version = "3.4.3"
             }
         }
     }
diff --git a/admanagekit-core/build.gradle.kts b/admanagekit-core/build.gradle.kts
@@ -44,7 +44,7 @@ afterEvaluate {
                 from(components["release"])  // Now works correctly
                 groupId = "com.github.i2hammad"
                 artifactId = "ad-manage-kit-core"
-                version = "3.4.2"
+                version = "3.4.3"
             }
         }
     }
diff --git a/admanagekit-yandex/build.gradle.kts b/admanagekit-yandex/build.gradle.kts
@@ -44,7 +44,7 @@ afterEvaluate {
                 from(components["release"])
                 groupId = "com.github.i2hammad"
                 artifactId = "ad-manage-kit-yandex"
-                version = "3.4.2"
+                version = "3.4.3"
             }
         }
     }
diff --git a/app/src/main/java/com/i2hammad/admanagekit/sample/MyApplication.kt b/app/src/main/java/com/i2hammad/admanagekit/sample/MyApplication.kt
@@ -1,6 +1,7 @@
 package com.i2hammad.admanagekit.sample
 
 import android.app.Application
+import androidx.lifecycle.ViewModelProvider.NewInstanceFactory.Companion.instance
 import com.google.android.gms.ads.MobileAds
 import com.google.android.gms.ads.RequestConfiguration
 import com.i2hammad.admanagekit.admob.AppOpenManager
@@ -63,8 +64,8 @@ class MyApplication : Application() {
             maxCachedAdsPerUnit = 3
             maxCacheMemoryMB = 50
             enableWelcomeBackDialog = true
-            appOpenFetchFreshAd = true
-            appOpenAutoReload = false
+            appOpenFetchFreshAd = false
+            appOpenAutoReload = true
             welcomeDialogAppIcon = R.mipmap.ic_launcher_round
             
             // =================== RELIABILITY FEATURES ===================
@@ -96,7 +97,7 @@ class MyApplication : Application() {
             // - Fetches fresh ad with loading dialog if cache is empty
             // - Good balance between UX and ad coverage
             interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
-            appOpenLoadingStrategy = AdLoadingStrategy.ON_DEMAND
+            appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
             nativeLoadingStrategy = AdLoadingStrategy.HYBRID
 
             // Option 2: ONLY_CACHE - Best for smooth UX (gaming apps)
@@ -187,11 +188,17 @@ class MyApplication : Application() {
         ))
 
         // Configure provider chains: Yandex first, AdMob fallback
-        AdProviderConfig.setInterstitialChain(listOf(yandex.interstitialProvider, admob.interstitialProvider))
-        AdProviderConfig.setBannerChain(listOf(yandex.bannerProvider, admob.bannerProvider))
-        AdProviderConfig.setNativeChain(listOf(yandex.nativeProvider, admob.nativeProvider))
-        AdProviderConfig.setAppOpenChain(listOf(yandex.appOpenProvider, admob.appOpenProvider))
-        AdProviderConfig.setRewardedChain(listOf(yandex.rewardedProvider, admob.rewardedProvider))
+        AdProviderConfig.setInterstitialChain(listOf(admob.interstitialProvider, yandex.interstitialProvider))
+        AdProviderConfig.setBannerChain(listOf(admob.bannerProvider, yandex.bannerProvider))
+        AdProviderConfig.setNativeChain(listOf(admob.nativeProvider, yandex.nativeProvider))
+//        AdProviderConfig.setAppOpenChain(listOf(admob.appOpenProvider, yandex.appOpenProvider))
+        AdProviderConfig.setRewardedChain(listOf(admob.rewardedProvider, yandex.rewardedProvider))
+//       // Configure provider chains: Yandex first, AdMob fallback
+//        AdProviderConfig.setInterstitialChain(listOf(yandex.interstitialProvider, admob.interstitialProvider))
+//        AdProviderConfig.setBannerChain(listOf(yandex.bannerProvider, admob.bannerProvider))
+//        AdProviderConfig.setNativeChain(listOf(yandex.nativeProvider, admob.nativeProvider))
+//        AdProviderConfig.setAppOpenChain(listOf(yandex.appOpenProvider, admob.appOpenProvider))
+//        AdProviderConfig.setRewardedChain(listOf(yandex.rewardedProvider, admob.rewardedProvider))
     }
 
     private fun initBilling() {
diff --git a/app/src/main/java/com/i2hammad/admanagekit/sample/SplashActivity.kt b/app/src/main/java/com/i2hammad/admanagekit/sample/SplashActivity.kt
@@ -75,7 +75,7 @@ class SplashActivity : AppCompatActivity() {
             statusTextView.text = "Consent Requested."
 
             adsConsentManager.requestUMP(
-                this@SplashActivity, true, "EC60C39375F6619F5C03850A0E440646", true
+                this@SplashActivity, false, "EC60C39375F6619F5C03850A0E440646", false
             ) { isUserAccepted ->
                 if (isUserAccepted) {
                     Log.d("SplashActivity", "requestUMP: Consent accepted by user")
diff --git a/docs/release-notes/RELEASE_NOTES_v3.4.3.md b/docs/release-notes/RELEASE_NOTES_v3.4.3.md
@@ -0,0 +1,80 @@
+# Release Notes - v3.4.3
+
+**Release Date**: March 6, 2026
+
+## Overview
+
+v3.4.3 fixes several race conditions in `AppOpenManager` that caused duplicate ad loads, missed ad shows, and auto-navigation on splash screens — with both waterfall and non-waterfall (single-provider) setups.
+
+---
+
+## What's New
+
+### Duplicate Ad Load Prevention
+
+When multiple code paths (e.g. `onStart` background preload and splash `fetchAd`) triggered concurrent waterfall loads, the same ad could be fetched twice. `fetchViaWaterfall(callback, timeout)` now checks if a load is already in progress and attaches to it instead of starting a duplicate.
+
+- If a **dialog-based fetch** is running, the callback is attached to `dialogFetchCallback`
+- If a **background preload** is running (excluded-activity preload), the callback is attached to `pendingFetchCallback` with proper timeout handling
+- Works for both **waterfall** (`fetchViaWaterfall`) and **non-waterfall** (`fetchAdWithRetry`) paths
+
+---
+
+### Splash Auto-Navigation Fix
+
+When the splash screen's `fetchAd` callback attached to an in-progress background preload, orphaned timeouts could fire `onFailedToLoad` after the ad had already loaded and shown — causing the splash to navigate away while the ad was still displayed.
+
+**Before:** Multiple `fetchViaWaterfall(callback, timeout)` calls each created timeouts, but only the last was tracked. Earlier timeouts fired stale callbacks.
+
+**After:** Previous pending timeouts are cancelled before creating new ones. All completion paths (load, fail, timeout) clear `pendingFetchCallback` state.
+
+---
+
+### Resume App Open Ad Show After Auto-Reload
+
+`showAdIfAvailable()` was blocked by `isLoading` from a background auto-reload preload, preventing app open ads from showing on resume.
+
+**Before:** After dismissing an app open ad, `appOpenAutoReload` triggered `fetchViaWaterfall()` which set `isLoading=true`. The immediate `onStart` → `showAdIfAvailable()` saw `isLoading=true` and skipped.
+
+**After:** `showAdIfAvailable()` only skips for dialog-based fetches (`isFetchingWithDialog`), not background preloads. Background preloads don't block ad display since they're non-interactive.
+
+---
+
+### Comprehensive Ad Lifecycle Logging
+
+All paths in `AppOpenManager` now emit `AdDebugUtils.logEvent` events:
+- **`loading`**: Logged when any ad load request starts (`fetchAdWithRetry`, `fetchAd(callback)`, `showAdWithWelcomeDialog`, `fetchAndShowFresh`)
+- **`showCachedAd`**: Logged when a cached ad is about to be shown (both regular and forced paths)
+- **`onAdLoaded` / `onFailedToLoad`**: Already present, now added to dialog-based and waterfall paths that were previously missing
+
+---
+
+## Full Changelog
+
+- **Fixed**: Duplicate ad loads on cold start when `onStart` preload and splash `fetchAd` run concurrently (both waterfall and non-waterfall)
+- **Fixed**: Splash auto-navigation caused by orphaned `pendingFetchTimeoutRunnable` firing stale `onFailedToLoad` callbacks
+- **Fixed**: `showAdIfAvailable()` blocked by background auto-reload preload, preventing app open ads on resume
+- **Fixed**: ON_DEMAND strategy cold start no longer triggers automatic ad load from `onStart` (explicit `fetchAd`/`forceShow` handles it)
+- **Fixed**: Hot-start duplicate loads when returning to SplashActivity
+- **Added**: `pendingFetchCallback` mechanism to attach splash callbacks to in-progress background preloads
+- **Added**: `hasBeenBackgrounded` flag to distinguish cold start from resume for ON_DEMAND strategy
+- **Added**: `loading` log event to all ad load start paths (background preload, dialog fetch, fresh fetch, timeout fetch)
+- **Added**: `showCachedAd` log event when cached ads are shown (regular and forced paths)
+- **Added**: `AdDebugUtils.logEvent` calls to all previously missing load/failure paths in `AppOpenManager`
+
+---
+
+## Installation
+
+```groovy
+// Core modules
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v3.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v3.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v3.4.3'
+
+// Jetpack Compose support
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v3.4.3'
+
+// Yandex provider (optional)
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v3.4.3'
+```

Original file line number	Diff line number	Diff line change
`@@ -68,7 +68,7 @@ afterEvaluate {`
`68`	`68`	`from(components["release"])`
`69`	`69`	`groupId = "com.github.i2hammad"`
`70`	`70`	`artifactId = "ad-manage-kit"`
`71`		`- version = "3.4.2"`
	`71`	`+ version = "3.4.3"`
`72`	`72`	`}`
`73`	`73`
`74`	`74`
Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,7 @@ afterEvaluate {`
`51`	`51`	`from(components["release"]) // Now works correctly`
`52`	`52`	`groupId = "com.github.i2hammad"`
`53`	`53`	`artifactId = "ad-manage-kit-billing"`
`54`		`- version = "3.4.2"`
	`54`	`+ version = "3.4.3"`
`55`	`55`	`}`
`56`	`56`	`}`
`57`	`57`	`}`
Original file line number	Diff line number	Diff line change
`@@ -84,7 +84,7 @@ afterEvaluate {`
`84`	`84`	`from(components["release"])`
`85`	`85`	`groupId = "com.github.i2hammad"`
`86`	`86`	`artifactId = "ad-manage-kit-compose"`
`87`		`- version = "3.4.2"`
	`87`	`+ version = "3.4.3"`
`88`	`88`	`}`
`89`	`89`	`}`
`90`	`90`	`}`
Original file line number	Diff line number	Diff line change
`@@ -44,7 +44,7 @@ afterEvaluate {`
`44`	`44`	`from(components["release"]) // Now works correctly`
`45`	`45`	`groupId = "com.github.i2hammad"`
`46`	`46`	`artifactId = "ad-manage-kit-core"`
`47`		`- version = "3.4.2"`
	`47`	`+ version = "3.4.3"`
`48`	`48`	`}`
`49`	`49`	`}`
`50`	`50`	`}`