iOS 快速入門

幾分鐘之內，你的 iOS 應用程式就會讀到一個真實的 feature flag，而快取、離線回退和裝置身分都已經替你處理好。

需要 iOS 17、macOS 14 或 visionOS 1。SDK 本身沒有任何相依。

1. 安裝

這個 SDK 放在 GitHub 上的公開儲存庫裡，直接從那裡把它當作 Swift Package 加入，在 Xcode 裡（File → Add Package Dependencies…）或在 Package.swift 裡：

.package(url: "https://github.com/FortressFlag/FortressFlag_SDK_ios.git", from: "1.0.0")

2. 啟動 SDK

只做一次，在啟動時。對 SwiftUI 來說，你的 App 的 init 是最自然的位置：

import FortressFlag

FortressFlag.start(
    Configuration(
        sdkKey: "ffc_prod_…",                          // 來自你的專案的 SDK 金鑰畫面
        environment: .production,
        keychainAccessGroup: "com.acme.fortressflag"   // 你出貨的每個應用程式都用同一個字串
    )
)

start 在快取的值載入後就會返回，從那時起 SDK 會在背景輪詢變更。這把金鑰是用戶端金鑰：它設計上就是隨你的應用程式出貨的。

3. 讀取一個 flag

在任何地方，包括 SwiftUI 的 body 裡：

if FortressFlag.isEnabled("new-checkout") {
    NewCheckoutView()
} else {
    LegacyCheckoutView()
}

字串和數字 flag 的讀法一樣（FortressFlag.stringValue("checkout-cta", default: "buy-now")），你也可以用 FortressFlag.onChange 監看變更。

就這樣，你的 flag 上線了。在儀表板切換它，應用程式會在下一次輪詢跟上。

就算 FortressFlag 掛了，你的應用程式也不會

這套 API 裡沒有任何呼叫會拋出例外、阻塞，或讓你的應用程式當掉。每一次讀取都透過一條串接解析：最後收到的值，然後是先前執行留下的持久快取，然後是你呼叫處的預設值。所以一次故障、一條斷掉的網路或一把被撤銷的金鑰，永遠不會觸及你的使用者。

設定鑰匙圈共用：不設定會花你的錢

FortressFlag 按裝置計費，而不是按應用程式。一支手機跑著你的三個應用程式算一個席次，但前提是三者對同一個裝置身分有共識，而在 iOS 上這意味著一個共用的鑰匙圈存取群組：

1. 在每個應用程式 target 裡：Signing & Capabilities → + Capability → Keychain Sharing。
2. 在你的每一個應用程式都加入同一個群組，例如 com.acme.fortressflag。
3. 把那個字串（不含團隊前綴）作為 keychainAccessGroup 傳入。

跳過這步一切照樣能用，但每個應用程式會各存各的身分：一台裝置算成三台計費裝置。發生這種情況時，SDK 會記錄一次警告。

一個平台備註：身分存在鑰匙圈裡，所以在 iOS 上它在應用程式解除安裝後仍然保留，而且它永遠不會同步到 iCloud，所以它永遠不會隨著備份跑到第二台裝置上。

為整合除錯

這個套件附帶第二個函式庫 FortressFlagDebugUI，內含 FlagListView：一個 SwiftUI 畫面，即時顯示這台裝置持有的每個 flag、它的值以及它從哪裡來。這是「SDK 到底有沒有在跟伺服器講話？」最快的答案。

接下來

• Flag 如何送達你的應用程式：那次背景輪詢做了什麼
• 裝置身分與計費：你剛設定好的那個身分
• 設定百分比發布：先出貨給 10%