功能开关（Feature flags）
功能开关（feature flag）是应用或网站中某项功能的开/关切换。您在 Control Panel 中切换它，无需发布新版本。
您可以为每个开关选择谁能获得该功能：某个细分中的用户、所有用户中的一定比例，或两者兼有。例如，先向 10% 的用户展示新界面，然后再提高比例。如果出现问题，您可以使用 对所有人关停 按钮为所有人关闭该功能。开关还可以携带属性，例如按钮颜色或折扣上限，您可以按受众分别设置。
开始之前
Anchor link to- 套餐： 功能开关仅在包含该功能的套餐中可用。在其他套餐中，受众 菜单中不会显示 功能开关。如需开通，请联系您的客户经理。
- 访问权限： 功能开关 会出现在您可以查看的每个应用中。要创建和更改开关，您需要 修改应用 权限，或在该应用的应用特定权限中拥有相同权限。
- 开发者设置： 只有当您的开发者在应用或网站代码中通过键读取开关后，开关才会对用户生效。他们需要 Web SDK 3.94.1 或更高版本、Android SDK 6.16.0 或更高版本，或 iOS SDK 7.2.10 或更高版本。在尚无开关的应用中，功能开关 页面会显示适用于 Web、Android 和 iOS 的现成代码示例。请将它们连同开关的键一起交给您的开发者。请将 Web SDK 指南、Android SDK 指南或 iOS SDK 指南分享给他们。
如果您的套餐不再包含功能开关，设备将不再接收开关，您的应用或网站将使用代码中设置的值。此时创建或恢复开关会失败，并显示消息 您的套餐不支持功能开关，例如在套餐变更前已打开的 Control Panel 标签页中。
开关如何决定每个用户获得什么
Anchor link to每个开关都有一个规则列表。每条规则包含一个细分、为其开启开关的用户比例（灰度比例，%）以及可选的属性值。对于每台设备，Pushwoosh 会从上到下检查规则：
- 设备匹配其细分的第一条规则起决定作用。没有细分的规则匹配所有设备。
- 规则的 灰度比例，% 决定该用户是否开启开关。设为 20% 时，每十个用户中有两个开启。
- 开启开关的用户会获得该规则中设置的属性值。关闭开关的用户会获得默认属性值。
设备一旦匹配某条规则，后续规则就会被跳过，即使该规则为它关闭了开关。不匹配任何规则的设备，开关为关闭。
用户每次访问都会得到相同的结果。使用相同 User ID 登录的设备在匹配同一条规则时会得到相同的结果，因为 Pushwoosh 会针对每台设备检查细分。Pushwoosh 通过 User ID 识别用户，未设置 User ID 时则通过设备 ID 识别。当您提高比例时，已开启开关的用户会保留它，新用户会加入他们。
创建开关
Anchor link to-
前往 受众 → 功能开关。
-
点击 创建功能开关。
-
输入 键，例如
new_checkout。键可以是您选择的任意名称，但您的开发者会在代码中按这个完全相同的键（包括大小写）读取开关。请在保存开关之前与他们商定。 -
输入 名称，并可选填写 描述，以便您的团队了解该开关控制什么。
键须遵循以下规则：
- 拉丁字母、数字、
_、.和-，最多 58 个字符。 - 键在之后无法更改。
- 您不能重复使用该应用中另一个开关（即使已归档）已使用的键，也不能使用仅大小写不同的键，例如
New_Checkout和new_checkout。
添加属性
Anchor link to属性是应用或网站从开关中读取的值，例如横幅文本或推荐区块中的商品数量。如果开关只用于开启和关闭某项功能，请跳过此步骤。
- 在 属性 中，点击 添加属性。
- 输入 属性键，例如
button_color。使用拉丁字母、数字和_，最多 64 个字符。属性键可以是您选择的任意名称，但您的开发者会在代码中按这个完全相同的键（包括大小写）读取该值。请在保存开关之前与他们商定。 - 选择类型：字符串、数字、布尔值 或 JSON。保存开关后无法更改类型。
- 输入 默认值。关闭开关的用户会获得此值。
一个开关最多可以有 50 个属性。
添加规则
Anchor link to- 在 规则 中，点击 添加规则。
- 输入 规则名称，例如
Paying customers。 - 在 分群 中，选择规则适用的对象。留空则规则适用于所有用户。
- 在 灰度比例，% 中，输入该细分中开启开关的用户比例，范围为 0 到 100，最多两位小数。
- 在 此规则为用户开启开关时使用的值 中，更改对这些用户应与默认值不同的属性。未更改的属性保留其默认值。
- 要添加其他受众，请重复上述步骤。使用 上移 和 下移 更改顺序，因为第一条匹配的规则起决定作用。
一个开关最多可以有 10 条规则。
在 灰度比例，% 下方，每条规则会显示它大约为多少台设备开启开关，例如 ≈ 1,200 台设备。Pushwoosh 将规则细分的大小乘以比例。对于没有细分的规则，则取该应用的所有设备。请将这个数字理解为该规则最多能触达的设备数，因为匹配了前面某条规则的设备会停在那条规则上。
例如，要为所有付费客户以及其他所有人中的 20% 提供新的结账流程，请创建两条规则：
| 规则 | 细分 | 灰度比例，% | 此规则为用户开启开关时使用的值 |
|---|---|---|---|
| Paying customers | Purchased something | 100 | button_color = green，show_apple_pay = true |
| Everyone else | — | 20 | button_color = orange |
保存开关
Anchor link to点击 保存。开关创建后状态为 已启用，设备会在下次检查开关时接收它。
管理开关
Anchor link to开关列表显示每个开关的名称、键、状态、规则数量和最后更新时间。要查看已归档的开关，请打开 显示已归档。要打开某个开关，请点击它的名称。列表顶部和每个开关页面顶部的 SDK 支持 区块会显示该应用中使用旧版 SDK 的设备所占比例（前提是这些设备上报了 SDK 版本）。在用户更新应用之前，这些设备不会获得开关。
开关有以下三种状态之一：
| 状态 | 用户获得什么 | 操作 |
|---|---|---|
| 已启用 | 开关按其规则工作。 | 重新打乱、对所有人关停、归档 |
| 已关停 | 开关对所有用户关闭，使用默认属性值。规则和属性会保留。 | 重新开启、归档 |
| 已归档 | 设备不再接收该开关，因此代码使用您的开发者在其中设置的值。 | 恢复 |
更改开关
Anchor link to- 打开开关。
- 编辑名称、描述、属性或规则。
- 点击 保存。
- 如果您更改了规则或默认属性值，确认变更 对话框会列出设备将发生的变化。检查后点击 保存。
对话框中每项更改显示一行：
- 规则的灰度比例： 大约有多少台设备新获得开关，或有多少台设备失去开关。
- 规则的值： 大约有多少台设备获得新值，以及每个属性的旧值和新值。
- 新增或删除的规则、不同的细分或新的规则顺序： 设备会移到哪里。例如，被删除规则的设备会移到下一条与其匹配的规则。
- 默认值： 开关关闭的设备获得的旧值和新值。
仅更改名称或描述时，会直接保存，不显示该对话框。
要逐步推出功能，请分步提高规则的 灰度比例，%。
如果在您编辑期间其他人保存了该开关，Control Panel 不会覆盖他们的更改，并会要求您重新加载开关。点击 重新加载，然后重新进行更改。
为所有人关闭开关
Anchor link to当某项功能引发问题、需要为所有人停用时，请使用 对所有人关停：
-
打开开关并点击 对所有人关停。
-
确认。每台设备会在下次检查开关时获得关闭状态和默认属性值。
当您的网站或应用处于打开状态时，设备会在一小时内获得此更改。请参阅 Web SDK、Android SDK 和 iOS SDK 如何检查开关。
要按原有规则重新开启开关，请点击 重新开启。
选择不同的用户样本
Anchor link to重新打乱会将每个用户放入新的分组，因此相同比例的用户由不同的人组成。当您需要新的样本时（例如开始新的测试）可以使用它。
- 打开一个活动开关并点击 重新打乱。
- 确认。部分已开启开关的用户会失去它，另一些用户会在其设备下次检查开关时获得它，而比例保持不变。
归档和恢复开关
Anchor link to当功能已完全发布或已从代码中移除时，请归档开关。已归档的开关不计入您套餐中每个应用的开关数量上限，其键仍保持保留状态。
- 打开开关并点击 归档。
- 确认。
已归档的开关无法编辑。要恢复它，请在列表中打开 显示已归档，打开该开关，然后点击 恢复。恢复的开关状态为 已关停，因此不会自行触达用户。准备就绪后，点击 重新开启。
查看谁更改了开关
Anchor link to变更历史显示开关的每个已保存版本：更改了什么、由谁更改以及何时更改。任何可以打开该开关的人都可以查看其历史。
历史记录从 2026 年 10 月 13 日起的更改开始记录。没有记录任何更改的开关会显示 暂无变更。对于在该日期之前创建的开关，最早的条目不显示更改列表，因为没有更早的版本可供比较。
- 打开开关。
- 点击 历史。
变更历史 面板按从新到旧的顺序列出开关的各个版本。每个条目显示：
- 操作，例如 已编辑。
- 更改者：用户的电子邮件，或进行更改所用的 API 令牌，例如 API 令牌“Release pipeline”，未命名的令牌则显示 API 令牌。
- 日期和时间。
- 版本号，例如 v4。
要加载更早的条目，请点击 显示更多。
| 操作 | 发生了什么 |
|---|---|
| 已创建 | 开关已创建。 |
| 已编辑 | 有人保存了对开关的更改。 |
| 发布比例已更改 | 通过 API 或 MCP 服务器更改了某条规则的灰度比例。在 Control Panel 中，灰度比例的更改会记录为 已编辑。 |
| 已关闭 | 有人点击了 对所有人关停。 |
| 已重新开启 | 有人点击了 重新开启。 |
| 已归档 | 开关已归档。 |
| 已恢复 | 开关已从归档中恢复。 |
| 用户已重新分配 | 有人点击了 重新打乱。 |
在每个条目下方，面板以更改前和更改后的值列出更改内容：名称、描述、状态、属性、规则顺序，以及每条新增、删除或更改的规则。对于更改的规则，只显示不同的字段：名称、细分、发布比例 或 值。没有细分的规则显示 所有用户。
按开关对用户进行细分
Anchor link to细分中的功能开关条件可以找到开启了开关、关闭了开关、匹配了其某条规则，或到达了开关所控制的应用部分的设备。您可以用它向看到新功能的用户发送消息（例如征求反馈），或围绕他们构建 Journey。
- 打开细分构建器，如如何创建细分中所述。
- 在条件列表中点击 功能开关。
- 在 选择功能开关… 中选择开关。已归档的开关不在列表中。
- 选择状态：
- 已开启：开启了开关的设备。
- 已关闭：关闭了开关的设备。
- 属于规则：匹配了某条规则细分的设备，无论该规则的 灰度比例，% 是否为它们开启了开关。在 选择规则… 中选择规则。
- 看到过该功能（30 天）：在过去 30 天内至少发送过一次该开关曝光的设备，即应用为此开关键调用了
logImpression。请参阅查找到达某项功能的用户。
功能开关 仅在包含功能开关的套餐中出现在细分构建器中。只能包含标签条件的 High Speed Delivery 细分不能使用它。
每种状态包含哪些设备
Anchor link to设备的状态取决于它最近一次收到的开关以及开关的当前状态：
- 从未请求过该开关的设备（例如其 SDK 不读取开关）不属于任何状态。
- 在您更改规则或规则的 灰度比例，% 后，设备只有在再次请求开关时才会转入另一个状态。
- 当您关停或归档开关时，已开启 和 属于规则 会在约 10 秒内变为空，无需等待设备再次请求开关。此时 已关闭 包含所有曾经获得过该开关的设备。
查找到达某项功能的用户
Anchor link to要查找看到了已启用功能的用户：
- 为该开关添加 看到过该功能（30 天）。
- 为同一开关添加 已开启，并用 AND 连接这两个条件。
看到过该功能（30 天） 匹配到达了开关所控制的界面或代码的用户，无论开关对他们是开启还是关闭。因此需要添加 已开启：它只保留获得新版本的用户。结果接近但并不精确。已开启 反映的是设备最近一次获得的开关，而其曝光可能来自开关关闭时的早前访问。
如果应用不记录曝光，该细分将为空。要记录曝光，请参阅 Web SDK、Android SDK 或 iOS SDK 指南中的“Log impressions”部分。
关停或归档开关不会清空此状态。设备会在最后一次曝光 30 天后离开该状态。
在 Journey 中使用开关细分
Anchor link to带有功能开关条件的细分可用于基于受众的进入和条件拆分。例如，将获得新结账流程的用户与未获得的用户分开，并向每组发送各自的消息。
保存开关时，Control Panel 和 API 会强制执行以下限制：
| 限制 | 值 |
|---|---|
| 每个开关的规则数 | 10 |
| 每个开关的属性数 | 50 |
| 单个开关的属性大小（键、类型和默认值） | 10,000 字节 |
| JSON 值的嵌套深度 | 5 层 |
| 每个应用的开关数 | 由您的套餐决定，已归档的开关不计入 |
| 单台设备为该应用所有开关接收的数据量 | 64 KB |
通过 API 管理开关
Anchor link to您的开发者可以使用 Feature Flags API 从自己的系统中创建和更改开关，通过 Pushwoosh MCP 服务器连接的 AI 助手也可以使用相同的操作管理开关。