@featbit/js-client-sdk

中文文档

4.4.2发布于 2026/11/03MITTypeScriptESM + CJS近 30 天下载 7.9万

https://github.com/featbit/featbit-js-client-sdk 互联网档案馆的存檔,存档日期2013-12-22

文档目录22 节

导言
开始
安装
先决条件
快速启动
实例
SDK 软件
Fb 用户
诱饵
锁定器
评价
离线模式
保留用户缓存
存档并删除了旗帜
活动
初始化后切换用户
数据同步
网络故障处理
禁用事件收藏
实验(A/B/n测试)
获得支持
另见

请注意

如果您正在使用 SDK 的 v1 或 v2, 请参见此医生

JavaScript 的 FeatBit 客户端 SDK

导言

这是100%开源功能旗管理平台的客户端- Side SDK 费特比特。。。 .

要注意,这是客户端SDK,它旨在用于单个用户上下文,可以是移动,桌面或嵌入式应用程序. 这个SDK只能运行在浏览器环境中,不适合NodeJs应用.

开始

安装

npm install --save @featbit/js-client-sdk

先决条件

在使用SDK之前,需要获得环境秘密(sdkKey)和SDK URL.

遵循以下文档获取这些值

快速启动

以下代码显示: @featbit/js-client-sdk。。。 .

import { FbClientBuilder, UserBuilder } from "@featbit/js-client-sdk";

const bob = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .custom('age', '18')
    .custom('country', 'FR')
    .build();

// setup SDK client with websocket streaming
const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .streamingUri('ws://localhost:5100')
    .eventsUri("http://localhost:5100")
    .user(bob)
    .build();

(async () => {
  // wait for the SDK to be initialized
  try {
    await fbClient.waitForInitialization();
  } catch(err) {
    // failed to initialize the SDK
    console.log(err);
  }

  // flag to be evaluated
  const flagKey = "game-runner";

  // evaluate a feature flag for a given user
  const boolVariation = await fbClient.boolVariation(flagKey, false);

  // switch user
  const alice = new UserBuilder('another-unique-key-of-user')
      .name('alice')
      .custom('country', 'UK')
      .custom('age', 36)
      .build();
  
  await fbClient.identify(alice);
})();

实例

网络应用
关于如何使用 FeatBit with React,请参见反应 - 客户端 - sdk

SDK 软件

Fb 用户

这个 FbClient 是提供 FeatBit 服务器访问的 SDK 的核心。申请应在申请的周期内立即提出一个实例.

FbClientBuilder 用于构建一个 FbClient 举个例子构建者将显示配置 SDK 的方法,并最终创建 FbClient 举个例子.

使用流线的 FbClient

import { FbClientBuilder, UserBuilder } from "@featbit/js-client-sdk";

const user = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .build();
    
const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .streamingUri('ws://localhost:5100')
    .eventsUri("http://localhost:5100")
    .user(user)
    .build();

使用投票的 Fb 客户端

import { FbClientBuilder, UserBuilder, DataSyncModeEnum } from "@featbit/js-client-sdk";

const user = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .build();

const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .dataSyncMode(DataSyncModeEnum.POLLING)
    .pollingUri('http://localhost:5100')
    .eventsUri("http://localhost:5100")
    .pollingInterval(10000)
    .build();

与倒计时相接

在使用流模式时,如果启动时无法建立WebSocket连接,SDK可以自动倒回投票. 这是 默认禁用 必须明确启用.

注: pollingUri 在允许投票倒计时必须设定,否则倒计时没有投票终点.

import { FbClientBuilder, UserBuilder } from "@featbit/js-client-sdk";

const user = new UserBuilder('a-unique-key-of-user')
    .name('bob')
    .build();

// opt in to polling fallback — pollingUri is required
const fbClient = new FbClientBuilder()
    .sdkKey("your_sdk_key")
    .streamingUri('ws://localhost:5100')
    .pollingUri('http://localhost:5100')   // required for fallback
    .eventsUri("http://localhost:5100")
    .enablePollingFallback(true)
    .user(user)
    .build();

