指南

自動換版與事件

新版資料發佈後，App 在前景時最慢約 95 秒就會換到新版，不需要重開；SDK 會先發出 releaseUpdated 事件，你在事件裡重新載入目前畫面即可。

延遲組成

環節	最長延遲
伺服器得知新版已發佈	5 秒
`/v1/release/current` 快取	30 秒
SDK 前景輪詢（`releaseCheckInterval`）	60 秒

SDK 做了什麼

只在前景輪詢，每次帶 ETag，資料沒變時伺服器回 304，幾乎不耗流量。
發現更新的 release 時，只替換預設 session，並發出 releaseUpdated(from, to)。
你自己建立、明確傳入的 session 不會被換掉，用於「同一畫面必須來自同一版」的場合。
同一交易日可能有 .1、.2：部分資料集較晚就緒時，會先發 .1，資料到齊後再補發 .2，SDK 會依序換上。

你要做的事

iOS

// events 是單一消費者的 AsyncStream：全 App 只在一處訂閱，再轉發給各畫面
Task {
    for await event in client.events {
        switch event {
        case .releaseUpdated(let from, let to):
            reloadCurrentScreen()
        case .releaseRevoked(let release):
            reloadCurrentScreen()
        default:
            break
        }
    }
}

iOS 的前景與背景切換由 SDK 自動處理。

Android

override fun onStart() {
    super.onStart()
    watchJob = client.startReleaseWatch(lifecycleScope)
    lifecycleScope.launch {
        client.events.collect { event ->
            when (event) {
                is ClientEvent.ReleaseUpdated -> reloadCurrentScreen()
                else -> Unit
            }
        }
    }
}

override fun onStop() {
    watchJob?.cancel()
    super.onStop()
}

Web SDK 沒有事件與自動輪詢。可自行定期呼叫 getReleaseCurrent()，發現 release 變新時重新載入。

訂閱事件。iOS 的 events 是單一消費者的 AsyncStream；Android 是 SharedFlow。
Android 在 onStart 呼叫 startReleaseWatch(scope)，在 onStop 取消回傳的 Job。
收到 releaseUpdated 時重新載入畫面上的資料。已快取的歷史分塊會沿用，通常只下載本月那一小塊。
對事件做 switch、when 時保留 default、else，未來可能新增事件種類。

撤回

發現已發佈的資料有誤時，後端會撤回該版。SDK 會丟棄該版的快取、重新釘選到上一個有效版本；iOS 另會發出 releaseRevoked，Android 則靜默完成、不發事件。處理方式與 releaseUpdated 相同：重新載入畫面。

事件欄位與觸發條件見事件。