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 里没有任何调用会抛出、阻塞或让你的应用崩溃。每一次读取都通过一条级联解析——最后收到的值，然后是来自之前运行的持久缓存，然后是你调用处的默认值——所以一次故障、一段断掉的网络或一个被吊销的密钥，永远不会到达你的用户。

设置 keychain 共享——不设会花你的钱

FortressFlag 按设备计费，而不是按应用。一部手机跑着你的三个应用算一个席位——但前提是三个应用就一个设备标识达成一致，而在 iOS 上这意味着一个共享的 keychain 访问组：

1. 在每个应用 target 里：Signing & Capabilities → + Capability → Keychain Sharing。
2. 给你的每一个应用添加同一个组——例如 com.acme.fortressflag。
3. 把这个字符串（不带 team 前缀）作为 keychainAccessGroup 传入。

跳过这一步一切照样能用，但每个应用会存储自己的标识：一台设备算成三台计费设备。当这种情况发生时，SDK 会记录一次警告。

一个平台说明：标识存在 keychain 里，所以在 iOS 上它在应用卸载后仍然保留——而且它从不同步到 iCloud，所以它永远不会跟着备份跑到第二台设备上。

调试一次集成

这个包附带第二个库 FortressFlagDebugUI，其中有 FlagListView——一个 SwiftUI 界面，实时显示这台设备持有的每一个 flag、它的值以及它来自哪里。这是“SDK 到底有没有在和服务器说话？“最快的答案。

接下来去哪

• Flag 如何到达你的应用——那次后台轮询做了什么
• 设备标识与计费——你刚配置的那个标识
• 设置百分比灰度——先发布给 10%