用户

IUser 定义正在评价特征标记的用户的属性。 IUser有两个内置属性:密钥和名. 一个IUser唯一的强制属性是密钥,密钥必须单独识别每个用户.

除了这些内置属性外,您还可以使用 custom(string key, string value) 方法。内置属性和自定义属性都可以在瞄准规则中被引用,并包含在分析数据中.

UserBuilder 用于构建一个 IUser 举个例子构建者暴露出配置 IUser 的方法,最后创建 IUser 实例.

import { UserBuilder } from "@featbit/js-client-sdk";

const bob = new UserBuilder("unique_key_for_bob")
    .name("Bob")
    .custom('age', 18)
    .custom('country', 'FR')
    .build();

诱饵

如果您已经拥有可用的特性标记,您可以将其传递给 SDK 而不是从远程请求 .

注: 有效的缓存快照优先于靴子陷阱,包括空快照或存档旗. 只有当不存在有效的缓存且存储为空时才会使用 Bootstrap. 远程值用相同的密钥来替换靴子值; 仅本地的靴子值从远程全快照中幸存了省略值。一旦一个远程值或归档替换了靴子值,之后的完整快照并不能恢复该靴子值.

// define the option with the bootstrap parameter
const options = {
  ...
  bootstrap = [{
    // feature flag key name
    id: string,
    // variation value
    variation: string,
    // variation data type, string will be used if not specified
    variationType: VariationDataType
  }]
}

const fbClient = new FbClientBuilder(options).build();
// or
const fbClient = new FbClientBuilder()
    //... other options
    .bootstrap(options.bootstrap)
    .build();

锁定器

默认日志使用无作为日志级别,这意味着它不会输出任何东西。如果默认日志不符合您的需要, 您有两个选项 .

使用不同的日志级别

const fbClient = new FbClientBuilder()
    .logLevel('debug') // possible log levels: 'debug', 'info', 'warn', 'error', 'none'
    ...
    .build();

// or
const options = {
  ...
  logLevel: 'debug'
}

const fbClient = new FbClientBuilder(options).build();

定义自己的日志

您的日志必须执行 ILOGER 浏览器 界面,我们提供了 Basic 潜行器你可以像这样使用:

const logger = new BasicLogger({
    level: 'debug', // possible log levels: 'debug', 'info', 'warn', 'error', 'none'
    destination: console.log
});

const fbClient = new FbClientBuilder()
    .logger(logger)
    ...
    .build();

// or
const options = {
  ...
  logger: logger
}

const fbClient = new FbClientBuilder(options).build();

注意日志选项的优先级高于日志级。如果您通过两个选项, 日志级将被忽略 .

评价

初始化后,SDK在当地拥有了所有的特性旗,不需要请求远程服务器来进行任何特性旗评价. 所有评价都是在当地同步进行的,平均评价时间不到一毫秒.

有一个 variation 返回旗帜值的方法,以及 variationDetail 返回对象的方法说明如何为每种类型确定数值.

bulVariation/boolVariation 详情
字符串变化/字符串变化
数字变化/数字变化
json 变化/json 变化

变位调取特性旗键和默认值. 如果有任何错误,则无法评价旗帜(例如,特性旗帜密钥不匹配任何已存在的旗帜),默认值会被返回.

// flag to be evaluated
const flagKey = "game-runner";

// evaluate a feature flag for a given user
const boolVariation = await fbClient.boolVariation(flagKey, false);

// evaluate a boolean flag for a given user with evaluation detail
const boolVariationDetail = await fbClient.boolVariationDetail(flagKey, false);

离线模式

在某些情况下,你可能要停止远程呼叫费特比特。这是如何:

import { FbClientBuilder } from "@featbit/browser-server-sdk";

const fbClient = new FbClientBuilder()
    //... other options
    .offline(true)
    .build();

当启用离线模式时,您应该向旗下提供拖带选项, 否则,SDK会归还你传递给 variation 方法.

