Web SDK 中的功能开关

Pushwoosh.featureFlags 为您的网站提供在 Control Panel 中为该应用配置的功能开关。Pushwoosh 在服务器上针对当前设备和用户评估开关规则，SDK 返回评估结果：该开关是否对此访客开启，以及适用哪些属性值。

前提条件

Web SDK 3.94.1 或更高版本，按照 Web SDK 3.0 指南中的说明从 Pushwoosh CDN 加载；或 web-push-notifications npm 包 3.95.0 或更高版本。
在 Audience → Feature Flags 中至少创建了一个开关。您需要它的 Key 以及其属性的键和类型。请严格按照其中显示的形式使用这些键，包括大小写。例如，get('New_Checkout') 找不到键为 new_checkout 的开关。

读取开关

在 SDK 就绪后读取开关。请始终传入默认值：在 SDK 尚未获得该页面的开关之前，以及当开关不存在、已归档或套餐不包含功能开关时，都会使用该默认值。

Pushwoosh.push(() => {
  const flags = Pushwoosh.featureFlags;

  const render = () => {
    const checkout = flags.get('new_checkout');
    if (checkout && checkout.enabled) {
      showNewCheckout({
        buttonColor: checkout.getString('button_color', 'blue'),
        maxItems: checkout.getNumber('max_items', 3),
      });
    } else {
      showOldCheckout();
    }
  };

  render();
  flags.addUpdateListener(render);
});

使用 npm 包时，请使用您创建的 Pushwoosh 实例：

import { Pushwoosh } from 'web-push-notifications';

const pushwoosh = new Pushwoosh();
pushwoosh.push(['init', { applicationCode: 'XXXXX-XXXXX' /* ... */ }]);

pushwoosh.push(() => {
  const isNewCheckout = pushwoosh.featureFlags.isEnabled('new_checkout', false);
  // ...
});

在您的代码首次调用 get()、isEnabled()、refresh() 或 addUpdateListener() 之前，SDK 不会在页面上发起任何开关请求，因此不使用开关的页面不会产生额外流量。

开关返回的内容

get(key) 返回一个 FeatureFlag 对象；当 SDK 尚未获得该页面的开关，或响应中不包含该开关时，返回 null。已归档的开关不会出现在响应中。该对象包含以下字段：

字段	类型	描述
`key`	string	开关键。
`enabled`	boolean	该开关是否对此访客开启。
`ruleId`	string	决定结果的规则，例如 `r_1a2b3c4d`。没有规则匹配该访客时为 `default`，开关被终止（killed）时为空字符串。

请使用与属性类型匹配的 getter 读取属性值。当属性缺失或其值属于其他类型时，每个 getter 都会返回您的默认值。当开关关闭时，属性保存的是在 Control Panel 中设置的默认值。

方法	返回值
`getString(property, defaultValue)`	String 属性的值。
`getNumber(property, defaultValue)`	Number 属性的值。
`getBool(property, defaultValue)`	Boolean 属性的值。
`getJson(property, defaultValue)`	JSON 属性的值，以解析后的 JSON 值返回。
`getProperties()`	该开关所有属性值的副本。

isEnabled(key, defaultValue) 是 get(key)?.enabled 的简写，没有开关时返回 defaultValue。

保持开关最新

SDK 会将最近一次响应存储在浏览器的 IndexedDB 中，最长 24 小时。存储的开关仅对请求它们时的 User ID 有效。SDK 会在以下情况下刷新开关：

在页面上首次使用时，如果存储的开关超过 15 分钟或不存在；
页面保持打开期间每小时一次；
设备注册后，如果开关是在注册之前请求的；
User ID 变更后立即刷新。上一个用户的存储开关会被丢弃，因此新用户永远不会看到它们。

要响应新值，请注册一个监听器。每次刷新改变了任一开关值后，都会调用它：

const onFlagsChanged = () => render();
Pushwoosh.featureFlags.addUpdateListener(onFlagsChanged);
// later
Pushwoosh.featureFlags.removeUpdateListener(onFlagsChanged);

要自行请求开关，例如在某个可能使访客进入不同 Segment 的操作之后，请调用 refresh()。在存储的开关有效期间，它每 5 分钟最多发送一次请求，并在该时间窗口内立即完成。请求失败时 promise 会被拒绝，存储的开关继续生效。

try {
  await Pushwoosh.featureFlags.refresh();
} catch (error) {
  // the stored flags, or your defaults, stay in effect
}
render();

如果 Pushwoosh 无法及时匹配访客所属的 Segment，它会返回部分响应。SDK 仅在当前页面上、且仅在没有有效的存储开关时使用该响应，并且从不存储它。下一次刷新会带来完整响应。

当某个开关在 Control Panel 中被终止（killed）时，访客会在下一次刷新时获得关闭状态的开关及默认属性值。当 SDK 无法连接服务器时，它会继续使用存储的开关，直到它们存在满 24 小时，此后使用您的默认值。

记录曝光

曝光（impression）告诉 Pushwoosh，访客确实执行到了某个开关所控制的代码，以便您对比获得该功能的访客与未获得该功能的访客。请在访客看到该功能或其旧版本的那一刻调用 logImpression(key)，开启分支和关闭分支都要调用，因为开关关闭的访客就是您的对比组：

const checkout = Pushwoosh.featureFlags.get('new_checkout');
if (checkout) {
  Pushwoosh.featureFlags.logImpression('new_checkout');
}

SDK 会发送带有以下属性的 PW_FeatureFlagImpression 事件：

属性	类型	值
`flag_key`	string	开关键。
`rule_id`	string	决定结果的规则，与 `ruleId` 相同。
`enabled`	boolean	该开关当时是否开启。

您无需事先创建该事件，因为当第一条曝光到达时，Pushwoosh 会将带有这些属性的 PW_FeatureFlagImpression 添加到 Audience → Events 中。SDK 在一个页面上针对每个开关、规则和状态只发送一次曝光，并在 30 分钟内跳过同一浏览器其他标签页中的重复曝光。logImpression() 从不拒绝，当该键没有对应开关时也不会发送任何内容。

借助曝光，营销人员还可以为接触到该功能的访客建立分群：使用功能开关条件的 看到过该功能（30 天） 状态。

方法参考

Pushwoosh.featureFlags 包含以下方法：

方法	描述
`get(key)`	返回该键对应的 `FeatureFlag`，或 `null`。仅读取存储的开关，从不等待网络。
`isEnabled(key, defaultValue)`	返回该开关是否开启；没有开关时返回 `defaultValue`。
`refresh()`	请求开关；在存储的开关有效期间，限制为每 5 分钟一次。返回一个 promise。
`addUpdateListener(listener)`	每次刷新改变了开关值后调用 `listener`。
`removeUpdateListener(listener)`	移除通过 `addUpdateListener` 添加的监听器。
`logImpression(key)`	针对该开关当前的规则和状态发送 `PW_FeatureFlagImpression` 事件。返回一个 promise。