Android 展示编排队列：用 Handler 思想统一管理广告、推送与弹窗

/** 展示请求：队列中的「一条消息」 */
data class PresentationRequest(
    val id: String,
    val type: PresentationType,
    val priority: Int,
    val dedupeKey: String? = null,
    val expireAt: Instant? = null,
    val payload: PresentationPayload,
)
 
enum class PresentationType {
    PRIVACY_CONSENT,
    FORCE_UPDATE,
    SPLASH_AD,
    APP_OPEN_AD,
    IN_APP_MESSAGE,
    OPS_DIALOG,
    INTERSTITIAL_AD,
    REWARDED_AD,
}
 
sealed interface PresentationPayload {
    data class AdSlot(val slotId: String) : PresentationPayload
    data class PushMessage(val campaignId: String, val content: PushContent) : PresentationPayload
    data class Update(val versionCode: Int, val force: Boolean) : PresentationPayload
    data object PrivacyConsent : PresentationPayload
    data class OpsDialog(val templateId: String) : PresentationPayload
}
 
/** 处理结果：类似 Handler 处理完一条 message */
sealed interface PresentationResult {
    data object Shown : PresentationResult
    data object Skipped : PresentationResult
    data object Expired : PresentationResult
    data class Failed(val error: Throwable) : PresentationResult
}

interface PresentationOrchestrator {
    /** 入队；若当前空闲则立即调度 */
    fun enqueue(request: PresentationRequest)
 
    /** 取消某 dedupeKey 或 id */
    fun cancel(id: String)
    fun cancelByDedupeKey(key: String)
 
    /** 观察队列与当前展示（调试、埋点） */
    val state: StateFlow<OrchestratorState>
 
    /** 绑定前台 Activity，供展示器消费 */
    fun bindHost(host: PresentationHost)
 
    fun unbindHost(host: PresentationHost)
}
 
data class OrchestratorState(
    val current: PresentationRequest?,
    val pendingCount: Int,
    val isProcessing: Boolean,
)
 
sealed class PresentationHost {
    data class ActivityHost(
        val activity: FragmentActivity,
        val lifecycleOwner: LifecycleOwner = activity,
    ) : PresentationHost()
}

class DefaultPresentationOrchestrator(
    private val scope: CoroutineScope,
    private val handlers: Map<PresentationType, PresentationHandler>,
    private val policy: PresentationPolicy,
    private val reporter: PresentationReporter,
) : PresentationOrchestrator {
 
  private val queue = PriorityBlockingQueue<PresentationRequest>(
      compareBy({ it.priority }, { it.enqueueTime })
  )
  private val mutex = Mutex()
  private var processing = false
 
  private val _state = MutableStateFlow(OrchestratorState(null, 0, false))
  override val state: StateFlow<OrchestratorState> = _state.asStateFlow()
 
  @Volatile
  private var boundHost: PresentationHost? = null
 
  override fun enqueue(request: PresentationRequest) {
      if (!policy.canEnqueue(request)) {
          reporter.skipped(request, "policy_deny")
          return
      }
      request.dedupeKey?.let { key ->
          queue.removeIf { it.dedupeKey == key }
      }
      queue.offer(request.copy(enqueueTime = System.nanoTime()))
      _state.update { it.copy(pendingCount = queue.size) }
      trySchedule()
  }
 
  private fun trySchedule() {
      scope.launch {
          mutex.withLock {
              if (processing) return@withLock
              processing = true
          }
          processLoop()
      }
  }
 
  private suspend fun processLoop() {
      while (true) {
          val host = awaitValidHost() ?: break
          val next = pollValidRequest() ?: break
 
          _state.update {
              OrchestratorState(current = next, pendingCount = queue.size, isProcessing = true)
          }
 
          val handler = handlers[next.type] ?: continue
          val result = runCatching {
              handler.present(host, next)
          }.getOrElse { PresentationResult.Failed(it) }
 
          reporter.completed(next, result)
          _state.update {
              OrchestratorState(current = null, pendingCount = queue.size, isProcessing = false)
          }
      }
      mutex.withLock { processing = false }
  }
}

interface PresentationHandler {
    val type: PresentationType
    suspend fun present(
        host: PresentationHost,
        request: PresentationRequest,
    ): PresentationResult
}
 
/** 广告：委托 AdManager，挂起直到 onDismiss */
class AdPresentationHandler(
    private val adManager: AdManager,
) : PresentationHandler {
    override val type = PresentationType.INTERSTITIAL_AD
 
    override suspend fun present(
        host: PresentationHost,
        request: PresentationRequest,
    ): PresentationResult = suspendCancellableCoroutine { cont ->
        val slot = (request.payload as PresentationPayload.AdSlot).slotId
        val activityHost = host as PresentationHost.ActivityHost
 
        adManager.show(
            slotId = slot,
            host = AdHost.ActivityHost(activityHost.activity),
            listener = object : AdShowListener {
                override fun onDismissed() {
                    if (cont.isActive) cont.resume(PresentationResult.Shown)
                }
                override fun onFailed() {
                    if (cont.isActive) cont.resume(PresentationResult.Skipped)
                }
            }
        )
    }
}

class App : Application() {
    @Inject lateinit var orchestrator: PresentationOrchestrator
 
