# @bucketco/browser-sdk 中文文档

规范地址：https://npmcn.com/package/%40bucketco/browser-sdk/

版本：3\.3\.4
npm 元数据更新时间：2025-09-02T20:50:27.000Z
中文译文更新时间：2026-11-08T18:36:57.713Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bucketco/browser-sdk
原文对照：https://npmcn.com/package/%40bucketco/browser-sdk/?lang=original
项目主页：https://github.com/bucketco/bucket-javascript-sdk#readme
源码仓库：https://github.com/bucketco/bucket-javascript-sdk

弃用说明：This package has been moved to @reflag/browser-sdk\. Please upgrade\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，141 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2024-07-31T12:57:27.147Z
- 最新版本发布：2025-08-26T13:43:24.229Z
- 近 30 天下载量：5036（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 0 个）

## 中文简介

Bucket.co的基本客户端. 如果你在使用回放,你将会更好 与Bucket回放SDK.

## 安装

```sh
npm install @bucketco/browser-sdk
```

也可以使用：`pnpm add @bucketco/browser-sdk`、`yarn add @bucketco/browser-sdk`、`bun add @bucketco/browser-sdk`

## README

# Bucket 浏览器 SDK

Bucket.co的基本客户端. 如果你在使用回放,你将会更好 与Bucket回放SDK.