保留用户缓存

内置商店默认最多保留了5个用户上下文,包括当前上下文. 一个上下文包括用户的属性,因此改变属性可以选择另一个缓存条目. 历史条目在7天后失效,未经选择或更新. 配置这些限制与 .maxCachedUsers(5) 财务报告和审定财务报表 .userCacheTtl(7 * 24 * 60 * 60 * 1000),或相应的构造器选项。这两个值必须是正安全整数;TTL为毫秒.

选项/构建方法	默认	目的
`maxCachedUsers`	`5`	最大保留用户上下文,包括当前上下文
`userCacheTtl`	`604800000` (7天) (中文(简体) )	历史用户缓存已过期, 以毫秒计
`fullSyncInterval`	`86400000` (24小时)	在线全刷新间隔, 以毫秒为单位, 有 ± 10% 的焦距

无效值会回落到默认值,并通过所配置的日志报告 .

这些选项适用于内置商店,而不是应用程序自定义的自定义商店.

存档并删除了旗帜

当服务器响应标记了旗帜时 matchReason: "flag archived",内置商店删除其完整的评价数据,只保留其密钥,版本,出处和存档标记. 变异方法返回提供的默认值,以及 getAllVariations() 不包括旗帜。该标记使更古老的补丁无法将旗帜带回. 后被接受的无存档值使其再次被提供.

一个成功的全快照可以去除被服务器省略的远程旗帜和归档标记. 这将调和断开时丢失的删除或归档更改。在SDK收到存档更新或权威全快照之前,缓存值仍然可以返回;定期刷新不是立即删除通知. 已归档的标记保留在活动快照内,直到被更新的数据所取代或被完整的快照所去掉. 历史用户缓存以计数和闲置时间为界,不是字节大小.

活动

等着准备

要了解客户端何时准备好,可以使用两种机制之一:事件或承诺.

客户对象可以放出JavaScript事件. 当它从服务器接收到初始旗下值时, 它会发出一个已准备好的事件。您可以聆听此事件以确定客户端何时准备好评价旗帜 .

fbClient.on('ready', () => {
  var flagValue = fbClient.variation("YOUR_FEATURE_KEY", defaultValue);
});

或者, waitForInitialization() 在当前用户上下文初始化成功后与客户端解决。使用 getAllVariations() 以获取评估过的旗帜。离线初始化使用缓存或靴子化数据. 每个识别开始一个新的准备周期.

await fbClient.waitForInitialization();
const featureFlags = await fbClient.getAllVariations();

初始化在无法恢复的同步错误或何时失败 startWaitTime 过期( 默认为5秒) 。初始化超时不能停止背景同步;后期成功响应可以使客户端做好准备. 关闭客户端或启动另一个 DID 拒绝未完成的初始化等待 .

订阅是注册在 on,例如UI组件需要重读一面旗帜. 承诺答复最多一次发出 update 包含平面的事件 string[] 键,然后是 update:<key> 每个键。听者看到全部承诺的批量。变化包括增加,去除/存档,还原,或价值或价值类型的变化. 重复的存档,拒绝的 stale 补丁,或者只使用元数据的更改不会发出更新.

对于已存档或已删除的密钥,在调用器内重新读取返回提供的默认值。完整快照可能会释放服务器省略了旗帜的去除事件. 切换用户也可能在所选缓存不同时发出变化.

有两种订阅表格:

订阅任何特性旗的更改

fbClient.on('update', (keys: string[]) => {
  // do something when any feature flag changes
});

订阅特定特性旗的更改

// replace feature_flag_key with your feature flag key
fbClient.on('update:feature_flag_key', (key) => {
  const myFeature = fbClient.variation('feature_flag_key', defaultValue);
});

初始化后切换用户

如果用户在经过了某些过程后有所改变,例如登录,可以使用以下方法在初始化后设置用户.

await fbClient.identify(user);

数据同步

