Bucket 浏览器 SDK

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

Bucket 支持特性拖动、跟踪特性使用, 收集反馈 关于特征,以及 远程配置特性。 。 。 .

安装

先找到你们的 publishableKey 下级 环境设置 在巴凯特.

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

A. 导入模块:

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 实例:

<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>

输入选项

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

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 - 已接受 users,如果可用,将在 Bucket UI 中突出显示,
• avatar - 两者均可提供 user 财务报告和审定财务报表 company 并应该成为图像的 URL.

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

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

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

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

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

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

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

远程配置

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

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

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 中.

// 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工具栏非常适合自己在上/下移动特性,以确保在特性打开和关闭时,一切都能奏效.

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

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

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

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

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

见 参考文献 详细情况.

关于β特征的定性反馈

Bucket 能够以 a 的形式收集用户的质量反馈 客户满意度 和评论.

自动收集反馈

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

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

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

您可以找到所有选项来更改默认行为 Bucket 反馈文档。 。 。 .

Bucket 反馈 UI

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

读取 Bucket 反馈 UI 文档

Bucket 反馈 SDK

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

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

跟踪功能使用情况

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

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

活动听众

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

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

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

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 之前将敏感数据散开 :

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() 现在替换为 事件听众
• 对 BucketClient 原列在 featureOptions 现在直接在根中提供.

类型脚本

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

内容安全政策

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

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

许可证

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