Android 广告模块架构：统一管理开屏、插屏、激励与全屏广告

/** 广告形态 */
enum class AdFormat {
    SPLASH,          // 开屏
    INTERSTITIAL,    // 插屏
    REWARDED,        // 激励视频
    APP_OPEN,        // 全屏 / App Open（含部分厂商「全屏视频」）
    BANNER,          // 横幅（可选）
    NATIVE           // 原生（可选）
}
 
/** 广告单元配置：远程可下发 */
data class AdUnitConfig(
    val slotId: String,
    val format: AdFormat,
    val primaryPlacementId: String,
    val fallbackPlacementIds: List<String> = emptyList(),
    val preload: Boolean = true,
    val expireMs: Long = 3_600_000L
)
 
/** 统一状态机 */
sealed interface AdState {
    data object Idle : AdState
    data object Loading : AdState
    data class Ready(val ad: LoadedAd) : AdState
    data class Showing(val ad: LoadedAd) : AdState
    data class Rewarded(val amount: Int, val type: String) : AdState
    data class Failed(val reason: AdError) : AdState
    data object Dismissed : AdState
}
 
/** 对外门面：业务唯一入口 */
interface AdManager {
    fun initialize(app: Application, config: AdSdkConfig)
    suspend fun preload(slotId: String)
    suspend fun show(
        slotId: String,
        host: AdHost,
        listener: AdShowListener = AdShowListener.NO_OP
    ): AdShowResult
    fun observeState(slotId: String): Flow<AdState>
}

interface AdAdapter {
    val networkName: String
    fun supports(format: AdFormat): Boolean
    suspend fun load(
        context: Context,
        placementId: String,
        format: AdFormat
    ): Result<LoadedAd>
    fun show(loadedAd: LoadedAd, host: AdHost, callbacks: InternalAdCallbacks)
    fun destroy(loadedAd: LoadedAd)
}

sealed class AdHost {
    data class ActivityHost(val activity: Activity) : AdHost()
    data class FragmentHost(val fragment: Fragment) : AdHost()
 
    fun lifecycleOwner(): LifecycleOwner = when (this) {
        is ActivityHost -> activity
        is FragmentHost -> fragment.viewLifecycleOwner
    }
 
    fun activity(): Activity = when (this) {
        is ActivityHost -> activity
        is FragmentHost -> fragment.requireActivity()
    }
}

class SplashActivity : AppCompatActivity() {
    private val adManager: AdManager by inject()
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_splash)
 
        lifecycleScope.launch {
            val result = withTimeoutOrNull(4_000) {
                adManager.show(
                    slotId = AdSlots.SPLASH_COLD,
                    host = AdHost.ActivityHost(this@SplashActivity)
                )
            }
            navigateToMain()
        }
    }
}

// ViewModel
fun onLevelCleared() {
    viewModelScope.launch {
        _events.emit(UiEvent.ShowAd(AdSlots.INTERSTITIAL_LEVEL_END))
    }
}
 
// Activity
lifecycleScope.launch {
    viewModel.events.collect { event ->
        if (event is UiEvent.ShowAd) {
            adManager.show(event.slotId, AdHost.ActivityHost(this@GameActivity))
        }
    }
}

adManager.show(
    slotId = AdSlots.REWARDED_DOUBLE_COIN,
    host = AdHost.FragmentHost(this),
    listener = object : AdShowListener {
        override fun onRewarded(amount: Int, type: String) {
            viewModel.grantCoins(amount)
        }
        override fun onDismissed() {
            viewModel.onRewardFlowEnd()
        }
    }
)

class AdLoader(
    private val adapters: List<AdAdapter>,
    private val cache: AdCache
) {
    suspend fun load(slot: AdUnitConfig): Result<LoadedAd> {
        cache.getValid(slot.slotId)?.let { return Result.success(it) }
 
        val errors = mutableListOf<AdError>()
        for (placementId in listOf(slot.primaryPlacementId) + slot.fallbackPlacementIds) {
            val adapter = resolveAdapter(placementId) ?: continue
            adapter.load(appContext, placementId, slot.format)
                .onSuccess { loaded ->
                    cache.put(slot.slotId, loaded, slot.expireMs)
                    return Result.success(loaded)
                }
                .onFailure { errors.add(it as? AdError ?: AdError.Unknown) }
        }
        return Result.failure(AdError.AllSourcesFailed(errors))
    }
}

interface AdPolicy {
    fun canShow(slotId: String, context: PolicyContext): PolicyVerdict
}
 
data class PolicyContext(
    val isVip: Boolean,
    val isChildMode: Boolean,
    val consentGranted: Boolean,
    val lastShowTimestamps: Map<String, Long>,
    val sessionShowCount: Map<String, Int>
)
 
sealed interface PolicyVerdict {
    data object Allow : PolicyVerdict
    data class Deny(val reason: String) : PolicyVerdict
}

Application.onCreate
  → 隐私同意 / UMP 表单
  → AdManager.initialize()（仅一次）
  → 预加载高优先级 slot

:app
  └── :feature-ad          // AdManager 实现、Renderer、Policy
        ├── :lib-ad-api     // 接口、AdHost、AdState（业务仅依赖此 module）
        ├── :lib-ad-admob   // AdMobAdapter（runtimeOnly 或 productFlavor）
        └── :lib-ad-pangle  // 穿山甲 Adapter

@Module
@InstallIn(SingletonComponent::class)
object AdModule {
    @Provides @Singleton
    fun provideAdManager(
        loaders: AdLoader,
        renderers: Set<AdRenderer>,
        policy: AdPolicy,
        reporters: AdReporter
    ): AdManager = DefaultAdManager(loaders, renderers, policy, reporters)
}