我们用 网络安全套 或者说投票 ,使本地数据与服务器同步,然后默认将其存储到本地Storage。当特性旗或其相关数据有任何更改时,此更改会被推向 SDK,平均同步时间会少于 百分点 如果配置了 WebSocket 。但一旦问题消失, 便会自动恢复.

内置同步器在启动时和每次启动后请求完整快照 identify,即使缓存光标存在。在获取快照时仍然可以使用现有旗帜。普通重联使用递增同步,直到下一次完全刷新到期.

完全刷新默认为24小时,随机时间为±10%。以毫秒配置间隔 new FbClientBuilder({ fullSyncInterval: 24 * 60 * 60 * 1000 }) 或者说 .fullSyncInterval(...);必须是正安全整数。只有成功承诺的完整响应重排间隔。补丁响应, HTTP 304, 和失败的请求留下全部更新等待。一个空的全快照会去掉以前的远程旗帜,然后将光标重置为零.

流取刷新取代了WebSocket连接并请求时间戳为0,每30秒重试一次等待的全刷新. 投票要求获得下一次预定投票的完整快照。两种模式在页面可见或被恢复时检查过期,投票倒计时共享相同的刷新状态. 关闭客户端会删除刷新的计时器和页面收听器;离线模式将不创建. 自定义同步器必须执行自己的刷新调度 .

网络故障处理

由于所有数据都在当地存储在本地Storage中,在以下情况下,当暂时没有互联网连接时,SDK仍然会工作:

它已经收到以前连接的数据
页:1 fbClient.bootstrap(featureFlags) 方法使用所有必要的特征标记

在此期间,SDK会尝试以递增间隔重新连接到服务器,这可以确保网络连接恢复后网络口被恢复.

禁用事件收藏

默认情况下,SDK会自动向FeatBit服务器发送事件(旗下评价事件和A/B测试的度量事件),除非SDK处于离线模式.

如果您喜欢在SDK处于在线模式时禁用此事件收藏, 您可以使用 disableEvents 选项.

import { FbClientBuilder } from "@featbit/browser-server-sdk";

const fbClient = new FbClientBuilder()
        .disableEvents(true)
        .build();

旗子评价事件收藏也由每个旗子控制 insightsEnabled 从 FeatBit 服务器收到的设置 :

false: 禁用该旗帜的评价事件收藏,而不改变其评价结果.
true 或缺:允许评价事件收集,但需启用全SDK事件收集.

disableEvents 必须是 false (默认)和SDK必须在线供每个旗子的见解来收集评价事件. 设置 insightsEnabled 改为 true 不覆盖 disableEvents 或离线模式。这个 insightsEnabled 设置不影响自定义的度量事件 track();这些仍受SDK全局事件收集设置的约束.

实验(A/B/n测试)

我们支持网页浏览和点击的自动实验, 你只需要把你的实验设置在我们SaaS平台上, 那你应该可以在实验开始后近实时看到结果.

如果你需要更多的控制实验数据发送到我们的服务器, 我们提供一个方法发送自定义事件.

fbClient.track(eventName, numericValue);

数值 ,默认值为 1.0 国家。。。 .

确保 track 在调用相关特性旗后调用, 否则自定义事件将不会包含进入实验结果.

获得支持

如果你有关于使用这个sdk的具体问题我们鼓励你改为趁机问吧。。。 .
如果您遇到错误或想要请求特性, 提交问题。。。 .

另见

连接到 JavaScript Sdk

版本与发布记录

@featbit/js-client-sdk 共发布 47 个版本，首次发布于 2024/04/15；过去 12 个月发布了 22 个版本。

版本	发布日期	距今
`4.4.2`latest	2026/11/03	10 天前
`4.4.1`	2026/10/31	14 天前
`4.4.0`	2026/10/30	15 天前
`4.3.6`	2026/10/19	26 天前
`4.3.5`	2026/08/17	2 个月前
`4.3.4`	2026/08/17	2 个月前

关于 @featbit/js-client-sdk 的常见问题