    override fun onCreate() {
        super.onCreate()
        registerActivityLifecycleCallbacks(object : ActivityLifecycleCallbacks {
            override fun onActivityResumed(activity: Activity) {
                if (activity is FragmentActivity) {
                    orchestrator.bindHost(
                        PresentationHost.ActivityHost(activity)
                    )
                }
            }
            override fun onActivityPaused(activity: Activity) {
                if (activity is FragmentActivity) {
                    orchestrator.unbindHost(
                        PresentationHost.ActivityHost(activity)
                    )
                }
            }
            // 其他空实现省略
        })
    }
}

ProcessLifecycleOwner.get().lifecycle.currentStateFlow()
    .filter { it.isAtLeast(Lifecycle.State.STARTED) }
    .collect { /* 恢复调度 */ }

// 推送 SDK 回调
fun onInAppMessageReceived(message: InAppMessage) {
    orchestrator.enqueue(
        PresentationRequest(
            id = message.id,
            type = PresentationType.IN_APP_MESSAGE,
            priority = 30,
            dedupeKey = "push_${message.campaignId}",
            payload = PresentationPayload.PushMessage(message.campaignId, message.toContent()),
        )
    )
}

interface PresentationPolicy {
    fun canEnqueue(request: PresentationRequest): Boolean
    fun canProcess(request: PresentationRequest, host: PresentationHost): Boolean
}
 
class DefaultPresentationPolicy(
    private val dataStore: PresentationDataStore,
) : PresentationPolicy {
 
    override fun canEnqueue(request: PresentationRequest): Boolean {
        request.expireAt?.let { if (Instant.now().isAfter(it)) return false }
 
        // 今日已展示过的运营弹窗
        if (request.type == PresentationType.OPS_DIALOG) {
            if (dataStore.isShownToday(request.dedupeKey)) return false
        }
        return true
    }
 
    override fun canProcess(request: PresentationRequest, host: PresentationHost): Boolean {
        val activity = (host as PresentationHost.ActivityHost).activity
        // 登录页、支付页不打断
        if (activity is BlocklistedForPresentation) return false
        return true
    }
}

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        val orch = entryPoint.presentationOrchestrator()
 
        orch.enqueue(
            PresentationRequest(
                id = "privacy_v1",
                type = PresentationType.PRIVACY_CONSENT,
                priority = 0,
                dedupeKey = "privacy_consent",
                payload = PresentationPayload.PrivacyConsent,
            )
        )
 
        if (RemoteConfig.splashAdEnabled) {
            orch.enqueue(
                PresentationRequest(
                    id = "splash_cold",
                    type = PresentationType.SPLASH_AD,
                    priority = 20,
                    dedupeKey = "splash_cold_start",
                    expireAt = Instant.now().plusSeconds(30),
                    payload = PresentationPayload.AdSlot(AdSlots.SPLASH_COLD),
                )
            )
        }
    }
}

@Module
@InstallIn(SingletonComponent::class)
object PresentationModule {
 
    @Provides @Singleton
    fun provideOrchestrator(
        @ApplicationScope scope: CoroutineScope,
        handlers: Set<@JvmSuppressWildcards PresentationHandler>,
        policy: PresentationPolicy,
        reporter: PresentationReporter,
    ): PresentationOrchestrator = DefaultPresentationOrchestrator(
        scope = scope,
        handlers = handlers.associateBy { it.type },
        policy = policy,
        reporter = reporter,
    )
}
 
@Module
@InstallIn(SingletonComponent::class)
abstract class PresentationHandlerModule {
    @Binds @IntoSet abstract fun bindAd(handler: AdPresentationHandler): PresentationHandler
    @Binds @IntoSet abstract fun bindPush(handler: PushPresentationHandler): PresentationHandler
    @Binds @IntoSet abstract fun bindPrivacy(handler: PrivacyPresentationHandler): PresentationHandler
}

@Composable
fun PresentationOverlay(
    orchestrator: PresentationOrchestrator = hiltViewModel<ShellViewModel>().orchestrator,
) {
    val state by orchestrator.state.collectAsStateWithLifecycle()
    val push = state.current?.takeIf { it.type == PresentationType.IN_APP_MESSAGE }
 
    push?.let { req ->
        val content = (req.payload as PresentationPayload.PushMessage).content
        AlertDialog(
            onDismissRequest = { /* 通知 Handler 完成 */ },
            title = { Text(content.title) },
            text = { Text(content.body) },
            confirmButton = { TextButton(onClick = { }) { Text("去看看") } },
        )
    }
}

@Test
fun `privacy before splash ad`() = runTest {
    val fake = FakePresentationOrchestrator(testScope)
    fake.enqueue(privacyRequest(priority = 0))
    fake.enqueue(splashRequest(priority = 20))
 
    fake.drainQueue()
 
    assertEquals(
        listOf(PresentationType.PRIVACY_CONSENT, PresentationType.SPLASH_AD),
        fake.shownTypes,
    )
}
 
@Test
fun `expired request is skipped`() = runTest {
    val expired = splashRequest(expireAt = Instant.now().minusSeconds(1))
    fake.enqueue(expired)
    fake.drainQueue()
    assertTrue(fake.shownTypes.isEmpty())
}