Bucket 支持特性拖动、跟踪特性使用, [收集反馈](https://npmcn.com/package/%40bucketco/browser-sdk/#readme-qualitative-feedback) 关于特征,以及 [远程配置特性](https://npmcn.com/package/%40bucketco/browser-sdk/#readme-remote-config-beta)。 。 。 .

## 安装

先找到你们的 `publishableKey` 下级 [环境设置](https://app.bucket.co/env-current/settings/app-environments) 在巴凯特.

包可以直接导入或用在 HTML 脚本标签中 :

A. 导入模块:

```typescript
import { BucketClient } from "@bucketco/browser-sdk";

const user = {
  id: 42,
  role: "manager",
};

const company = {
  id: 99,
  plan: "enterprise",
};

const bucketClient = new BucketClient({ publishableKey, user, company });

await bucketClient.initialize();

const {
  isEnabled,
  config: { payload: question },
  track,
  requestFeedback,
} = bucketClient.getFeature("huddle");

if (isEnabled) {
  // Show feature. When retrieving `isEnabled` the client automatically
  // sends a "check" event for the "huddle" feature which is shown in the
  // Bucket UI.

  // On usage, call `track` to let Bucket know that a user interacted with the feature
  track();

  // The `payload` is a user-supplied JSON in Bucket that is dynamically picked
  // out depending on the user/company.
  const question = payload?.question ?? "Tell us what you think of Huddles";

  // Use `requestFeedback` to create "Send feedback" buttons easily for specific
  // features. This is not related to `track` and you can call them individually.
  requestFeedback({ title: question });
}

// `track` just calls `bucketClient.track(<featureKey>)` to send an event using the same feature key
// You can also use `track` on the client directly to send any custom event.
bucketClient.track("huddle");

// similarly, `requestFeedback` just calls `bucketClient.requestFeedback({featureKey: <featureKey>})`
// which you can also call directly:
bucketClient.requestFeedback({ featureKey: "huddle" });
```

B. 脚本标记( html 中的客户端)

见 [示例/浏览器.html](https://github.com/bucketco/bucket-javascript-sdk/tree/main/packages/browser-sdk/example/browser.html) 实例:

```html
<script src="https://cdn.jsdelivr.net/npm/@bucketco/browser-sdk@2"></script>
<script>
  const bucket = new BucketBrowserSDK.BucketClient({
    publishableKey: "publishableKey",
    user: { id: "42" },
    company: { id: "1" },
  });

  bucket.initialize().then(() => {
    console.log("Bucket initialized");
    document.getElementById("loading").style.display = "none";
    document.getElementById("start-huddle").style.display = "block";
  });
</script>
<span id="loading">Loading...</span>
<button
  id="start-huddle"
  style="display: none"
  onClick="bucket.track('Started huddle')"
>
  Click me
</button>
```

### 输入选项

向建筑商的电话提供这些:

```typescript
type Configuration = {
  logger: console; // by default only logs warn/error, by passing `console` you'll log everything
  apiBaseUrl?: "https://front.bucket.co";
  sseBaseUrl?: "https://livemessaging.bucket.co";
  feedback?: undefined; // See FEEDBACK.md
  enableTracking?: true; // set to `false` to stop sending track events and user/company updates to Bucket servers. Useful when you're impersonating a user
  fallbackFeatures?:
    | string[]
    | Record<string, { key: string; payload: any } | true>; // Enable these features if unable to contact bucket.co. Can be a list of feature keys or a record with configuration values
  timeoutMs?: number; // Timeout for fetching features (default: 5000ms)
  staleWhileRevalidate?: boolean; // Revalidate in the background when cached features turn stale to avoid latency in the UI (default: false)
  staleTimeMs?: number; // at initialization time features are loaded from the cache unless they have gone stale. Defaults to 0 which means the cache is disabled. Increase this in the case of a non-SPA
  expireTimeMs?: number; // In case we're unable to fetch features from Bucket, cached/stale features will be used instead until they expire after `expireTimeMs`. Default is 30 days
  offline?: boolean; // Use the SDK in offline mode. Offline mode is useful during testing and local development
};
```

## 特性切换

Bucket决定一个给定用户/公司的哪些功能是活动的. 用户/公司在 BucketClient 构建器中给出.

如果你提供 `user` 或者说 `company` 对象,它们必须至少包括 `id` 否则,它们将被完全忽略. 计外 `id`,您还必须提供您想要评估特性目标设定规则的附加条件.

属性不能被嵌入(多等),必须是字符串,整数或布尔. 一些属性是特殊的,并在 Bucket UI 中使用:

-   `name` -- 显示名称 `user`编号 :`company`, (中文(简体) ),
-   `email` - 已接受 `user`s,如果可用,将在 Bucket UI 中突出显示,
-   `avatar` - 两者均可提供 `user` 财务报告和审定财务报表 `company` 并应该成为图像的 URL.

```ts
const bucketClient = new BucketClient({
  publishableKey,
  user: {
    id: "user_123",
    name: "John Doe",
    email: "john@acme.com"
    avatar: "https://example.com/images/udsy6363"
  },
  company: {
    id: "company_123",
    name: "Acme, Inc",
    avatar: "https://example.com/images/31232ds"
  },
});
```

检索特征及其目标信息 `getFeature(key: string)`数字 :

```ts
const huddle = bucketClient.getFeature("huddle");
// {
//   isEnabled: true,
//   config: { key: "zoom", payload: { ... } },
//   track: () => Promise<Response>
//   requestFeedback: (options: RequestFeedbackData) => void
// }
```

你用得着 `getFeatures()` 以获取当前所有启用的特性.

```ts
const features = bucketClient.getFeatures();
// {
//   huddle: {
//     isEnabled: true,
//     targetingVersion: 42,
//     config: ...
//   }
// }
```

`getFeatures()` 意思是比 `getFeature()` 并且它通常使用 由下游客户端, 如反应SDK.

注意获取 `isEnabled` 在返回的对象上 `getFeatures` 不自动 生成一个 `check` 事件,与 `isEnabled` 返回对象上的财产 `getFeature`。 。 。 .

## 远程配置

远程配置是一种动态而灵活的配置应用程序外的特征行为的方法 — — 不需要重新配置它.

类似 `isEnabled`,每个特性都有 `config` 属性。 此配置由 Bucket 内部管理 . 它的管理方式类似于对特性的访问的管理方式, 而不是二进制 `isEnabled` 你可以拥有 向不同的用户/公司提供的多个配置值.

```ts
const features = bucketClient.getFeatures();
// {
//   huddle: {
//     isEnabled: true,
//     targetingVersion: 42,
//     config: {
//       key: "gpt-3.5",
//       payload: { maxTokens: 10000, model: "gpt-3.5-beta1" }
//     }
//   }
// }
```

`key` 用于配置,但如果一个特性没有配置或没有配置值与上下文相匹配,则 `key` 将会是 `undefined`。在试图在应用程序中使用配置时,请检查此大小写. `payload` 是任意配置需要的可选 JSON 值.

碞钩 `isEnabled`,访问 `config` 在返回的对象上 `getFeatures` 不自动 生成一个 `check` 事件,与 `config` 返回对象上的财产 `getFeature`。 。 。 .

## 更新用户/公司/其他上下文

BucketClient 构造器中为用户/公司/其他上下文给出的属性可以更新,用于特性目标评价 `updateUser()`, (中文(简体) ), `updateCompany()` 财务报告和审定财务报表 `updateOtherContext()` 方法。 。 . 他们回到一个承诺,一旦特性在属性更新后被重新评价就解决了.

以下显示如何让用户自行选择新功能. 特征必须有规则 `voiceHuddleOptIn IS true` 设置在 Bucket UI 中.

```ts
// toggle opt-in for the voiceHuddle feature:
const { isEnabled } = bucketClient.getFeature("voiceHuddle");
// this toggles the feature on/off. The promise returns once feature targeting has been
// re-evaluated.
await bucketClient.updateUser({ voiceHuddleOptIn: (!isEnabled).toString() });
```

> \[!注\] `user`编号 :`company` 属性也远程存储在 Bucket 服务器上,如果页面被刷新,将自动用于评价特性目标.

## 工具栏

Bucket工具栏非常适合自己在上/下移动特性,以确保在特性打开和关闭时,一切都能奏效.

![Toolbar screenshot](https://github.com/user-attachments/assets/c223df5a-4bd8-49a1-8b4a-ad7001357693)

工具栏将自动显示在 `localhost`然而,它也可以在生产中令人难以置信地有用. 你完全控制 当它出现通过 `toolbar` 配置选项传递到 `BucketClient`。 。 。 .

您可以通过一个简单的布尔来强制工具栏出现/消失 :

```typescript
const client = new BucketClient({
  // show the toolbar even in production if the user is an internal/admin user
  toolbar: user?.isInternal,
  ...
});
```

您也可以配置屏幕上工具栏的位置 :

```typescript
const client = new BucketClient({
  toolbar: {
    show: true;
    position: {
      placement: "bottom-left",
      offset: {x: "1rem", y: "1rem"}
    }
  }
  ...
})
```

见 [参考文献](https://docs.bucket.co/supported-languages/browser-sdk/globals#toolbaroptions) 详细情况.

## 关于β特征的定性反馈

Bucket 能够以 a 的形式收集用户的质量反馈 [客户满意度](https://en.wikipedia.org/wiki/Customer_satisfaction) 和评论.

### 自动收集反馈

Bucket浏览器SDK带有默认启用的自动反馈收集模式,这使得Bucket服务在用户使用过相关功能后,就要求用户反馈.

> \[注\] 要从自动反馈收集开始, 确保您已经设置 `user` 输入 `BucketClient` 建筑师.

自动反馈调查即使没有利用SDK向Bucket发送事件,也能奏效. 它之所以有效,是因为 Bucket 浏览器 SDK 维持着与 Bucket 服务器的活连接,并且可以自动显示当 Bucket 服务器确定某一事件应触发一个快讯时的回馈快讯- 不管该事件是如何发送到 Bucket 的.

您可以找到所有选项来更改默认行为 [Bucket 反馈文档](https://npmcn.com/package/%40bucketco/browser-sdk/FEEDBACK.md)。 。 。 .

### Bucket 反馈 UI

Bucket可以通过提供预建的UI来帮助您收集用户的反馈,允许您以最小的代码和努力开始.

[读取 Bucket 反馈 UI 文档](https://npmcn.com/package/%40bucketco/browser-sdk/FEEDBACK.md)

### Bucket 反馈 SDK

可以使用 SDK 向 Bucket 提交反馈 :

```ts
bucketClient.feedback({
  featureKey: "my-feature-key", // String (required), copy from Feature feedback tab
  score: 5, // Number: 1-5 (optional)
  comment: "Absolutely stellar work!", // String (optional)
});
```

### Bucket 反馈 API

如果您没有使用 Bucket 浏览器 SDK, 您仍然可以使用 HTTP API 提交反馈 .

详情见 [反馈 HTTP API](https://docs.bucket.co/api/http-api#post-feedback)

## 跟踪功能使用情况

这个 `track` 函数允许您向 Bucket 发送事件以表示特性使用. 默认 Bucket 期望事件名称与特性密钥一致, 但是 可以随意定制.

```ts
bucketClient.track("huddle", { voiceHuddle: true });
```

## 活动听众

事件听众可以捕捉发生在 `BucketClient`。这有利于与其他系统建立集成或用于各种调试目的。 有5种活动:

-   `check`: 您使用的代码 `isEnabled` 或者说 `config` 特性
-   `featuresUpdated`: 特性已更新。 要么是作为初始化的一部分加载,要么是用户/公司更新
-   `user`: 用户信息更新(类似于 `identify` 用于跟踪术语的电话)
-   `company`: 公司信息更新(有时更新到 `group` 用于跟踪术语的电话)
-   `track`: 发生了音轨事件.

使用 `on()` 用于添加事件听众的方法,以响应某些事件。 每个钩子上的细节参见API参考.

```ts
import { BucketClient, CheckEvent, RawFeatures } from "@bucketco/browser-sdk";

const client = new BucketClient({
  // options
});

// or add the hooks after construction:
const unsub = client.on("check", (check: CheckEvent) =>
  console.log(`Check event ${check}`),
);
// use the returned function to unsubscribe, or call `off()` with the same arguments again
unsub();
```

## 无 PII

Bucket 浏览器 SDK 不收集任何元数据, HTTP IP 地址是 _没有_ 被存储.

为了跟踪个别用户,我们建议使用类似数据库ID作为用户ID,因为它是独一无二的,并且不包括任何PII(个人可识别信息). 但如果您使用电子邮件地址作为用户ID, 但不愿将任何 PII 发送到 Bucket, 您可以在发送到 Bucket 之前将敏感数据散开 :

```ts
import bucket from "@bucketco/browser-sdk";
import { sha256 } from "crypto-hash";

bucket.user(await sha256("john_doe"));
```

## 饼干的使用

Bucket浏览器SDK使用一对饼干支持自动反馈调查. 这些饼干不用于跟踪目的,因此不需要以饼干同意表出现.

两个饼干是:

-   `bucket-prompt-${userId}`: 存储最近收到的自动反馈即时消息ID,以避免重复调查
-   `bucket-token-${userId}`: 缓存用于连接Bucket的活口信箱基础设施的活口信箱,用于实时提供自动反馈调查.

## 从2.x升级到3.0

中断更改 :

-   `client.onFeaturesUpdated()` 现在替换为 [事件听众](https://npmcn.com/package/%40bucketco/browser-sdk/#readme-event-listeners)
-   对 `BucketClient` 原列在 `featureOptions` 现在直接在根中提供.

## 类型脚本

类型被捆绑到库中,并在通过包管理器导入时自动被曝光.

## 内容安全政策

如果您在网站上使用严格的内容安全政策, 您需要启用这些指令才能使用 SDK :

| 指令 | 数值 | 原因 |
| --- | --- | --- |
| 连接弧 | [https://front.bucket.co (中文(简体) )](https://front.bucket.co/) | 基本功能 ' |
| 连接弧 | [https://livemessage.bucket.co 互联网档案馆的存檔,存档日期2013-12-22](https://livemessaging.bucket.co/) | 服务器发送事件用于自动反馈调查,这允许在用户使用特性时自动收集反馈. |
| 样式弧 | "不安全入内" | 反馈的 UI 有内线样式的样式. 没有此指令结果未设置 HTML 元素 . |

如果你把追踪SDK的火桶 加上 `<script>`\-来自 `jsdelivr.net` 您还需要:

| 指令 | 数值 | 原因 |
| --- | --- | --- |
| 脚本- src- elem | [https://cdn.jsdelivr.net (中文(简体) )](https://cdn.jsdelivr.net/) | 从 CDN 装入 Bucket SDK |

## 许可证

> MIT 许可证 版权(c)2025 Bucket Aps

## 常见问题

### @bucketco/browser-sdk 是什么？

Bucket\.co的基本客户端\. 如果你在使用回放,你将会更好 与Bucket回放SDK\.注意：该包已被作者标记为弃用——This package has been moved to @reflag/browser-sdk\. Please upgrade\.

### 如何安装 @bucketco/browser-sdk？

在项目目录运行 npm install @bucketco/browser-sdk，或使用 pnpm add / yarn add / bun add。

### @bucketco/browser-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bucketco/browser-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bucketco/browser-sdk 可以商用吗？

@bucketco/browser-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bucketco/browser-sdk 的下载量有多少？

根据 npm 官方下载统计，@bucketco/browser-sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,036 次，日均约 168 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bucketco/browser-sdk 还在维护吗？

最新版本 3\.3\.4 发布于 2025/08/26（1\.2 年前）；至今共发布 33 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。